Add x-error-responses partial-failure error mask

OpenSearch returns HTTP 200 for partial successes -- bulk item failures,
search-shard failures, single-doc replica failures -- so callers must
remember a second check after `err == nil`. v4 added an opt-in boolean
(Config.ReturnQueryErrors) that converted ALL partial-failure shapes
into typed Go errors. That single switch is too coarse: callers who
want shard-level errors but tolerate bulk item failures (or vice versa)
have no way to express it.

Replace the boolean with internal/errmask.ErrorMask, a 15-bit field
where each bit corresponds to one wrapper schema in the proposed
x-error-responses OpenAPI extension (BulkItems, SearchShards,
WriteShards, BroadcastShards, NodeFailures, BulkByScrollFailures,
TaskFailures, MultiSearchItems, MultiDocItems, Snapshot{Create,Get}-
ShardFailures, SimulateDocFailures, RankEvalFailures,
IngestionShardFailures, PitNodeFailures). A set bit MASKS that
category; the zero value reports every category. Callers express
fine-grained policy in code (Config.Errors = errmask.BulkItems |
errmask.SearchShards) or via OPENSEARCH_GO_ERROR_MASK using
comma-separated +/- tokens (e.g. "+all,-bulk_items").

Lifecycle (matches OPENSEARCH_GO_ROUTER):
  v4 (this commit): default `errmask.All` -- preserves pre-bitfield
    behavior (no partial-failure errors). Config.ReturnQueryErrors=true
    is honored as a deprecated alias for `errmask.None`.
  v5: default flips to `errmask.None` (safe by default).
  v6: Config.Errors / OPENSEARCH_GO_ERROR_MASK removed; behavior is
    unconditionally `errmask.None`.

The hand-written v4 opensearchapi/api_*.go call sites now read
c.errors.Has(errmask.<Wrapper>) for each operation's wrapper category.
A new hand-written v5preview/opensearchapi/errors.go ports the same
typed-error surface (PartialBulkError, PartialSearchError,
ShardFailureError, plus the IsPartialFailure / ToleratePartial-
Failures / RequireSuccessRate helpers) using v5preview's BulkResponse-
Item and ShardSearchFailure types. v5preview Config.Errors and the
clientInit(rootClient, mask) signature are wired through both
hand-written api.go and the generated clients_gen.go.

Spec side: opensearch-openapi.yaml is patched with 15
`_common.errors___<Wrapper>` schemas under components.schemas and 115
operation entries get an x-error-responses annotation. This mirrors
the upstream proposal in opensearch-api-specification (see
issue-x-partial-failure-mode.md). Once that PR lands and we re-bundle
from source, the local patch goes away cleanly.

Generator side: cmd/osgen reads x-error-responses from the spec
extension into ir.Operation.ErrorWrappers; cmd/osgen/errwrap supplies
a hardcoded fallback for plugin operations the spec doesn't yet
annotate. The dispatch fragment carries a data-driven `wrappers` map
of {Template, Applies}: each wrapper has both an emission template and
an Applies predicate that walks the response struct (including
embeds via the type registry) to confirm the field path the template
references actually exists. This keeps generated code compilable when
spec annotations land before the underlying response schema models the
relevant field -- v5preview's CreateResp and msearch's union response
item are skipped today and will start emitting once those types
acquire the missing fields.

Ref: opensearch-project#816
Ref: opensearch-project/opensearch-api-specification/pull/1137

Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>

Author: sean-

cmd/osgen/api_extract.go

