Cosmos: Add *_OVERRIDE incident kill-switch env vars for hedging & PPCB, plus AZURE_COSMOS_HEDGING_ENABLED master switch

[kundadebdatta]

Summary

Adds environment-driven enablement controls for two availability features —
cross-region read hedging and the per-partition circuit breaker (PPCB) — on top
of the existing programmatic configuration, plus an incident _OVERRIDE kill
switch for each.

• Hedging gains a master switch AZURE_COSMOS_HEDGING_ENABLED (env layer of
  the normal OperationOptions layering) and a top-priority kill switch
  AZURE_COSMOS_HEDGING_ENABLED_OVERRIDE. Both are implemented generically in
  the CosmosOptions derive via #[option(env = "...", overridable)].
• PPCB enablement is a driver-level PartitionFailoverOptions concern (since
  cosmos: expose CosmosRuntime, consolidate client config #4588), so its kill switch is a dedicated
  PartitionFailoverOptions::circuit_breaker_enabled_override field, set via
  AZURE_COSMOS_PPCB_ENABLED_OVERRIDE. When set it is authoritative over both
  the circuit_breaker_enabled option and the server account property
  enable_per_partition_failover_behavior.

Hedging and PPCB remain enabled by default; all new variables are inert unless set.

Resolution layering

• Hedging (hedging_enabled): {ENV}_OVERRIDE → operation → account → runtime → {ENV}.
• PPCB (circuit_breaker_enabled_override): override wins over
  circuit_breaker_enabled option and the account property. (Not part of the
  per-operation layering — PPCB enablement is driver-level.)

All _OVERRIDE values are read once at runtime-build time; flipping mid-incident
requires a process restart. Booleans parse leniently (true/false, 1/0,
yes/no, on/off); an unrecognized value is logged and ignored.

Changes

azure_data_cosmos_macros

• New overridable field flag (#[option(env = "...", overridable)]) →
  auto-generates {ENV}_OVERRIDE parsing + a top-priority env_override view
  layer via new_with_override.
• New #[options(env_only)] struct mode → generates only from_env()/
  from_env_vars() (no View/Builder/Default), letting an existing builder type
  double as its own env source.
• New #[option(env = "...", parser = path)] attribute → custom
  fn(&str) -> Option<T> parsing (e.g. Duration from a millisecond count),
  with lenient None-is-ignored semantics.
• Crate version 0.1.0 → 0.2.0; driver depends on it by path.

azure_data_cosmos_driver (core)

• OperationOptions::hedging_enabled: Option<bool>
  (#[option(env = "AZURE_COSMOS_HEDGING_ENABLED", overridable)]); a new
  Priority-0 branch in resolve_availability_strategy evaluates it before
  availability_strategy.
• PartitionFailoverOptions::circuit_breaker_enabled_override (env
  AZURE_COSMOS_PPCB_ENABLED_OVERRIDE), applied at the two effective-PPCB
  resolution sites (PartitionEndpointState::new and the LocationStateStore
  account-property refresh).
• Options-layering cleanup (per review): RuntimeEnvConfig,
  DiagnosticsEnvConfig, and ConnectionPoolEnvConfig removed — the builders
  now read env directly (via env_only + parser) or through the shared
  parse_duration_millis_from_env helper. Malformed env values are warn-and-
  ignored (fail-soft); bounds violations still hard-error.

Documentation

• ConfigurationOptions.md _OVERRIDE table updated with both switches and a
  note that PPCB's override is driver-level (outside the per-operation layering).
• CHANGELOG entries in azure_data_cosmos, azure_data_cosmos_driver, and
  azure_data_cosmos_macros.

Out of scope

• PPAF (server-driven) enablement is unchanged.
• The multi-region eligibility gate (should_hedge) and default threshold are
  unchanged.

[Copilot]

Pull request overview

This PR adds environment-driven enablement controls to Cosmos availability features (cross-region read hedging and the per-partition circuit breaker), including an incident-oriented {ENV}_OVERRIDE kill-switch layer that overrides all other configuration sources.

Changes:

• Extended CosmosOptions derive to support #[option(env = "...", overridable)], generating {ENV}_OVERRIDE parsing + a top-priority env_override view layer (via new_with_override).
• Introduced OperationOptions::{hedging_enabled, per_partition_circuit_breaker_enabled} env master/override switches and updated hedging resolution to evaluate the env switch before availability_strategy.
• Consolidated env parsing for connection pool, diagnostics, and runtime refresh interval onto macro-generated from_env(), switching malformed env values to warn-and-ignore (while keeping bounds violations as errors), plus added unit/E2E coverage and docs/changelog updates.

Reviewed changes

Copilot reviewed 24 out of 25 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
sdk/cosmos/azure_data_cosmos/docs/ConfigurationOptions.md	Documents new master/override env vars and precedence.
sdk/cosmos/azure_data_cosmos/CHANGELOG.md	Records SDK-facing env kill switch + master switch additions.
sdk/cosmos/azure_data_cosmos_macros/tests/derive_cosmos_options.rs	Adds tests for lenient boolean parsing (base + override).
sdk/cosmos/azure_data_cosmos_macros/src/view.rs	Adds optional env_override layer + new_with_override constructor generation.
sdk/cosmos/azure_data_cosmos_macros/src/parse.rs	Parses new overridable attribute and derives {ENV}_OVERRIDE names.
sdk/cosmos/azure_data_cosmos_macros/src/lib.rs	Documents the new overridable option attribute behavior.
sdk/cosmos/azure_data_cosmos_macros/src/env.rs	Implements shared env parsing, including lenient bool parsing and override constructors.
sdk/cosmos/azure_data_cosmos_driver/tests/framework/test_client.rs	Exposes runtime for tests that need to inspect runtime-resolved env override state.
sdk/cosmos/azure_data_cosmos_driver/tests/emulator_tests/mod.rs	Registers new emulator E2E test module.
sdk/cosmos/azure_data_cosmos_driver/tests/emulator_tests/driver_hedging_kill_switch.rs	Adds emulator E2E wiring test for AZURE_COSMOS_HEDGING_ENABLED_OVERRIDE.
sdk/cosmos/azure_data_cosmos_driver/src/options/operation_options.rs	Adds overridable hedging/PPCB enablement fields + related tests.
sdk/cosmos/azure_data_cosmos_driver/src/options/mod.rs	Updates re-export to renamed env resolution helper (resolve_duration_ms).
sdk/cosmos/azure_data_cosmos_driver/src/options/env_parsing.rs	Refactors env helpers to “resolve pre-read env value” model; removes direct env reads.
sdk/cosmos/azure_data_cosmos_driver/src/options/diagnostics_options.rs	Migrates diagnostics env parsing to macro-driven config + resolve helpers.
sdk/cosmos/azure_data_cosmos_driver/src/options/connection_pool.rs	Migrates connection-pool env parsing to macro-driven config + resolve helpers (fail-soft malformed env).
sdk/cosmos/azure_data_cosmos_driver/src/driver/runtime.rs	Builds and exposes env_override_operation_options and uses macro-based runtime env config.
sdk/cosmos/azure_data_cosmos_driver/src/driver/routing/partition_endpoint_state.rs	Adds tests verifying PPCB override precedence through resolution.
sdk/cosmos/azure_data_cosmos_driver/src/driver/pipeline/hedging_eligibility.rs	Adds hedging_enabled Priority-0 logic and tests for override precedence/threshold behavior.
sdk/cosmos/azure_data_cosmos_driver/src/driver/cosmos_driver.rs	Wires env_override into init-time and per-operation view construction.
sdk/cosmos/azure_data_cosmos_driver/docs/PARTITION_LEVEL_FAILOVER_SPEC.md	Updates spec sample to include env_override layer in view construction.
sdk/cosmos/azure_data_cosmos_driver/docs/HEDGING_SPEC.md	Updates spec to reflect new env master/override switches and precedence.
sdk/cosmos/azure_data_cosmos_driver/CHANGELOG.md	Records driver-side kill switch + env parsing consolidation behavior change.
sdk/cosmos/azure_data_cosmos_driver/Cargo.toml	Switches macros dependency to local path at v0.2.0.
sdk/cosmos/.cspell.json	Adds new terms used in docs/comments.
Cargo.lock	Updates lockfile for macros crate version/source change.

[analogrelay]

Good start. Some fairly minor design suggestions. Not critically blocking, but this is a good opportunity to fix up all the Options layering (i.e. not just OperationOptions, but also DriverOptions, ConnectionPoolOptions, etc.) to use the same macro.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 27 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

sdk/cosmos/azure_data_cosmos_macros/src/parse.rs:114

• #[options(env_only)] is documented as mutually exclusive with #[options(layers(...))], but the parser currently allows both and will silently ignore layers(...) because env_only short-circuits codegen. This should be rejected at macro-parse time to avoid surprising/ambiguous behavior.

        let (layers, env_only) = parse_options_attr(&ast.attrs)?;
        if !env_only && layers.is_empty() {
            return Err(Error::new(
                ast.ident.span(),
                "missing `#[options(layers(...))]` attribute",
            ));
        }

[FabianMeiswinkel]

LGTM