feat(opensearch): configureSettings escape hatch on both client factories

[bfarmer67]

Stacked on #122 (which is stacked on #121). GitHub retargets automatically as each merges. Review the third commit only.

Closes a real consumer gap: there was no way to reach ConnectionSettings, so the only escape was to stop calling AddOpenSearchAwsClient and fork it.

API

services.AddOpenSearchClient(
    endpoint,
    auth     => auth.Mode = OpenSearchAuthenticationMode.Basic,
    settings => settings.RequestTimeout( TimeSpan.FromMinutes( 2 ) )
                        .MaximumRetries( 5 )
                        .EnableHttpCompression() );

services.AddOpenSearchAwsClient(
    endpoint,
    aws      => aws.Region = "us-east-1",
    settings => settings.RequestTimeout( TimeSpan.FromMinutes( 2 ) ) );

Both IConfiguration overloads get the same treatment.

Purely additive: source- AND binary-compatible with 3.1.x. This ships as four new overloads, not as an appended optional parameter. Appending one is source-compatible but not binary-compatible - it changes the existing method's signature, so the 3.1.x entry point stops existing and anything compiled against it throws MissingMethodException until recompiled. This library claims SemVer; a minor release must not do that.

The four 3.1.x signatures are preserved exactly and forward to the new ones. Their = null defaults move to the new overloads, which is not a signature change (a default is parameter metadata, and a 3.1.x caller that omitted the argument already baked the null into its own call site) and is what keeps the pair unambiguous:

AddOpenSearchClient( services, uri )                         -> new overload (both default)
AddOpenSearchClient( services, uri, auth )                   -> 3.1.x overload (fewer params wins)
AddOpenSearchClient( services, uri, auth, cfg )              -> new overload
AddOpenSearchClient( services, uri, configureSettings: cfg ) -> new overload

Two reflection tests pin all eight signatures so the guarantee cannot regress silently. Reflection rather than call sites on purpose - a source-level call binds happily to a widened signature and proves nothing.

Applied last, after the endpoint and auth wiring. An escape hatch the library can silently overwrite is not an escape hatch; there's a test asserting a consumer BasicAuthentication beats the library's.

Action<ConnectionSettings> rather than Func<...>: ConnectionSettings mutates in place and returns itself, so a required return adds only a way to get it wrong — and Action<TOptions> is the configure-callback idiom already used throughout these extensions.

Both packages route through one internal BuildClient, so the hook and its validation behave identically on both paths. That needs InternalsVisibleTo from core to .Aws.

Why this is not the _mget fix

Worth being explicit since this PR exists because of that bug. Fixing #121 by having consumers declare DefaultMappingFor<OpenSearchMigrationRecord> would make correct operation opt-in and push a library-internal type into consumer wiring. #121 fixes it properly; this is a separate capability for consumer-owned concerns. Recorded in ADR-0030 with ADR-0029 as the counterweight.

The guardrail

The hook introduces one real foot-gun, so it ships with the safety.

The ledger index is created with a strict mapping using camelCase fields, matching the client's default field-name inference. A hook that replaces the serializer or sets a client-wide non-camelCase DefaultFieldNameInferrer breaks every ledger write. That failure is loud on its own — strict_dynamic_mapping_exception — but it arrives at first write, names fields rather than the cause, and reads like a schema problem.

Registration probes one known ledger property through the configured inferrer and fails with the cause and the remediation:

The configureSettings callback changed field-name inference: the ledger property
`AppliedBy` now serializes as `AppliedBy` instead of `appliedBy`. The migration ledger
index is created with a strict mapping using camelCase field names, so every ledger
write would be rejected with strict_dynamic_mapping_exception.

This is usually caused by replacing the serializer or by calling
DefaultFieldNameInferrer(...) with a non-camelCase convention. Both are supported for
your own document types -- scope them with DefaultMappingFor<TDocument>() instead of
changing the client-wide default, or register a separate IOpenSearchClient for
application use and leave the migration client stock.

One probe is enough — field-name inference is a single client-wide setting. Validation runs only when a hook is supplied, so the default path costs nothing.

I deliberately did not extend the validation to the whole class of ledger-adjacent settings (serializer, DefaultIndex, IConnection). Only field-name inference actually breaks the ledger; DefaultIndex is legitimate and #121 already makes the ledger immune to index inference. Replacing IConnection on the SigV4 path removes request signing — documented on the parameter rather than validated, since enumerating every way to misconfigure a transport isn't tractable.

Tests

OpenSearchConnectionSettingsHookTests (9):

• hook reaches the resolved client — core and AWS paths
• hook runs after auth wiring (consumer BasicAuthentication wins)
• hook stays optional; existing call shapes unchanged
• IConfiguration overload forwards it
• ledger-breaking inferrer loud-fails with remediation — core and AWS paths
• the recommended remediation actually works: DefaultMappingFor<ConsumerDocument> passes
• ADR-0029 cross-check: a consumer DefaultIndex does not become the ledger's index

Full suite: 450 + 889 + 38 pass (unit tier was 433 + 889 + 38 on main). Whole solution builds clean on net8/9/10.

Docs

ADR-0030, docs/site/opensearch.md ("Tuning the client"), and the .Aws package README.

Not doing: symmetric hooks on the other providers

I looked, and the symmetry argument doesn't hold. Aerospike (IAsyncClient), Couchbase (IClusterProvider), MongoDB (IMongoClient), and Postgres (NpgsqlDataSource) all resolve a client the consumer registered — they already have 100% control, and there's nothing to open up. OpenSearch is the outlier because it's the only one that constructs a client. Adding factories elsewhere to make the hook symmetric would be inventing the problem to justify the solution.

The thing that did generalize was the underlying coupling, and that's #122.

🤖 Generated with Claude Code