@@ -55,6 +55,11 @@ type apiOperation struct {
 	QueryParams       []apiQueryParam
 	ResponseRef       string // schema key for the 200 response body (e.g. "cluster.health___HealthResponseBody")
 
+	// ErrorWrappers lists the partial-failure wrapper-schema names this
+	// operation may surface alongside its primary 2xx response. Populated
+	// from the x-error-responses extension on the spec operation.
+	ErrorWrappers []string
+
 	// ResponseSchemaRef is the resolved schema for the 200 response body,
 	// used to walk inline schemas that aren't in Components.Schemas.
 	ResponseSchemaRef *openapi3.SchemaRef
@@ -309,6 +314,7 @@ func buildAPIOperation(group string, ops []struct {
 		DocsURL:           docsURL,
 		ExcludedDistros:   extensionStringSlice(op.Extensions, extDistributionsExcluded),
 		HasBody:           op.RequestBody != nil,
+		ErrorWrappers:     errorResponseWrappers(op),
 	}
 
 	// Extract request body schema ref.

cmd/osgen/emit/build.go

@@ -226,7 +226,7 @@ func buildOperationFile(dir, pkg, basename string, op *ir.Operation, reg *ir.Typ
 	}
 
 	if len(op.DispatchRoutes) > 0 {
-		frags = append(frags, &DispatchFragment{Op: op})
+		frags = append(frags, &DispatchFragment{Op: op, Registry: reg})
 	}
 
 	return &File{

cmd/osgen/emit/frag_clients.go

@@ -30,6 +30,7 @@ func (f *ClientsFragment) Imports() []Import {
 	return []Import{
 		{Path: "github.com/opensearch-project/opensearch-go/v4"},
 		{Path: "github.com/opensearch-project/opensearch-go/v4/internal/apiutil"},
+		{Path: "github.com/opensearch-project/opensearch-go/v4/internal/errmask"},
 	}
 }
 
@@ -120,15 +121,17 @@ var noBody *opensearch.NoBody //nolint:gochecknoglobals // package-internal sent
 // Client represents the opensearchapi Client summarizing all API calls.
 type Client struct {
 	Client *opensearch.Client
+	errors errmask.ErrorMask
 {{- range .TopLevel}}
 	{{.FieldName}} {{.TypeName}}
 {{- end}}
 }
 
 // clientInit initializes a Client with all sub-clients.
-func clientInit(rootClient *opensearch.Client) *Client {
+func clientInit(rootClient *opensearch.Client, mask errmask.ErrorMask) *Client {
 	client := &Client{
 		Client: rootClient,
+		errors: mask,
 	}
 {{- range .InitStmts}}
 	{{.}}

cmd/osgen/emit/frag_clients_test.go

@@ -36,9 +36,11 @@ func TestClientsFragment_Body(t *testing.T) {
 	}{
 		{name: "Client struct", want: "type Client struct"},
 		{name: "Client field", want: "Client *opensearch.Client"},
+		{name: "errors mask field", want: "errors errmask.ErrorMask"},
 		{name: "top-level Cat", want: "Cat catClient"},
 		{name: "top-level Indices", want: "Indices indicesClient"},
-		{name: "clientInit", want: "func clientInit(rootClient *opensearch.Client) *Client"},
+		{name: "clientInit", want: "func clientInit(rootClient *opensearch.Client, mask errmask.ErrorMask) *Client"},
+		{name: "errors init", want: "errors: mask,"},
 		{name: "init Cat", want: "client.Cat = catClient{apiClient: client}"},
 		{name: "init Indices", want: "client.Indices = indicesClient{apiClient: client}"},
 		{name: "nested init Alias", want: "client.Indices.Alias = aliasClient{apiClient: client}"},
@@ -70,7 +72,7 @@ func TestClientsFragment_Imports(t *testing.T) {
 	}}
 
 	imps := frag.Imports()
-	require.Len(t, imps, 2)
+	require.Len(t, imps, 3)
 }
 
 func TestNewClientsFile_Render(t *testing.T) {
@@ -92,6 +94,7 @@ func TestNewClientsFile_Render(t *testing.T) {
 	require.Contains(t, output, "package "+ir.DefaultCorePkgName)
 	require.Contains(t, output, `"github.com/opensearch-project/opensearch-go/v4"`)
 	require.Contains(t, output, `"github.com/opensearch-project/opensearch-go/v4/internal/apiutil"`)
+	require.Contains(t, output, `"github.com/opensearch-project/opensearch-go/v4/internal/errmask"`)
 }
 
 func TestNewClientsFile_NilWhenEmpty(t *testing.T) {