dynamic_modules: let runtime cluster hosts carry logical hostnames

[dio]

Description:

This is the first remaining implementation slice from #45962. The TLS part has been completed by #45982, which scopes upstream client TLS session caching by effective SNI.

Envoy core already supports host-driven SNI: when auto_host_sni is enabled, upstream TLS reads HostDescription::hostname(). The remaining gap is narrower and specific to dynamic-module clusters. The current envoy_dynamic_module_callback_cluster_add_hosts() ABI accepts concrete socket addresses but no logical hostnames, and DynamicModuleCluster::addHosts() therefore synthesizes each runtime hostname from the cluster name and address.

A module can consequently connect to a resolved IP:port, but cannot preserve the original DNS name on the runtime Host for auto_host_sni and auto_sni_san_validation.

Proposed first slice:

• Add an additive callback named envoy_dynamic_module_callback_cluster_add_hosts_with_hostnames().
• Accept a logical-hostname buffer parallel to the existing address buffer.
• Store a non-empty supplied hostname on the Host while continuing to use the concrete address for the connection.
• Treat a null hostname array or an empty hostname entry as a request for the existing synthesized-hostname behavior.
• Expose the callback through the dynamic-module ABI implementation and SDKs.
• Leave envoy_dynamic_module_callback_cluster_add_hosts() and all of its behavior unchanged.

This slice does not require a proto or xDS change, does not change DNS ownership, and does not modify router or TLS code. It only makes the logical hostname already consumed by Envoy core available to runtime hosts created by this extension.

Compatibility:

The proposed API is additive and opt-in. Existing modules continue to call the address-only callback and retain the current synthesized hostname and address-based deduplication behavior. Because no existing behavior changes until a module calls the new ABI, I do not currently see a need for a runtime guard, but I would follow reviewer guidance here.

Expected tests:

• a supplied logical hostname becomes HostDescription::hostname();
• null and empty hostname inputs preserve the current synthesized-hostname behavior;
• the existing address-only callback remains unchanged;
• ABI input validation and main-thread requirements remain fail-closed;
• SDK tests cover the new callback and returned host handles.

Possible follow-up: shared addresses:

This first slice deliberately preserves the existing address-based host deduplication model. A later, separate change can consider modules that need two logical TLS sites at the same socket address, for example:

192.0.2.10:443 -> service-a.example
192.0.2.10:443 -> service-b.example

The likely follow-up would affect only the hostname-aware callback: permit distinct returned Host objects for the same address, retain exact HostPtr identity in the module, and let the module own logical-host deduplication. The existing address-only callback would remain address-deduplicated. Keeping this out of the first PR makes the ABI addition independently reviewable and avoids mixing hostname transport with a host-identity semantic change.

Relevant links:

• Umbrella issue: dynamic_modules/tls: support auto_host_sni for runtime hosts and SNI-scoped session reuse #45962
• Merged TLS slice: tls: scope upstream session cache by sni #45982
• First-slice prototype branch: https://github.com/dio/envoy/tree/dio/dynamic-module-runtime-hostnames-base
• Pinned prototype commit: dio@cabe988
• Runnable Go demo and downloadable builds: https://github.com/dio/auto-sni-choose-host
• Shared-address follow-up prototype: https://github.com/dio/envoy/tree/dio/dynamic-module-shared-address-hosts

The main design question for this issue is whether an additive hostname-specific callback is the preferred ABI shape, or whether maintainers want a more general per-host attributes/options ABI before implementation is submitted.

[dio]

cc @wbpcode — following up directly on your earlier TLS session-cache comment: #45962 (comment)

The exact shared-client-context setup discussed there is now implemented by merged PR #45982: session reuse is keyed by effective SNI while retaining a global bounded LRU. This issue intentionally isolates the remaining dynamic-module ABI addition needed to put the logical hostname on each runtime Host.

[dio]

Compatibility invariant for the first PR: this must not change behavior for any existing module or existing Envoy configuration.

Acceptance criteria:

• Keep the existing envoy_dynamic_module_callback_cluster_add_hosts() symbol, signature, validation, returned handles, and failure behavior unchanged.
• Preserve its exact synthesized hostname behavior.
• Preserve existing address-based deduplication, including incremental additions at an already-owned address.
• A null hostname array or empty hostname entry on the new callback must produce the same observable behavior as the existing callback, including hostname synthesis, deduplication, returned handles, and failure semantics. The implementation may use a shared internal helper.
• The only new behavior occurs when a module explicitly calls the new callback with a non-empty logical hostname.
• Do not change proto/xDS configuration, DNS ownership, load-balancer behavior, router behavior, or TLS behavior in this slice.
• Add regression tests that exercise the existing address-only callback before and after the refactor, plus null/empty fallback and incremental same-address deduplication.

This additive, opt-in boundary is also why a runtime guard should not be necessary: there is no changed behavior to roll back for existing callers. If implementation review reveals that the existing callback cannot retain the same observable behavior, that should stop this slice for redesign rather than silently broaden its scope.

The possible shared-address follow-up must follow the same rule: any relaxed deduplication would apply only to the new hostname-aware callback; the existing address-only callback would remain address-deduplicated.

Prepared runnable demo: https://github.com/dio/auto-sni-choose-host

• The default demo and base release exercise only this first logical-hostname ABI slice.
• The separately documented shared-address scenario and stacked release demonstrate the possible follow-up; they are not part of the first PR.