cosmos: add configurable TLS backend, enforced on reqwest (#4649)

## Problem

The driver does not expose direct access to its HTTP transport (and
won't, in a supported fashion). As a result, customers have no supported
way to assert a specific TLS backend on the officially-supported
`reqwest` transport.

## Change

Introduces a supported, forward-looking mechanism to select and enforce
the TLS backend.

- **`TlsBackend` enum** — `#[non_exhaustive]`, one variant
`TlsBackend::Rustls` (the `#[default]`). Added to
`azure_data_cosmos_driver` and re-exported from `azure_data_cosmos`.
- **`ConnectionPoolOptions::tls_backend`** — new option with
`ConnectionPoolOptionsBuilder::with_tls_backend` and a `tls_backend()`
getter, defaulting to `Rustls`. Builder-only (intentionally **not**
environment-configurable).
- **Enforced on reqwest** — `DefaultHttpClientFactory::build` selects
the backend and calls `reqwest::ClientBuilder::tls_backend_rustls()`.
The call is cfg-gated on the `rustls` feature because that reqwest
method only exists when reqwest's rustls backend is compiled in; under a
different TLS feature the reqwest default applies.

Because there is a single variant and it is the default, **no customer
configuration is required today**. The value is forward-looking: it lets
us add new backends in a supported way, and (once #4616 lands) hand the
selected backend to a user-provided `HttpClientFactory`.

## Files

- `options/policies.rs` — new `TlsBackend` enum.
- `options/mod.rs` (driver) and `options/mod.rs` (SDK) — export /
re-export `TlsBackend`.
- `options/connection_pool.rs` — `tls_backend` field, builder field,
`with_tls_backend`, getter, default wiring; extended option tests.
- `driver/transport/http_client_factory.rs` — enforce the backend on the
reqwest builder; factory build test.
- `CHANGELOG.md` (driver `0.6.0`, SDK `0.37.0`) — Features Added
entries.

## Testing & coverage

**Unit (added):**
- `connection_pool_options_builder_defaults` — default `tls_backend()`
is `Rustls`.
- `connection_pool_options_builder_custom_values` — `with_tls_backend()`
round-trips through the builder.
- `default_factory_builds_client_with_default_tls_backend`
(`reqwest`-gated) — builds a real `reqwest::Client` with the default
backend, exercising `tls_backend_rustls()` and asserting `build()`
succeeds.

**Suites / static checks (green):** 1878 driver lib unit tests; `cargo
clippy --all-features --all-targets`; `cargo doc`; `cargo fmt --check`;
cSpell. Compile verified for both the `rustls` and the `not(rustls)`
(`reqwest` + `native_tls`) feature paths — the main risk surface for the
cfg-gated call.

**Integration testing:** No dedicated integration test is added, by
design. `Rustls` is the only variant and the default, and the default
feature set already used reqwest-over-rustls — so behavior is unchanged
and the existing emulator/recorded integration suites already exercise
the rustls transport path end-to-end. A bespoke test could not assert
more, because reqwest exposes no API to introspect which TLS backend
negotiated a connection; the added factory test already proves the
client builds and runs with the enforced backend.

Fixes #4641.

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

Author: ananth7592

sdk/cosmos/azure_data_cosmos/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Features Added
 
+- Added `TlsBackend` (re-exported) and a `tls_backend` option on `ConnectionPoolOptions` (`ConnectionPoolOptionsBuilder::with_tls_backend`), defaulting to `TlsBackend::Rustls`, available under the `rustls` feature, to pin the TLS backend used by the transport. This is additive and changes no behavior for the default (rustls) build; it only has an effect in builds that compile in multiple reqwest TLS backends, where reqwest would otherwise default to native-tls and the driver now pins rustls instead. ([#4649](https://github.com/Azure/azure-sdk-for-rust/pull/4649))
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/cosmos/azure_data_cosmos/src/options/mod.rs

@@ -20,7 +20,7 @@ pub use azure_data_cosmos_driver::options::{
     ReadConsistencyStrategy, Region, ServerCertificateValidation, ThrottlingRetryOptions,
     ThrottlingRetryOptionsBuilder, ThrottlingRetryOptionsView, ThroughputControlGroupOptions,
     ThroughputControlOptions, ThroughputControlOptionsBuilder, ThroughputControlOptionsView,
-    UserAgentSuffix,
+    TlsBackend, UserAgentSuffix,
 };
 pub use batch::{
     BatchDeleteOptions, BatchOptions, BatchReadOptions, BatchReplaceOptions, BatchUpsertOptions,

sdk/cosmos/azure_data_cosmos_driver/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Features Added
 
+- Added `TlsBackend` (currently `TlsBackend::Rustls`, the default) and a `tls_backend` option on `ConnectionPoolOptions` (`ConnectionPoolOptionsBuilder::with_tls_backend` / `ConnectionPoolOptions::tls_backend`), available under the `rustls` feature. The driver asserts the selected backend on the `reqwest` transport, giving a supported way to pin the TLS backend without direct transport access. This is additive and changes no behavior for the default (rustls-only) build, where reqwest already negotiates rustls; it only has an effect in builds that compile in multiple reqwest TLS backends (e.g. `rustls` plus `native_tls`, absent reqwest's `http3` feature), where reqwest would otherwise default to native-tls and the driver now pins rustls instead. ([#4649](https://github.com/Azure/azure-sdk-for-rust/pull/4649))
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/cosmos/azure_data_cosmos_driver/src/driver/transport/http_client_factory.rs

@@ -134,6 +134,22 @@ mod tests {
         assert!(!config.allow_invalid_cert);
         assert!(config.with_allow_invalid_cert().allow_invalid_cert);
     }
+
+    #[cfg(feature = "rustls")]
+    #[test]
+    fn default_factory_builds_client_with_default_tls_backend() {
+        // The default backend is `TlsBackend::Rustls`; building the client must
+        // succeed (i.e. `tls_backend_rustls()` is wired up under the `rustls`
+        // feature).
+        let pool = ConnectionPoolOptionsBuilder::new().build().unwrap();
+        assert_eq!(pool.tls_backend(), crate::options::TlsBackend::Rustls);
+        let config = HttpClientConfig::metadata(&pool, TransportHttpVersion::Http2);
+        let factory = DefaultHttpClientFactory::new();
+        assert!(
+            factory.build(&pool, config).is_ok(),
+            "building the reqwest client with the default TLS backend should succeed"
+        );
+    }
 }
 
 pub trait HttpClientFactory: fmt::Debug + Send + Sync {
@@ -187,6 +203,19 @@ impl HttpClientFactory for DefaultHttpClientFactory {
             }
         }
 
+        // Enforce the selected TLS backend on the reqwest transport. The driver
+        // does not otherwise expose the transport, so this is the supported way
+        // to assert a specific backend. The whole block compiles in only under
+        // the `rustls` feature: `tls_backend_rustls()` (and the `tls_backend()`
+        // accessor it reads) exist only then. With a different TLS feature the
+        // backend is not driver-selectable and reqwest's own default applies.
+        #[cfg(feature = "rustls")]
+        {
+            builder = match connection_pool.tls_backend() {
+                crate::options::TlsBackend::Rustls => builder.tls_backend_rustls(),
+            };
+        }
+
         builder = match config.version_policy {
             HttpVersionPolicy::Http11Only => {
                 // HTTP/1.1: TCP keepalive for connection liveness detection.

sdk/cosmos/azure_data_cosmos_driver/src/options/connection_pool.rs

@@ -10,6 +10,8 @@ use super::env_parsing::{
     ValidationBounds,
 };
 use crate::options::ServerCertificateValidation;
+#[cfg(feature = "rustls")]
+use crate::options::TlsBackend;
 
 /// Configuration for connection pooling behavior.
 ///
@@ -69,6 +71,9 @@ pub struct ConnectionPoolOptions {
 
     server_certificate_validation: ServerCertificateValidation,
 
+    #[cfg(feature = "rustls")]
+    tls_backend: TlsBackend,
+
     local_address: Option<IpAddr>,
 }
 
@@ -222,6 +227,16 @@ impl ConnectionPoolOptions {
         self.server_certificate_validation
     }
 
+    /// Returns the TLS backend the `reqwest` transport is configured to use.
+    ///
+    /// Only available when the `rustls` feature is enabled. With a different
+    /// TLS feature the backend is not driver-selectable, so there is no honest
+    /// value to report and this accessor is not compiled in.
+    #[cfg(feature = "rustls")]
+    pub fn tls_backend(&self) -> TlsBackend {
+        self.tls_backend
+    }
+
     /// Returns the local IP address to bind to, if set.
     pub fn local_address(&self) -> Option<IpAddr> {
         self.local_address
@@ -390,6 +405,8 @@ pub struct ConnectionPoolOptionsBuilder {
         parser = parse_env_server_cert_validation
     )]
     server_certificate_validation: Option<ServerCertificateValidation>,
+    #[cfg(feature = "rustls")]
+    tls_backend: Option<TlsBackend>,
     #[option(env = "AZURE_COSMOS_LOCAL_ADDRESS")]
     local_address: Option<IpAddr>,
 }
@@ -598,6 +615,17 @@ impl ConnectionPoolOptionsBuilder {
         self
     }
 
+    /// Sets the TLS backend used by the `reqwest` transport.
+    ///
+    /// Defaults to [`TlsBackend::Rustls`] when unset. Only available when the
+    /// `rustls` feature is enabled; with a different TLS feature the backend is
+    /// not driver-selectable.
+    #[cfg(feature = "rustls")]
+    pub fn with_tls_backend(mut self, value: TlsBackend) -> Self {
+        self.tls_backend = Some(value);
+        self
+    }
+
     /// Sets the local IP address to bind to.
     pub fn with_local_address(mut self, addr: IpAddr) -> Self {
         self.local_address = Some(addr);
@@ -888,6 +916,10 @@ impl ConnectionPoolOptionsBuilder {
                 .server_certificate_validation
                 .or(env.server_certificate_validation)
                 .unwrap_or(ServerCertificateValidation::Required),
+            // TLS backend is builder-only (not env-configurable); defaults to
+            // `TlsBackend::Rustls`. Only present under the `rustls` feature.
+            #[cfg(feature = "rustls")]
+            tls_backend: self.tls_backend.unwrap_or_default(),
             // Builder override wins; otherwise the macro-parsed env value (or
             // `None` when unset / unparseable).
             local_address: self.local_address.or(env.local_address),
@@ -1101,6 +1133,21 @@ mod tests {
         );
     }
 
+    #[cfg(feature = "rustls")]
+    #[test]
+    fn tls_backend_defaults_to_rustls_and_is_settable() {
+        // Default build yields `TlsBackend::Rustls`...
+        let defaults = ConnectionPoolOptionsBuilder::new().build().unwrap();
+        assert_eq!(defaults.tls_backend(), TlsBackend::Rustls);
+
+        // ...and the builder round-trips an explicitly set backend.
+        let configured = ConnectionPoolOptionsBuilder::new()
+            .with_tls_backend(TlsBackend::Rustls)
+            .build()
+            .unwrap();
+        assert_eq!(configured.tls_backend(), TlsBackend::Rustls);
+    }
+
     #[test]
     fn min_connect_timeout_too_small() {
         let result = ConnectionPoolOptionsBuilder::new()

sdk/cosmos/azure_data_cosmos_driver/src/options/mod.rs

@@ -45,7 +45,7 @@ pub use operation_options::{
 pub use partition_failover::{PartitionFailoverOptions, PartitionFailoverOptionsBuilder};
 pub use policies::{
     ContentResponseOnWrite, EndToEndOperationLatencyPolicy, ExcludedRegions,
-    ServerCertificateValidation,
+    ServerCertificateValidation, TlsBackend,
 };
 pub use priority::PriorityLevel;
 pub use read_consistency::ReadConsistencyStrategy;

sdk/cosmos/azure_data_cosmos_driver/src/options/policies.rs

@@ -156,6 +156,19 @@ impl ServerCertificateValidation {
     }
 }
 
+/// Selects the TLS backend used by the officially-supported `reqwest` transport.
+///
+/// The driver does not expose direct access to the underlying HTTP transport, so
+/// this option is the supported mechanism for asserting a specific TLS backend.
+/// The default is [`TlsBackend::Rustls`].
+#[non_exhaustive]
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
+pub enum TlsBackend {
+    /// Use the `rustls` TLS backend.
+    #[default]
+    Rustls,
+}
+
 #[cfg(test)]
 mod tests {
     use std::time::Duration;