Cosmos: rework driver options to use new macro and model#3990
Merged
analogrelay merged 9 commits intoAzure:release/azure_data_cosmos-previewsfrom Mar 24, 2026
Merged
Conversation
analogrelay
force-pushed
the
ashleyst/driver-options
branch
from
02b3464 to
8ec98a2
Compare
github-project-automation
bot
moved this from Todo
to Approved
in CosmosDB Go/Rust Crew
analogrelay
force-pushed
the
ashleyst/driver-options
branch
from
f918f57 to
425dffe
Compare
Remove redundant materialization of RuntimeOptions from the view. Both downstream consumers (effective_throughput_control_group and execute_operation_pipeline) accept &RuntimeOptionsView, so the intermediate struct construction was unnecessary and broke the build after rebasing onto the fault injection changes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
analogrelay
force-pushed
the
ashleyst/driver-options
branch
from
bd33a3e to
3bd210e
Compare
azure_data_cosmos_macros must be a regular dependency because #[derive(CosmosOptions)] is used in library code, not just tests. Add version to the workspace dependency definition so cargo deny does not flag it as a wildcard path dependency. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
analogrelay
requested review from
a team,
LarryOsterman,
RickWinter,
heaths and
ronniegeraghty
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
Refactors the Cosmos DB Rust SDK runtime option resolution to use the new #[derive(CosmosOptions)] model, introducing a layered RuntimeOptionsView and updating callers/tests/docs to use view-based resolution rather than manual merging.
Changes:
- Introduces
RuntimeOptionsView/RuntimeOptionsBuilderviaazure_data_cosmos_macros::CosmosOptionsand updates runtime option env-var loading. - Reworks driver/runtime/operation pipeline code paths to resolve options through the layered view (env → runtime → account/driver → operation).
- Updates documentation and dependency manifests to include the new macros crate and reflect option-surface changes.
Reviewed changes
Copilot reviewed 12 out of 13 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| sdk/cosmos/azure_data_cosmos_driver/tests/framework/test_client.rs | Updates test client to hold an Arc<CosmosDriverRuntime> after runtime API changes. |
| sdk/cosmos/azure_data_cosmos_driver/src/options/runtime_options.rs | Converts RuntimeOptions to macro-derived layered options; adds env-var annotations and view/builder-based tests. |
| sdk/cosmos/azure_data_cosmos_driver/src/options/policies.rs | Adds FromStr/Display for ContentResponseOnWrite to support env parsing and formatting. |
| sdk/cosmos/azure_data_cosmos_driver/src/options/operation_options.rs | Removes the old “effective runtime options” merge helper in favor of view-based resolution. |
| sdk/cosmos/azure_data_cosmos_driver/src/options/mod.rs | Updates module docs and re-exports to include RuntimeOptionsView and remove obsolete shared-options types. |
| sdk/cosmos/azure_data_cosmos_driver/src/options/driver_options.rs | Switches driver-level runtime options storage to Arc<RuntimeOptions>; updates examples/tests accordingly. |
| sdk/cosmos/azure_data_cosmos_driver/src/driver/runtime.rs | Introduces env/runtime layering (env_options + swappable runtime_options) and makes runtime construction return an Arc. |
| sdk/cosmos/azure_data_cosmos_driver/src/driver/pipeline/operation_pipeline.rs | Updates pipeline to consume RuntimeOptionsView accessors instead of merged RuntimeOptions. |
| sdk/cosmos/azure_data_cosmos_driver/src/driver/cosmos_driver.rs | Replaces manual runtime option merging with runtime_options_view() and propagates RuntimeOptionsView usage. |
| sdk/cosmos/azure_data_cosmos_driver/Cargo.toml | Adds the azure_data_cosmos_macros dependency to the driver crate. |
| sdk/cosmos/azure_data_cosmos/docs/ConfigurationOptions.md | Updates docs around custom_headers semantics/location and clarifies best-effort behavior. |
| Cargo.toml | Adds the macros crate to workspace dependencies. |
| Cargo.lock | Records the new macros dependency and includes additional transitive dependency version updates. |
sdk/cosmos/azure_data_cosmos_driver/src/driver/cosmos_driver.rs
Outdated
Show resolved
Hide resolved
Store env_options as Arc<RuntimeOptions> in CosmosDriverRuntime to avoid per-operation Arc::new + clone allocations. Recover from RwLock poisoning in runtime_options() and set_runtime_options() using into_inner instead of unwrap, since the write side is an atomic Arc swap with no multi-step mutation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
RuntimeOptionsBuilder is generated by #[derive(CosmosOptions)] so rustdoc cannot resolve it as an intra-doc link. Use plain code spans instead. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
analogrelay
merged commit f3c5db5
into
Azure:release/azure_data_cosmos-previews
19 checks passed
github-project-automation
bot
moved this from Approved
to Done
in CosmosDB Go/Rust Crew
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request refactors the runtime options resolution logic in the Cosmos DB Rust SDK, introduces a new
RuntimeOptionsViewfor 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
effective_runtime_optionsmethod withruntime_options_view, which constructs aRuntimeOptionsViewfor 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] [2]default_max_failover_retries,default_max_session_retries) fromCosmosDriver, as these are now resolved through the new view. (sdk/cosmos/azure_data_cosmos_driver/src/driver/cosmos_driver.rs) [1] [2]Documentation Updates
custom_headersfrom multiple option types toCosmosAccountOptions, and explained its best-effort nature and intended use. (sdk/cosmos/azure_data_cosmos/docs/ConfigurationOptions.md) [1] [2] [3]Test and Builder API Updates
RuntimeOptionsBuilderinstead 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] [2] [3] [4] [5] [6] [7] [8] [9] [10]Dependency and Import Changes
azure_data_cosmos_macrosas a dependency in workspace and mainCargo.tomlfiles. (Cargo.toml,sdk/cosmos/azure_data_cosmos_driver/Cargo.toml) [1] [2]RuntimeOptionsViewand 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] [2]These changes make option resolution more robust and maintainable, and clarify the intended usage of custom headers and runtime configuration throughout the SDK.