Cosmos: rework driver options to use new macro and model (#3990)

This pull request refactors the runtime options resolution logic in the
Cosmos DB Rust SDK, introduces a new `RuntimeOptionsView` for layered
option resolution, and updates documentation and tests to match the new
approach. The changes simplify how runtime options are merged and
accessed, improve clarity in the codebase, and ensure consistent
behavior across driver, runtime, operation, and environment layers.

### Runtime Options Resolution Refactor

* Replaced the `effective_runtime_options` method with
`runtime_options_view`, which constructs a `RuntimeOptionsView` for
resolving options across operation, driver, runtime, and environment
layers. The view provides prioritized access to option values and
replaces manual merging.
(`sdk/cosmos/azure_data_cosmos_driver/src/driver/cosmos_driver.rs`)
[[1]](diffhunk://#diff-aae0ab9b30a5bf993d0a37d58a3f916f85391d6aeb72e334e2e9ea5d1ea18a54L695-L734)
[[2]](diffhunk://#diff-aae0ab9b30a5bf993d0a37d58a3f916f85391d6aeb72e334e2e9ea5d1ea18a54L825-R801)
* Removed fields and logic related to default retry counts
(`default_max_failover_retries`, `default_max_session_retries`) from
`CosmosDriver`, as these are now resolved through the new view.
(`sdk/cosmos/azure_data_cosmos_driver/src/driver/cosmos_driver.rs`)
[[1]](diffhunk://#diff-aae0ab9b30a5bf993d0a37d58a3f916f85391d6aeb72e334e2e9ea5d1ea18a54L59-L62)
[[2]](diffhunk://#diff-aae0ab9b30a5bf993d0a37d58a3f916f85391d6aeb72e334e2e9ea5d1ea18a54L580-L607)

### Documentation Updates

* Updated configuration documentation to clarify the movement of
`custom_headers` from multiple option types to `CosmosAccountOptions`,
and explained its best-effort nature and intended use.
(`sdk/cosmos/azure_data_cosmos/docs/ConfigurationOptions.md`)
[[1]](diffhunk://#diff-a8765df6c0f13087ea693bf4ac61c1394eda3e421df8acbf41c0e9d655b4e384R262)
[[2]](diffhunk://#diff-a8765df6c0f13087ea693bf4ac61c1394eda3e421df8acbf41c0e9d655b4e384L492-R497)
[[3]](diffhunk://#diff-a8765df6c0f13087ea693bf4ac61c1394eda3e421df8acbf41c0e9d655b4e384L534-R537)

### Test and Builder API Updates

* Refactored tests to use `RuntimeOptionsBuilder` instead of the
previous builder pattern, and updated assertions to match the new
options access pattern.
(`sdk/cosmos/azure_data_cosmos_driver/src/driver/cosmos_driver.rs`)
[[1]](diffhunk://#diff-aae0ab9b30a5bf993d0a37d58a3f916f85391d6aeb72e334e2e9ea5d1ea18a54L1036-R1004)
[[2]](diffhunk://#diff-aae0ab9b30a5bf993d0a37d58a3f916f85391d6aeb72e334e2e9ea5d1ea18a54L1157-R1132)
[[3]](diffhunk://#diff-aae0ab9b30a5bf993d0a37d58a3f916f85391d6aeb72e334e2e9ea5d1ea18a54L1173-R1146)
[[4]](diffhunk://#diff-aae0ab9b30a5bf993d0a37d58a3f916f85391d6aeb72e334e2e9ea5d1ea18a54L1183-R1157)
[[5]](diffhunk://#diff-aae0ab9b30a5bf993d0a37d58a3f916f85391d6aeb72e334e2e9ea5d1ea18a54L1321-R1309)
[[6]](diffhunk://#diff-aae0ab9b30a5bf993d0a37d58a3f916f85391d6aeb72e334e2e9ea5d1ea18a54L1350-R1319)
[[7]](diffhunk://#diff-aae0ab9b30a5bf993d0a37d58a3f916f85391d6aeb72e334e2e9ea5d1ea18a54L1361-R1330)
[[8]](diffhunk://#diff-aae0ab9b30a5bf993d0a37d58a3f916f85391d6aeb72e334e2e9ea5d1ea18a54L1371-R1352)
[[9]](diffhunk://#diff-aae0ab9b30a5bf993d0a37d58a3f916f85391d6aeb72e334e2e9ea5d1ea18a54L1392-R1361)
[[10]](diffhunk://#diff-aae0ab9b30a5bf993d0a37d58a3f916f85391d6aeb72e334e2e9ea5d1ea18a54L1407-R1379)

### Dependency and Import Changes

* Added `azure_data_cosmos_macros` as a dependency in workspace and main
`Cargo.toml` files. (`Cargo.toml`,
`sdk/cosmos/azure_data_cosmos_driver/Cargo.toml`)
[[1]](diffhunk://#diff-2e9d962a08321605940b5a657135052fbcef87b5e360662bb527c96d9a615542R101)
[[2]](diffhunk://#diff-e88ccd29a5723513603d930d833d57bdb20427e8b1a20c3bbc48acecc2bd464bR24)
* Updated imports to include `RuntimeOptionsView` and remove unused or
obsolete items.
(`sdk/cosmos/azure_data_cosmos_driver/src/driver/cosmos_driver.rs`,
`sdk/cosmos/azure_data_cosmos_driver/src/driver/runtime.rs`)
[[1]](diffhunk://#diff-aae0ab9b30a5bf993d0a37d58a3f916f85391d6aeb72e334e2e9ea5d1ea18a54L17-R17)
[[2]](diffhunk://#diff-63386f335ae60cf8f9101b469999e1e136da6b574066ac6892d8b6855c949dfdL20-R21)

These changes make option resolution more robust and maintainable, and
clarify the intended usage of custom headers and runtime configuration
throughout the SDK.

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: analogrelay

Cargo.lock

@@ -98,6 +98,7 @@ async-stream = { version = "0.3.6" }
 async-trait = "0.1"
 base64 = "0.22"
 arc-swap = "1.7"
+azure_data_cosmos_macros = { version = "0.1.0", path = "sdk/cosmos/azure_data_cosmos_macros" }
 bytes = "1.11.1"
 cargo_metadata = "0.23.1"
 clap = { version = "4.5.58", features = ["derive"] }

Cargo.toml

@@ -259,6 +259,7 @@ pub struct CosmosAccountOptions { /* fields below */ }
 | --- | --- | --- | --- |
 | `user_agent_suffix` | `Option<String>` | `AZURE_COSMOS_USER_AGENT_SUFFIX` | Application identifier appended to the User-Agent header for telemetry. |
 | `account_initialization_custom_endpoints` | `Option<HashSet<Url>>` | `AZURE_COSMOS_CUSTOM_ENDPOINTS` | Custom endpoints for initial account discovery (private endpoints, etc.). Env var is comma-separated. |
+| `custom_headers` | `Option<HashMap<HeaderName, HeaderValue>>` | — | **Best-effort only.** Additional HTTP headers injected into outgoing requests. Intended for proxies, gateways, or external telemetry systems — **not** for setting Cosmos DB backend headers. The SDK may use non-standard transports (e.g., custom framing over TCP) where HTTP headers do not apply; in those cases custom headers are silently ignored. The SDK reserves the right to override any header that conflicts with its internal protocol. `None` inherits from a lower layer; `Some(map)` replaces (does not merge) the inherited value. No environment variable — headers are not representable as a single string. |
 
 ---
 
@@ -489,9 +490,11 @@ The `ConsistencyLevel` enum itself is **retained** as a model type for account-l
 
 ### 6.3 Custom HTTP Headers (`custom_headers`)
 
-**Removed from:** `CosmosClientOptions`, `ItemOptions`, `QueryOptions`
+**Moved from:** `CosmosClientOptions`, `ItemOptions`, `QueryOptions` → `CosmosAccountOptions.custom_headers`
+
+Retained as a **best-effort** mechanism for injecting HTTP headers into outgoing requests. This is intended for proxies, gateways, or external telemetry systems — **not** for setting Cosmos DB backend headers. The Cosmos SDK does not always use standard HTTP or HTTP/2 (e.g., it may use custom framing over TCP); custom headers are silently ignored on transports where they do not apply. The SDK reserves the right to override any header that conflicts with its internal protocol.
 
-The Rust SDK does not expose a custom HTTP header mechanism. Features that other SDKs surface through custom headers (e.g., dedicated gateway cache control) will be modeled as first-class typed options when supported.
+Features that other SDKs surface through custom headers (e.g., dedicated gateway cache control) will continue to be modeled as first-class typed options rather than relying on `custom_headers`.
 
 ### 6.4 Indexing Directive (`indexing_directive`)
 
@@ -531,7 +534,7 @@ The Cosmos SDK manages its own transport, retry, and telemetry pipeline internal
 | `throughput_bucket` | `CosmosClientOptions`, `ItemOptions`, `QueryOptions` | — | **Deferred** to throughput control follow-up spec |
 | `session_retry_options` | `CosmosClientOptions` | `RetryOptions.session_retry` | Nested; fields become `Option<T>` |
 | `priority` | `CosmosClientOptions`, `ItemOptions`, `QueryOptions` | — | **Deferred** to throughput control follow-up spec |
-| `custom_headers` | `CosmosClientOptions`, `ItemOptions`, `QueryOptions` | — | **Removed** (§6.3) |
+| `custom_headers` | `CosmosClientOptions`, `ItemOptions`, `QueryOptions` | `CosmosAccountOptions.custom_headers` | Moved to option group; best-effort only (see §6.3) |
 | `pre_triggers` | `ItemOptions` | — | **Removed** (§6.5) |
 | `post_triggers` | `ItemOptions` | — | **Removed** (§6.5) |
 | `session_token` | `ItemOptions`, `QueryOptions` | Operation-only on each type | Duplicated across read/write/query/batch |

sdk/cosmos/azure_data_cosmos/docs/ConfigurationOptions.md

@@ -21,6 +21,7 @@ async-trait.workspace = true
 azure_core = { version = "0.33.0", default-features = false, features = [
   "hmac_rust",
 ] }
+azure_data_cosmos_macros.workspace = true
 base64.workspace = true
 crossbeam-epoch = { workspace = true, features = ["std"] }
 futures.workspace = true