azure_data_cosmos@0.36.0

0.36.0 (2026-06-19)

Features Added

• Derived SafeDebug on CosmosCredential, ItemResponse, ResourceResponse<T>, and BatchResponse. (#4512)
• Added standard derives (Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize) to ConsistencyLevel and RoutingStrategy. (#4512)
• Query::with_text now accepts impl Into<String>. (#4512)
• Exposed CosmosRuntime and a runtime-aware CosmosClientBuilder, splitting the Cosmos client into a per-process runtime (transport / cert / proxy / UA defaults) and per-client driver (operation defaults, fault injection, throughput-control groups), and re-exporting the driver's options surface from azure_data_cosmos::options:
  • New CosmosRuntime and CosmosRuntimeBuilder types. A default process-wide runtime is initialized lazily; users can configure their own runtime through CosmosRuntimeBuilder and attach it via CosmosClientBuilder::with_runtime. The runtime builder exposes:
    • with_connection_pool(ConnectionPoolOptions) — runtime-wide transport / cert / proxy settings.
    • with_default_operation_options(OperationOptions) — runtime-default OperationOptions.
    • with_user_agent_suffix(UserAgentSuffix) — runtime-default User-Agent suffix.
    • with_cpu_refresh_interval(Duration) — diagnostics sampler interval.
    • build() — auto-applies an azsdk-rust-cosmos/<crate-version> wrapping SDK identifier so wire User-Agent strings always advertise the SDK alongside any custom suffix.
  • New per-client setters on CosmosClientBuilder:
    • with_runtime(CosmosRuntime) — attach an explicit runtime; when not set, build() resolves CosmosRuntime::global() lazily.
    • with_default_operation_options(OperationOptions) — client-level default OperationOptions (overrides runtime defaults; overridden by per-call options).
    • with_partition_failover_options(PartitionFailoverOptions) — configures the driver's per-partition circuit-breaker / failover tuning for this client; when unset, the driver falls back to PartitionFailoverOptions::default(), which honors the AZURE_COSMOS_PPCB_* environment variables.
    • with_fault_injection_rules(Vec<Arc<FaultInjectionRule>>) -> Result<Self> — registers fault-injection rules on this specific client (gated on fault_injection).
    • register_throughput_control_group(ThroughputControlGroupOptions) -> Result<Self> — registers a throughput-control group for this client's driver.
  • New re-exports from azure_data_cosmos::options (so users configuring a custom runtime don't have to take a direct dependency on the driver crate): ConnectionPoolOptions, ConnectionPoolOptionsBuilder, ServerCertificateValidation, PartitionFailoverOptions, PartitionFailoverOptionsBuilder, ThroughputControlOptions, ThroughputControlOptionsBuilder, and ThroughputControlOptionsView.
  • New nested OperationOptions::throughput_control group lets callers set throughput_bucket and priority_level per request without first registering a throughput-control group; registered groups are still consulted as fallbacks through ThroughputControlOptions::group_name. (See the driver CHANGELOG for the full per-field layering and header-emission rules.)

Breaking Changes

• Reorganized the public API: types are now grouped under models, diagnostics, feed, and options; the query, regions, and routing_strategy modules were removed; the previously #[doc(hidden)] feature-gated builder methods on CosmosClientBuilder are now visible (and remain feature-gated); PartitionKey::EMPTY, its Default impl, and From<()> for PartitionKey were removed (use the query/feed APIs for cross-partition operations); and ETag is no longer re-exported from azure_data_cosmos::options — use azure_core::http::Etag directly (construct via Etag::from(&str) / Etag::from(String)). See the PR for the full list of moves and import paths. (#4512)
• Renamed CosmosClientBuilder::with_operation_options to CosmosClientBuilder::with_default_operation_options to reflect the fact that it specifies defaults for per-operation options rather than actual client-level options. (#4588)
• TransactionalBatch::{create_item, upsert_item, replace_item} and TransactionalBatchOperationResult::into_model now return azure_data_cosmos::Result<_> instead of Result<_, serde_json::Error>. The underlying resource_body is now stored as Option<Box<serde_json::value::RawValue>> and exposed via a new resource_body() accessor. (#4512)
• DatabaseProperties::id is now Option<String> (previously String) to match the wire schema. (#4512)
• Partition Circuit Breaker (PPCB) is now ENABLED by default. To disable it, set PartitionFailoverOptions::circuit_breaker_enabled to false when configuring a CosmosClient or set the AZURE_COSMOS_PPCB_ENABLED environment variable to false. (#4588)
• CosmosClientBuilder has been slimmed to a runtime-aware surface. Per-runtime concerns (transport, cert validation, proxy, UA defaults) move onto CosmosRuntime and are shared across clients; per-client concerns (operation defaults, FI rules, throughput-control groups) stay on the builder (#4588). Migration impact:
  • with_proxy_allowed — removed. Move to CosmosRuntimeBuilder::with_connection_pool(ConnectionPoolOptionsBuilder::new().with_proxy_allowed(true).build()).
  • with_throttling_retry_options — removed. The throttle settings now live on OperationOptions; use with_default_operation_options(OperationOptionsBuilder::new().with_throttling_retry_options(...).build()) (or attach to a CosmosRuntime for process-wide defaults).
  • with_fault_injection — renamed to with_fault_injection_rules and now returns Result<Self> to surface duplicate-ID errors at registration time.
  • with_throughput_control_group — renamed to register_throughput_control_group and now returns Result<Self>. Throughput-control groups are now a per-client (driver-level) concept only; CosmosRuntimeBuilder does not expose a corresponding registration method.
  • with_driver_runtime_builder — replaced by with_runtime(CosmosRuntime). The __internal_in_memory_emulator harness builds its runtime via CosmosRuntimeBuilder::from(driver_builder) (the From<CosmosDriverRuntimeBuilder> escape hatch).
  • The allow_invalid_certificates Cargo feature has been removed. The capability is now in the default feature set but requires explicit opt-in via CosmosRuntimeBuilder::with_connection_pool(ConnectionPoolOptionsBuilder::new().with_server_certificate_validation(ServerCertificateValidation::RequiredUnlessEmulator).build()). The new RequiredUnlessEmulator policy is not a blanket "disable validation" knob — it validates the server certificate normally and only relaxes validation for detected Cosmos DB emulator hosts (via AccountEndpoint + Region heuristics, or the AZURE_COSMOS_EMULATOR_HOST environment variable). See the driver CHANGELOG for the underlying EmulatorServerCertValidation → ServerCertificateValidation rename.
• Per-account driver caching has been removed from the underlying runtime — each CosmosClient::build(...) now constructs a fresh CosmosDriver. Clients sharing the same CosmosRuntime continue to share transport pools, sampler, account cache, etc.; only the per-account CosmosDriver instance is no longer reused. (#4588)

Bugs Fixed

• 403/1008 (DatabaseAccountNotFound) and 403/3 (WriteForbidden) now trigger an account-topology refresh and retry against the refreshed endpoints instead of bubbling up. (#4590)
• Gateway-mode transport connect failures no longer bump the per-partition circuit breaker counter; only the endpoint-unavailable mark is emitted. (#4590)
• 403/3 (WriteForbidden) and 403/1008 (DatabaseAccountNotFound) on a PPCB-managed multi-write partition no longer mark the endpoint unavailable; the per-partition counter drives failover so other partitions on the same endpoint keep writing normally. (#4590)
• The per-partition circuit breaker override now respects OperationOptions::excluded_regions; previously a tripped override could silently route to a region the caller had excluded. (#4590)

Other Changes

• DatabaseClient::read_throughput and begin_replace_throughput no longer panic in release builds if the service returns an offer without _rid; they now return a synthetic CosmosError. (#4512)
• azure_data_cosmos::error is now a public module, and ContainerClient / DatabaseClient are re-exported at the crate root. (#4512)
• Documented that control-plane create/replace methods (CosmosClient::create_database, DatabaseClient::create_container, ContainerClient::replace, and the throughput-replace methods) always return the resource body regardless of ContentResponseOnWrite, and pointed CosmosClient's rustdoc at the CosmosClient::builder() factory. (#4512)