Required foundation for v4 to v5: partial error support and route classifier

[sean-]

Summary

Adds two features that make the Go client more useful for production consumers:

• Partial failure errors in opensearchapi/ — PartialBulkError, PartialSearchError, and ShardFailureError types returned from API methods when Config.ReturnQueryErrors is set, so callers only need if err != nil. Both (resp, err) are non-nil on partial failure — the response is fully populated. Controllable via OPENSEARCH_GO_PARTIAL_QUERY_ERRORS env var (overrides config) for deploy-time toggling.

• OperationClassifier in opensearchtransport/ — A bit-packed OperationID type and exported classifier that maps any HTTP method+path to a structured operation identifier. Enables transparent metrics, tracing, and access-control middleware at the http.RoundTripper layer without per-operation wrapper code.

• OPENSEARCH_GO_ROUTER env var — Enable the DefaultRouter (connection-scoring, role-aware routing) without code changes by setting OPENSEARCH_GO_ROUTER=true. Programmatic Config.Router takes precedence. Transitional: off by default in v4, on by default in v5, removed in v6.

All three features are additive and backward-compatible. Existing code is unaffected unless the caller opts in to ReturnQueryErrors or OPENSEARCH_GO_ROUTER=true.

Ref: opensearch-project#816

Motivation

Partial failures require two error checks

OpenSearch returns HTTP 200 for partial failures — bulk item errors, shard failures on search, replica failures on writes. This forces non-idiomatic double-checking:

resp, err := client.Bulk(ctx, req)
if err != nil { return err }        // check 1: transport/HTTP errors
if resp.Errors { /* check 2 */ }    // easy to forget

Go convention (io.Reader.Read, json.Decoder.Decode) is to return (result, error) where both can be non-nil. The caller should only need if err != nil.

No way to identify the operation from an HTTP request

Middleware that wraps http.RoundTripper (metrics, tracing, audit logging) needs to know which OpenSearch operation a request represents. Today the only option is to re-parse the URL path with hand-written regexes, which is fragile and incomplete. The transport already has a trie-based route matcher. Exposing a read-only classifier that reuses this trie gives middleware a zero-allocation, O(path-segments) lookup that stays in sync with the canonical route table.

Changes

opensearchapi/ — Partial failure errors

File	Change
errors.go (new)	PartialFailureError interface, PartialBulkError, PartialSearchError, ShardFailureError, operation constants, helpers
errors_test.go (new)	Table-driven tests (external _test package): interface compliance, errors.As, all helpers, edge cases
errors_internal_test.go (new)	Internal test: resolveReturnQueryErrors env var priority (env > config > default), strconv.ParseBool edge cases
opensearchapi.go	Config.ReturnQueryErrors, resolveReturnQueryErrors() with OPENSEARCH_GO_PARTIAL_QUERY_ERRORS env var, updated constructors
api_bulk.go	Return PartialBulkError when data.Errors && returnQueryErrors
api_search.go	Return PartialSearchError when Shards.Failed > 0 && returnQueryErrors
api_index.go	Return ShardFailureError when Shards.Failed > 0 && returnQueryErrors
api_document.go	Return ShardFailureError for Create and Delete
api_update.go	Return ShardFailureError when Shards.Failed > 0 && returnQueryErrors
api_scroll.go	Return PartialSearchError for Scroll.Get
api_search-template.go	Return PartialSearchError when Shards.Failed > 0 && returnQueryErrors
api_msearch.go	Return PartialSearchError with aggregated shard failures across sub-responses
api_msearch-template.go	Return PartialSearchError with aggregated shard failures across sub-responses

opensearchtransport/ — Operation classifier

File	Change
operation.go (new)	OperationID type, bit layout, categories, minors, ~200 composed Op constants, String()
classify.go (new)	OperationClassifier, NewOperationClassifier(), Classify()
classify_test.go (new)	Table-driven tests: all operation IDs, masking, String(), concurrent safety
policy_mux_trie.go	Add operationID OperationID to trieLeaf and trieMatch
policy_mux.go	Add OpID() to Route interface, Op() builder method on RouteBuilder
policy_mux_trie_test.go	Updated add() call signatures
policy_mux_internal_test.go	OpID() on mock route type
router.go	.Op(OpXxx) on all ~124 routes in buildRoleRoutes()
feature_config.go	envRouter constant with v4/v5/v6 lifecycle doc comment
opensearchtransport.go	Auto-create NewDefaultRouter() in New() when env var is truthy and no programmatic router set
router_coverage_internal_test.go	4 test cases: true→created, false→nil, unset→nil, programmatic precedence
doc.go	New "Enabling the Router via Environment Variable" godoc section

Documentation

File	Change
CHANGELOG.md	Entries for both features + env var
UPGRADING.md	v5 migration guide for ReturnQueryErrors default flip
USER_GUIDE.md	ReturnQueryErrors in example config, env var table, Operation Classifier section
guides/error_handling.md	New "Automatic Partial Failure Errors" section with examples, error type reference, env var
guides/routing.md	Env-var quick start section with v6 removal note
UPGRADING.md	v5 migration guide for ReturnQueryErrors default flip; router env var with v6 removal note
USER_GUIDE.md	ReturnQueryErrors in example config, env var table (including OPENSEARCH_GO_ROUTER), Operation Classifier section

Migration path

• v4.x: ReturnQueryErrors defaults to false. Users opt in via Config or OPENSEARCH_GO_PARTIAL_QUERY_ERRORS=true. Zero breaking changes.
• v4.x (router): DefaultRouter is off. Users opt in via Config.Router = NewDefaultRouter() or OPENSEARCH_GO_ROUTER=true.
• v5.0: Flip default to true. Users who need the old behavior set ReturnQueryErrors: false or OPENSEARCH_GO_PARTIAL_QUERY_ERRORS=false.
• v5.0 (router): DefaultRouter flips to on. Users who need the old behavior set OPENSEARCH_GO_ROUTER=false.
• v6.0 (router): OPENSEARCH_GO_ROUTER env var removed. Router is unconditionally on; use OPENSEARCH_GO_POLICY_* to disable individual policies.
• v6.0 (router): OPENSEARCH_GO_ROUTER env var removed. Router is unconditionally on; use OPENSEARCH_GO_POLICY_* to disable individual policies.