Cosmos: Review options and refactor them according to the layered options model

[analogrelay]

Once #3921 lands, we need to review all our options in the driver, add ones we're missing, and refactor them to use the layered options infrastructure.

[github-actions]

🎯 Agentic Issue Triage

This is a follow-up refactoring task for the Cosmos SDK driver, blocked on #3921 (Build Layered Options Model). Once the layered options infrastructure is in place, this issue tracks the work to audit all existing options in the driver, identify missing ones, and migrate everything to the new model.

📋 Issue Analysis

Type: Feature / Refactoring
Blocked on: #3921 — "Cosmos: Build Layered Options Model"
Scope: sdk/cosmos/ — primarily azure_data_cosmos_driver and azure_data_cosmos

The goal is to:

1. Inventory all current driver options (e.g., connection settings, retry policies, timeout, consistency level, preferred regions, application region).
2. Identify gaps — options that should exist but don't yet.
3. Refactor existing options structs to use the layered options infrastructure introduced by Cosmos: Build Layered Options Model #3921.

🗂️ Suggested Sub-Tasks Checklist

• Wait for Cosmos: Build Layered Options Model #3921 to be merged (layered options infrastructure is a prerequisite).
• Audit all *Options structs in sdk/cosmos/azure_data_cosmos_driver/src/ for options that should participate in layering.
• Audit sdk/cosmos/azure_data_cosmos/src/ for any client-level options structs.
• Map each option to the correct layer: per-operation, per-client/account, or per-application.
• Identify missing options (e.g., anything exposed in other SDK languages' Cosmos clients that we lack).
• Refactor each options struct to integrate with the layered options model from Cosmos: Build Layered Options Model #3921.
• Ensure environment variable overrides work at the appropriate layer.
• Update documentation and changelogs accordingly.
• Validate with cargo clippy -p azure_data_cosmos and cargo clippy -p azure_data_cosmos_driver.

🔍 Relevant Code Areas

Key files/modules to review during the audit:

• sdk/cosmos/azure_data_cosmos_driver/src/driver/ — core driver options
• sdk/cosmos/azure_data_cosmos_driver/src/driver/routing/ — location/region settings
• sdk/cosmos/azure_data_cosmos_driver/src/driver/pipeline/ — retry and failover options
• sdk/cosmos/azure_data_cosmos/src/clients/cosmos_client_builder.rs — public client builder and options surface

Reference: other Azure SDK language implementations (e.g., .NET CosmosClientOptions, Java CosmosClientBuilder) for a comprehensive list of options that may be missing.

💡 Notes & Nudges

• This work will directly enable multi-account app scenarios described in Cosmos: Build Layered Options Model #3921.
• Consider whether any options should be settable via environment variables (e.g., AZURE_COSMOS_CONSISTENCY_LEVEL, AZURE_COSMOS_PREFERRED_REGIONS).
• The endpoint_unavailability_ttl is currently hardcoded in operation_pipeline.rs — this is a candidate for a layered option.
• Keep in mind that the driver crates should not introduce tokio-specific APIs; only azure_data_cosmos_native should use tokio directly.

Generated by Agentic Triage for issue #3923 · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/issue-triage.md@8e6d7c86bba37371d2d0eee1a23563db3e561eb5