Define distinct ClientOptions in azure_core (#2737)

* Define distinct ClientOptions in azure_core

This sets us up to have Azure-specific client options like UserAgentOptions nee TelemetryOptions. Also allows ability to disable sending the User-Agent like in the Go SDK.

Fixes #1753

* Use deconstruction to efficiently split up ClientOptions

* Fix lint

Author: heaths

sdk/core/azure_core/CHANGELOG.md

@@ -4,18 +4,24 @@
 
 ### Features Added
 
-- Added `get_async_runtime()` and `set_async_runtime()` to allow customers to replace
-the asynchronous runtime used by the Azure SDK.
+- Added `get_async_runtime()` and `set_async_runtime()` to allow customers to replace the asynchronous runtime used by the Azure SDK.
+- Added `UserAgentOptions::enabled` to allow disabling sending the `User-Agent` header.
 
 ### Breaking Changes
 
+- `azure_core::http::Pipeline::new` now takes an `azure_core::http::ClientOptions` which is defined in `azure_core`, but convertible to `typespec_client_core::http::ClientOptions`.
 - Moved `process::Executor` to `azure_identity`.
+- Removed `Pipeline::replace_policy`.
 - Renamed `azure_core::date` to `azure_core::time` and added `azure_core::time::Duration` as the standard "duration" type for the SDK.
+- Renamed `TelemetryOptions` to `UserAgentOptions`.
+- Renamed `TelemetryPolicy` to `UserAgentPolicy`.
 
 ### Bugs Fixed
 
 ### Other Changes
 
+- The `CustomHeadersPolicy` is executed after the retry policy in the `Pipeline`.
+
 ## 0.25.0 (2025-06-06)
 
 ### Features Added

sdk/core/azure_core/src/http/options/mod.rs

@@ -1,10 +1,48 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-mod telemetry;
+mod user_agent;
 
-pub use telemetry::*;
+use std::sync::Arc;
+use typespec_client_core::http::policies::Policy;
 pub use typespec_client_core::http::{
-    ClientMethodOptions, ClientOptions, ExponentialRetryOptions, FixedRetryOptions, RetryOptions,
-    TransportOptions,
+    ClientMethodOptions, ExponentialRetryOptions, FixedRetryOptions, RetryOptions, TransportOptions,
 };
+pub use user_agent::*;
+
+/// Client options allow customization of general client policies, retry options, and more.
+#[derive(Clone, Debug, Default)]
+pub struct ClientOptions {
+    /// Policies called per call.
+    pub per_call_policies: Vec<Arc<dyn Policy>>,
+
+    /// Policies called per try.
+    pub per_try_policies: Vec<Arc<dyn Policy>>,
+
+    /// Retry options.
+    pub retry: Option<RetryOptions>,
+
+    /// Transport options.
+    pub transport: Option<TransportOptions>,
+
+    /// User-Agent telemetry options.
+    pub user_agent: Option<UserAgentOptions>,
+}
+
+impl ClientOptions {
+    /// Efficiently deconstructs into owned [`typespec_client_core::http::ClientOptions`] as well as unwrapped or default Azure-specific options.
+    ///
+    /// If instead we implemented [`Into`], we'd have to clone Azure-specific options instead of moving memory of [`Some`] values.
+    pub(in crate::http) fn deconstruct(
+        self,
+    ) -> (UserAgentOptions, typespec_client_core::http::ClientOptions) {
+        let options = typespec_client_core::http::ClientOptions {
+            per_call_policies: self.per_call_policies,
+            per_try_policies: self.per_try_policies,
+            retry: self.retry,
+            transport: self.transport,
+        };
+
+        (self.user_agent.unwrap_or_default(), options)
+    }
+}

sdk/core/azure_core/src/http/options/telemetry.rs renamed to sdk/core/azure_core/src/http/options/user_agent.rs

@@ -1,9 +1,12 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-/// Telemetry options.
+/// Policy options to telemeter the `User-Agent` header.
 #[derive(Clone, Debug, Default)]
-pub struct TelemetryOptions {
-    /// Set the application ID in the `User-Agent` header that can be telemetered
+pub struct UserAgentOptions {
+    /// Set the application ID in the `User-Agent` header that can be telemetered.
     pub application_id: Option<String>,
+
+    /// Disable to prevent sending the `User-Agent` header in requests.
+    pub disabled: bool,
 }

sdk/core/azure_core/src/http/pipeline.rs

@@ -2,32 +2,31 @@
 // Licensed under the MIT License.
 
 use super::policies::ClientRequestIdPolicy;
-use crate::http::{options::TelemetryOptions, policies::TelemetryPolicy};
+use crate::http::{
+    policies::{Policy, UserAgentPolicy},
+    ClientOptions,
+};
 use std::{
     any::{Any, TypeId},
     ops::Deref,
     sync::Arc,
 };
-use typespec_client_core::http::{self, policies::Policy};
+use typespec_client_core::http;
 
 /// Execution pipeline.
 ///
 /// A pipeline follows a precise flow:
 ///
 /// 1. Client library-specified per-call policies are executed. Per-call policies can fail and bail out of the pipeline
 ///    immediately.
-/// 2. User-specified per-call policies are executed.
-/// 3. Built-in per-call policies are executed. If a [`ClientRequestIdPolicy`] was not added to `per_call_policies`,
-///    the default will be added automatically.
-/// 4. The retry policy is executed. It allows to re-execute the following policies.
-/// 5. Client library-specified per-retry policies. Per-retry polices are always executed at least once but are re-executed
-///    in case of retries.
-/// 6. User-specified per-retry policies are executed.
-/// 7. The authorization policy is executed. Authorization can depend on the HTTP headers and/or the request body so it
-///    must be executed right before sending the request to the transport. Also, the authorization
-///    can depend on the current time so it must be executed at every retry.
-/// 8. The transport policy is executed. Transport policy is always the last policy and is the policy that
-///    actually constructs the `Response` to be passed up the pipeline.
+/// 2. User-specified per-call policies in [`ClientOptions::per_call_policies`] are executed.
+/// 3. The retry policy is executed. It allows to re-execute the following policies.
+/// 4. The [`CustomHeadersPolicy`](crate::http::policies::CustomHeadersPolicy) is executed
+/// 5. Client library-specified per-retry policies. Per-retry polices are always executed at least once but are
+///    re-executed in case of retries.
+/// 6. User-specified per-retry policies in [`ClientOptions::per_try_policies`] are executed.
+/// 7. The transport policy is executed. Transport policy is always the last policy and is the policy that
+///    actually constructs the [`RawResponse`](http::RawResponse) to be passed up the pipeline.
 ///
 /// A pipeline is immutable. In other words a policy can either succeed and call the following
 /// policy of fail and return to the calling policy. Arbitrary policy "skip" must be avoided (but
@@ -45,35 +44,34 @@ impl Pipeline {
     pub fn new(
         crate_name: Option<&'static str>,
         crate_version: Option<&'static str>,
-        options: http::ClientOptions,
+        options: ClientOptions,
         per_call_policies: Vec<Arc<dyn Policy>>,
-        per_retry_policies: Vec<Arc<dyn Policy>>,
+        per_try_policies: Vec<Arc<dyn Policy>>,
     ) -> Self {
         let mut per_call_policies = per_call_policies.clone();
+        push_unique(&mut per_call_policies, ClientRequestIdPolicy::default());
 
-        if per_call_policies
-            .iter()
-            .all(|policy| TypeId::of::<ClientRequestIdPolicy>() != policy.type_id())
-        {
-            per_call_policies.push(Arc::new(ClientRequestIdPolicy::default()));
+        let (user_agent, options) = options.deconstruct();
+        if !user_agent.disabled {
+            let telemetry_policy = UserAgentPolicy::new(crate_name, crate_version, &user_agent);
+            push_unique(&mut per_call_policies, telemetry_policy);
         }
 
-        let telemetry_policy = TelemetryPolicy::new(
-            crate_name,
-            crate_version,
-            // TODO: &options.telemetry.unwrap_or_default(),
-            &TelemetryOptions::default(),
-        );
-        per_call_policies.push(Arc::new(telemetry_policy));
-
         Self(http::Pipeline::new(
             options,
             per_call_policies,
-            per_retry_policies,
+            per_try_policies,
         ))
     }
 }
 
+#[inline]
+fn push_unique<T: Policy + 'static>(policies: &mut Vec<Arc<dyn Policy>>, policy: T) {
+    if policies.iter().all(|p| TypeId::of::<T>() != p.type_id()) {
+        policies.push(Arc::new(policy));
+    }
+}
+
 // TODO: Should we instead use the newtype pattern?
 impl Deref for Pipeline {
     type Target = http::Pipeline;
@@ -90,14 +88,14 @@ mod tests {
             headers::{self, HeaderName, Headers},
             policies::Policy,
             request::options::ClientRequestId,
-            Context, Method, Request, StatusCode, TransportOptions,
+            ClientOptions, Context, Method, RawResponse, Request, StatusCode, TransportOptions,
+            UserAgentOptions,
         },
         Bytes,
     };
     use azure_core_test::http::MockHttpClient;
     use futures::FutureExt as _;
     use std::sync::Arc;
-    use typespec_client_core::http::{ClientOptions, RawResponse};
 
     #[tokio::test]
     async fn pipeline_with_custom_client_request_id_policy() {
@@ -210,4 +208,109 @@ mod tests {
             .await
             .expect("Pipeline execution failed");
     }
+
+    #[tokio::test]
+    async fn pipeline_with_user_agent_enabled_default() {
+        // Arrange
+        let ctx = Context::new();
+
+        let transport = TransportOptions::new(Arc::new(MockHttpClient::new(|req| {
+            async {
+                // Assert
+                let user_agent = req
+                    .headers()
+                    .get_optional_str(&headers::USER_AGENT)
+                    .expect("User-Agent header should be present by default");
+                // The default user agent format is: azsdk-rust-<crate_name>/<crate_version> (<rustc_version>; <OS>; <ARCH>)
+                // Since we can't know the rustc version at runtime, just check the prefix and crate/version
+                assert!(
+                    user_agent.starts_with("azsdk-rust-test-crate/1.0.0 "),
+                    "User-Agent header should start with expected prefix, got: {}",
+                    user_agent
+                );
+
+                Ok(RawResponse::from_bytes(
+                    StatusCode::Ok,
+                    Headers::new(),
+                    Bytes::new(),
+                ))
+            }
+            .boxed()
+        })));
+        let options = ClientOptions {
+            transport: Some(transport),
+            ..Default::default()
+        };
+
+        let per_call_policies = vec![];
+        let per_retry_policies = vec![];
+
+        let pipeline = Pipeline::new(
+            Some("test-crate"),
+            Some("1.0.0"),
+            options,
+            per_call_policies,
+            per_retry_policies,
+        );
+
+        let mut request = Request::new("https://example.com".parse().unwrap(), Method::Get);
+
+        // Act
+        pipeline
+            .send(&ctx, &mut request)
+            .await
+            .expect("Pipeline execution failed");
+    }
+
+    #[tokio::test]
+    async fn pipeline_with_user_agent_disabled() {
+        // Arrange
+        let ctx = Context::new();
+
+        let transport = TransportOptions::new(Arc::new(MockHttpClient::new(|req| {
+            async {
+                // Assert
+                let user_agent = req.headers().get_optional_str(&headers::USER_AGENT);
+                assert!(
+                    user_agent.is_none(),
+                    "User-Agent header should not be present when disabled"
+                );
+
+                Ok(RawResponse::from_bytes(
+                    StatusCode::Ok,
+                    Headers::new(),
+                    Bytes::new(),
+                ))
+            }
+            .boxed()
+        })));
+        let user_agent = UserAgentOptions {
+            disabled: true,
+            ..Default::default()
+        };
+        let options = ClientOptions {
+            transport: Some(transport),
+            user_agent: Some(user_agent),
+            ..Default::default()
+        };
+
+        let per_call_policies = vec![];
+        let per_retry_policies = vec![];
+
+        let pipeline = Pipeline::new(
+            Some("test-crate"),
+            Some("1.0.0"),
+            options,
+            per_call_policies,
+            per_retry_policies,
+        );
+
+        let mut request = Request::new("https://example.com".parse().unwrap(), Method::Get);
+
+        // Act
+        pipeline
+            .send(&ctx, &mut request)
+            .await
+            .expect("Pipeline execution failed");
+    }
 }

sdk/core/azure_core/src/http/policies/mod.rs

@@ -5,9 +5,9 @@
 
 mod bearer_token_policy;
 mod client_request_id;
-mod telemetry;
+mod user_agent;
 
 pub use bearer_token_policy::BearerTokenCredentialPolicy;
 pub use client_request_id::*;
-pub use telemetry::*;
 pub use typespec_client_core::http::policies::*;
+pub use user_agent::*;