google_cloud_gax/

client_builder.rs

// Copyright 2025 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Provide types for client construction.
//!
//! Some applications need to construct clients with custom configuration, for
//! example, they may need to override the endpoint or the authentication
//! credentials. The Google Cloud client libraries for Rust use a generic
//! builder type to provide such functionality. The types in this module
//! implement the client builders.
//!
//! Applications should not create builders directly, instead each client type
//! defines a `builder()` function to obtain the correct type of builder.
//!
//! ## Example: create a client with the default configuration.
//!
//! ```
//! # use google_cloud_gax::client_builder::examples;
//! # use google_cloud_gax::client_builder::Result;
//! # async fn sample() -> anyhow::Result<()> {
//! pub use examples::Client; // Placeholder for examples
//! let client = Client::builder().build().await?;
//! # Ok(()) }
//! ```
//!
//! ## Example: create a client with a different endpoint
//!
//! ```
//! # use google_cloud_gax::client_builder::examples;
//! # use google_cloud_gax::client_builder::Result;
//! # async fn sample() -> anyhow::Result<()> {
//! pub use examples::Client; // Placeholder for examples
//! let client = Client::builder()
//!     .with_endpoint("https://private.googleapis.com")
//!     .build().await?;
//! # Ok(()) }
//! ```

use crate::backoff_policy::{BackoffPolicy, BackoffPolicyArg};
use crate::polling_backoff_policy::{PollingBackoffPolicy, PollingBackoffPolicyArg};
use crate::polling_error_policy::{PollingErrorPolicy, PollingErrorPolicyArg};
use crate::retry_policy::{RetryPolicy, RetryPolicyArg};
use crate::retry_throttler::{RetryThrottlerArg, SharedRetryThrottler};

pub use internal::Extensions;

/// The result type for this module.
pub type Result<T> = std::result::Result<T, Error>;

/// Indicates a problem while constructing a client.
///
/// # Examples
/// ```
/// # use google_cloud_gax::client_builder::examples;
/// use google_cloud_gax::client_builder::Error as Error;
/// use examples::Client; // Placeholder for examples
/// # async fn sample() -> Result<(), Error> {
/// let client = match Client::builder().build().await {
///     Ok(c) => c,
///     Err(e) if e.is_default_credentials() => {
///         println!("error during client initialization: {e}");
///         println!("troubleshoot using https://cloud.google.com/docs/authentication/client-libraries");
///         return Err(e);
///     }
///     Err(e) => {
///         println!("error during client initialization {e}");
///         return Err(e);
///     }
/// };
/// # Ok(()) }
/// ```
#[derive(thiserror::Error, Debug)]
#[error(transparent)]
pub struct Error(ErrorKind);

impl Error {
    /// If true, the client could not initialize the default credentials.
    pub fn is_default_credentials(&self) -> bool {
        matches!(&self.0, ErrorKind::DefaultCredentials(_))
    }

    /// If true, the client could not initialize the transport client.
    pub fn is_transport(&self) -> bool {
        matches!(&self.0, ErrorKind::Transport(_))
    }

    /// If true, the client universe domain does not match the credentials.
    pub fn is_universe_domain_mismatch(&self) -> bool {
        matches!(&self.0, ErrorKind::UniverseDomainMismatch { .. })
    }

    /// Not part of the public API, subject to change without notice.
    #[cfg_attr(not(feature = "_internal-semver"), doc(hidden))]
    pub fn cred<T: Into<BoxError>>(source: T) -> Self {
        Self(ErrorKind::DefaultCredentials(source.into()))
    }

    /// Not part of the public API, subject to change without notice.
    #[cfg_attr(not(feature = "_internal-semver"), doc(hidden))]
    pub fn transport<T: Into<BoxError>>(source: T) -> Self {
        Self(ErrorKind::Transport(source.into()))
    }

    /// Not part of the public API, subject to change without notice.
    #[cfg_attr(not(feature = "_internal-semver"), doc(hidden))]
    pub fn universe_domain_mismatch(
        client_universe_domain: &str,
        credential_universe_domain: &str,
    ) -> Self {
        Self(ErrorKind::UniverseDomainMismatch {
            client_universe_domain: client_universe_domain.to_string(),
            credential_universe_domain: credential_universe_domain.to_string(),
        })
    }
}

#[derive(thiserror::Error, Debug)]
enum ErrorKind {
    #[error("could not create default credentials")]
    DefaultCredentials(#[source] BoxError),
    #[error("could not initialize transport client")]
    Transport(#[source] BoxError),
    #[error(
        "the client configured universe domain ({client_universe_domain}) does not match the universe domain found in the credentials ({credential_universe_domain}). If you haven't configured the universe domain explicitly, `googleapis.com` is the default. Use `ClientBuilder::with_universe_domain()` to set the universe domain."
    )]
    UniverseDomainMismatch {
        client_universe_domain: String,
        credential_universe_domain: String,
    },
}

type BoxError = Box<dyn std::error::Error + Send + Sync + 'static>;

/// A generic builder for clients.
///
/// In the Google Cloud client libraries for Rust a "client" represents a
/// connection to a specific service. Each client library defines one or more
/// client types. All the clients are initialized using a `ClientBuilder`.
///
/// Applications obtain a builder with the correct generic types using the
/// `builder()` method on each client:
/// ```
/// # use google_cloud_gax::client_builder::examples;
/// # use google_cloud_gax::client_builder::Result;
/// # async fn sample() -> anyhow::Result<()> {
/// use examples::Client; // Placeholder for examples
/// let builder = Client::builder();
/// # Ok(()) }
/// ```
///
/// To create a client with the default configuration just invoke the
/// `.build()` method:
/// ```
/// # use google_cloud_gax::client_builder::examples;
/// # use google_cloud_gax::client_builder::Result;
/// # async fn sample() -> anyhow::Result<()> {
/// use examples::Client; // Placeholder for examples
/// let client = Client::builder().build().await?;
/// # Ok(()) }
/// ```
///
/// As usual, the builder offers several method to configure the client, and a
/// `.build()` method to construct the client:
/// ```
/// # use google_cloud_gax::client_builder::examples;
/// # use google_cloud_gax::client_builder::Result;
/// # async fn sample() -> anyhow::Result<()> {
/// use examples::Client; // Placeholder for examples
/// let client = Client::builder()
///     .with_endpoint("http://private.googleapis.com")
///     .build().await?;
/// # Ok(()) }
/// ```
#[derive(Clone, Debug)]
pub struct ClientBuilder<F, Cr> {
    config: internal::ClientConfig<Cr>,
    factory: F,
}

impl<F, Cr> ClientBuilder<F, Cr> {
    /// Creates a new client.
    ///
    /// ```
    /// # use google_cloud_gax::client_builder::examples;
    /// # use google_cloud_gax::client_builder::Result;
    /// # async fn sample() -> anyhow::Result<()> {
    /// use examples::Client; // Placeholder for examples
    /// let client = Client::builder()
    ///     .build().await?;
    /// # Ok(()) }
    /// ```
    pub async fn build<C>(self) -> Result<C>
    where
        F: internal::ClientFactory<Client = C, Credentials = Cr>,
    {
        self.factory.build(self.config).await
    }

    /// Sets the endpoint.
    ///
    /// ```
    /// # use google_cloud_gax::client_builder::examples;
    /// # use google_cloud_gax::client_builder::Result;
    /// # async fn sample() -> anyhow::Result<()> {
    /// use examples::Client; // Placeholder for examples
    /// let client = Client::builder()
    ///     .with_endpoint("http://private.googleapis.com")
    ///     .build().await?;
    /// # Ok(()) }
    /// ```
    pub fn with_endpoint<V: Into<String>>(mut self, v: V) -> Self {
        self.config.endpoint = Some(v.into());
        self
    }

    /// Enables observability signals for the client.
    ///
    /// # Example
    /// ```
    /// # use google_cloud_gax::client_builder::examples;
    /// # use google_cloud_gax::client_builder::Result;
    /// # async fn sample() -> anyhow::Result<()> {
    /// use examples::Client; // Placeholder for examples
    /// let client = Client::builder()
    ///     .with_tracing()
    ///     .build().await?;
    /// // For observing traces and logs, you must also enable a tracing subscriber in your `main` function,
    /// // for example:
    /// //     tracing_subscriber::fmt::init();
    /// // For observing metrics, you must also install an OpenTelemetry meter provider in your `main` function,
    /// // for example:
    /// //     opentelemetry::global::set_meter_provider(provider.clone());
    /// # Ok(()) }
    /// ```
    ///
    /// <div class="warning">
    ///
    /// Observability signals at any level may contain sensitive data such as resource names, full
    /// URLs, and error messages.
    ///
    /// Before configuring subscribers or exporters for traces and logs, review the contents of the
    /// spans and consult the [tracing] framework documentation to set up filters and formatters to
    /// prevent leaking sensitive information, depending on your intended use case.
    ///
    /// [OpenTelemetry Semantic Conventions]: https://opentelemetry.io/docs/concepts/semantic-conventions/
    /// [tracing]: https://docs.rs/tracing/latest/tracing/
    ///
    /// </div>
    ///
    /// The libraries are instrumented to generate the following signals:
    ///
    /// 1. `INFO` spans for each logical client request. Typically a single method call in the client
    ///    struct gets such a span.
    /// 1. A histogram metric measuring the elapsed time for each logical client request.
    /// 1. `WARN` logs for each logical client requests that fail.
    /// 1. `INFO` spans for each low-level attempt RPC attempt. Typically a single method in the client
    ///    struct gets one such span, but there may be more if the library had to retry the RPC.
    /// 1. `DEBUG` logs for each low-level attempt that fails.
    ///
    /// These spans and logs follow [OpenTelemetry Semantic Conventions] with additional Google
    /// Cloud attributes. Both the spans and logs and are should be suitable for production
    /// monitoring.
    ///
    /// The libraries also have `DEBUG` spans for each request, these include the full request body,
    /// and the full response body for successful requests, and the full error message, with
    /// details, for failed requests. Consider the contents of these requests and responses before
    /// enabling them in production environments, as the request or responses may include sensitive
    /// data. These `DEBUG` spans use the client library crate followed by `::tracing` as their
    /// target and the method name as the span name. You can use the name and/or target to set up
    /// your filters.
    ///
    /// # More information
    ///
    /// The [Enable logging] guide shows you how to initialize a subscriber to
    /// log events to the console.
    ///
    /// [Enable logging]: https://docs.cloud.google.com/rust/enable-logging
    pub fn with_tracing(mut self) -> Self {
        self.config.tracing = true;
        self
    }

    /// Configure the authentication credentials.
    ///
    /// Most Google Cloud services require authentication, though some services
    /// allow for anonymous access, and some services provide emulators where
    /// no authentication is required. More information about valid credentials
    /// types can be found in the [google-cloud-auth] crate documentation.
    ///
    /// ```
    /// # use google_cloud_gax::client_builder::examples;
    /// # use google_cloud_gax::client_builder::Result;
    /// # async fn sample() -> anyhow::Result<()> {
    /// use examples::Client; // Placeholder for examples
    /// // Placeholder, normally use google_cloud_auth::credentials
    /// use examples::credentials;
    /// let client = Client::builder()
    ///     .with_credentials(
    ///         credentials::mds::Builder::new()
    ///             .scopes(["https://www.googleapis.com/auth/cloud-platform.read-only"])
    ///             .build())
    ///     .build().await?;
    /// # Ok(()) }
    /// ```
    ///
    /// [google-cloud-auth]: https://docs.rs/google-cloud-auth
    pub fn with_credentials<T: Into<Cr>>(mut self, v: T) -> Self {
        self.config.cred = Some(v.into());
        self
    }

    /// Configure the universe domain.
    ///
    /// The universe domain is the default service domain for a given cloud universe.
    /// The default value is "googleapis.com".
    ///
    /// ```
    /// # use google_cloud_gax::client_builder::examples;
    /// # use google_cloud_gax::client_builder::Result;
    /// # async fn sample() -> anyhow::Result<()> {
    /// use examples::Client; // Placeholder for examples
    /// let client = Client::builder()
    ///     .with_universe_domain("googleapis.com")
    ///     .build().await?;
    /// # Ok(()) }
    /// ```
    pub fn with_universe_domain<V: Into<String>>(mut self, v: V) -> Self {
        self.config.universe_domain = Some(v.into());
        self
    }

    /// Configure the retry policy.
    ///
    /// The client libraries can automatically retry operations that fail. The
    /// retry policy controls what errors are considered retryable, sets limits
    /// on the number of attempts or the time trying to make attempts.
    ///
    /// ```
    /// # use google_cloud_gax::client_builder::examples;
    /// # use google_cloud_gax as gax;
    /// # use google_cloud_gax::client_builder::Result;
    /// # async fn sample() -> anyhow::Result<()> {
    /// use examples::Client; // Placeholder for examples
    /// use gax::retry_policy::{AlwaysRetry, RetryPolicyExt};
    /// let client = Client::builder()
    ///     .with_retry_policy(AlwaysRetry.with_attempt_limit(3))
    ///     .build().await?;
    /// # Ok(()) }
    /// ```
    pub fn with_retry_policy<V: Into<RetryPolicyArg>>(mut self, v: V) -> Self {
        self.config.retry_policy = Some(v.into().into());
        self
    }

    /// Configure the retry backoff policy.
    ///
    /// The client libraries can automatically retry operations that fail. The
    /// backoff policy controls how long to wait in between retry attempts.
    ///
    /// ```
    /// # use google_cloud_gax::client_builder::examples;
    /// # use google_cloud_gax as gax;
    /// # use google_cloud_gax::client_builder::Result;
    /// # async fn sample() -> anyhow::Result<()> {
    /// use examples::Client; // Placeholder for examples
    /// use gax::exponential_backoff::ExponentialBackoff;
    /// use std::time::Duration;
    /// let policy = ExponentialBackoff::default();
    /// let client = Client::builder()
    ///     .with_backoff_policy(policy)
    ///     .build().await?;
    /// # Ok(()) }
    /// ```
    pub fn with_backoff_policy<V: Into<BackoffPolicyArg>>(mut self, v: V) -> Self {
        self.config.backoff_policy = Some(v.into().into());
        self
    }

    /// Configure the per-attempt timeout used as the client default.
    ///
    /// When set, this timeout will be used for each attempt of a request unless
    /// a per-request attempt timeout is provided via RequestOptions. Per-request
    /// settings take precedence.
    pub fn with_attempt_timeout<V: Into<std::time::Duration>>(mut self, v: V) -> Self {
        self.config.attempt_timeout = Some(v.into());
        self
    }

    /// Configure the retry throttler.
    ///
    /// Advanced applications may want to configure a retry throttler to
    /// [Address Cascading Failures] and when [Handling Overload] conditions.
    /// The client libraries throttle their retry loop, using a policy to
    /// control the throttling algorithm. Use this method to fine tune or
    /// customize the default retry throtler.
    ///
    /// [Handling Overload]: https://sre.google/sre-book/handling-overload/
    /// [Address Cascading Failures]: https://sre.google/sre-book/addressing-cascading-failures/
    ///
    /// ```
    /// # use google_cloud_gax::client_builder::examples;
    /// # use google_cloud_gax as gax;
    /// # use google_cloud_gax::client_builder::Result;
    /// # async fn sample() -> anyhow::Result<()> {
    /// use examples::Client; // Placeholder for examples
    /// use gax::retry_throttler::AdaptiveThrottler;
    /// let client = Client::builder()
    ///     .with_retry_throttler(AdaptiveThrottler::default())
    ///     .build().await?;
    /// # Ok(()) }
    /// ```
    pub fn with_retry_throttler<V: Into<RetryThrottlerArg>>(mut self, v: V) -> Self {
        self.config.retry_throttler = v.into().into();
        self
    }

    /// Configure the polling error policy.
    ///
    /// Some clients support long-running operations, the client libraries can
    /// automatically poll these operations until they complete. Polling may
    /// fail due to transient errors and applications may want to continue the
    /// polling loop despite such errors. The polling error policy controls
    /// which errors are treated as recoverable, and may limit the number
    /// of attempts and/or the total time polling the operation.
    ///
    /// ```
    /// # use google_cloud_gax::client_builder::examples;
    /// # use google_cloud_gax as gax;
    /// # use google_cloud_gax::client_builder::Result;
    /// # async fn sample() -> anyhow::Result<()> {
    /// use examples::Client; // Placeholder for examples
    /// use gax::polling_error_policy::Aip194Strict;
    /// use gax::polling_error_policy::PollingErrorPolicyExt;
    /// use std::time::Duration;
    /// let client = Client::builder()
    ///     .with_polling_error_policy(Aip194Strict
    ///         .with_time_limit(Duration::from_secs(15 * 60))
    ///         .with_attempt_limit(50))
    ///     .build().await?;
    /// # Ok(()) }
    /// ```
    pub fn with_polling_error_policy<V: Into<PollingErrorPolicyArg>>(mut self, v: V) -> Self {
        self.config.polling_error_policy = Some(v.into().0);
        self
    }

    /// Configure the polling backoff policy.
    ///
    /// Some clients support long-running operations, the client libraries can
    /// automatically poll these operations until they complete. The polling
    /// backoff policy controls how long the client waits between polling
    /// attempts.
    ///
    /// ```
    /// # use google_cloud_gax::client_builder::examples;
    /// # use google_cloud_gax as gax;
    /// # use google_cloud_gax::client_builder::Result;
    /// # async fn sample() -> anyhow::Result<()> {
    /// use examples::Client; // Placeholder for examples
    /// use gax::exponential_backoff::ExponentialBackoff;
    /// use std::time::Duration;
    /// let policy = ExponentialBackoff::default();
    /// let client = Client::builder()
    ///     .with_polling_backoff_policy(policy)
    ///     .build().await?;
    /// # Ok(()) }
    /// ```
    pub fn with_polling_backoff_policy<V: Into<PollingBackoffPolicyArg>>(mut self, v: V) -> Self {
        self.config.polling_backoff_policy = Some(v.into().0);
        self
    }

    /// Adds a custom extension to the client configuration.
    ///
    /// ```
    /// # use google_cloud_gax::client_builder::examples;
    /// # use google_cloud_gax::client_builder::Result;
    /// # async fn sample() -> anyhow::Result<()> {
    /// use examples::Client; // Placeholder for examples
    ///
    /// struct CustomSetting(String);
    ///
    /// let client = Client::builder()
    ///     .with_extension(CustomSetting("value".to_string()))
    ///     .build()
    ///     .await?;
    /// # Ok(()) }
    /// ```
    ///
    /// Extensions allow storing custom configuration settings in [internal::ClientConfig]
    /// keyed by type. Downstream client libraries or custom factory implementations
    /// can inspect stored extensions to customize client behavior.
    pub fn with_extension<T: Send + Sync + 'static>(mut self, extension: T) -> Self {
        self.config.extensions.insert(extension);
        self
    }
}

#[cfg_attr(not(feature = "_internal-semver"), doc(hidden))]
#[allow(missing_docs)]
pub mod internal {
    use std::any::{Any, TypeId};
    use std::collections::HashMap;
    use std::fmt::{Debug, Formatter, Result as FmtResult};
    use std::sync::Arc;

    use super::*;

    pub trait ClientFactory {
        type Client;
        type Credentials;
        fn build(
            self,
            config: internal::ClientConfig<Self::Credentials>,
        ) -> impl Future<Output = Result<Self::Client>>;
    }

    pub fn new_builder<F, Cr, C>(factory: F) -> super::ClientBuilder<F, Cr>
    where
        F: ClientFactory<Client = C, Credentials = Cr>,
    {
        super::ClientBuilder {
            factory,
            config: ClientConfig::default(),
        }
    }

    /// Configure a client.
    ///
    /// A client represents a connection to a Google Cloud Service. Each service
    /// has one or more client types. The default configuration for each client
    /// should work for most applications. But some applications may need to
    /// override the default endpoint, the default authentication credentials,
    /// the retry policies, and/or other behaviors of the client.
    #[derive(Clone, Debug)]
    #[non_exhaustive]
    pub struct ClientConfig<Cr> {
        pub endpoint: Option<String>,
        pub universe_domain: Option<String>,
        pub cred: Option<Cr>,
        pub tracing: bool,
        pub retry_policy: Option<Arc<dyn RetryPolicy>>,
        pub backoff_policy: Option<Arc<dyn BackoffPolicy>>,
        pub retry_throttler: SharedRetryThrottler,
        pub polling_error_policy: Option<Arc<dyn PollingErrorPolicy>>,
        pub polling_backoff_policy: Option<Arc<dyn PollingBackoffPolicy>>,
        pub attempt_timeout: Option<std::time::Duration>,
        pub disable_automatic_decompression: bool,
        pub disable_follow_redirects: bool,
        pub grpc_subchannel_count: Option<usize>,
        pub grpc_request_buffer_capacity: Option<usize>,
        pub grpc_max_header_list_size: Option<u32>,
        pub extensions: Extensions,
    }

    impl<Cr> std::default::Default for ClientConfig<Cr> {
        fn default() -> Self {
            use crate::retry_throttler::AdaptiveThrottler;
            use std::sync::Mutex;
            Self {
                endpoint: None,
                universe_domain: None,
                cred: None,
                tracing: false,
                retry_policy: None,
                backoff_policy: None,
                retry_throttler: Arc::new(Mutex::new(AdaptiveThrottler::default())),
                polling_error_policy: None,
                polling_backoff_policy: None,
                attempt_timeout: None,
                disable_automatic_decompression: false,
                disable_follow_redirects: false,
                grpc_subchannel_count: None,
                grpc_request_buffer_capacity: None,
                grpc_max_header_list_size: None,
                extensions: Extensions::new(),
            }
        }
    }

    /// A type-erased map of configuration extensions.
    #[derive(Clone, Default)]
    pub struct Extensions {
        map: HashMap<TypeId, Arc<dyn Any + Send + Sync>>,
    }

    impl Extensions {
        pub fn new() -> Self {
            Self::default()
        }

        pub fn insert<T: Send + Sync + 'static>(&mut self, val: T) {
            self.map.insert(TypeId::of::<T>(), Arc::new(val));
        }

        pub fn get<T: 'static>(&self) -> Option<&T> {
            self.map
                .get(&TypeId::of::<T>())
                .and_then(|boxed| boxed.as_ref().downcast_ref::<T>())
        }
    }

    impl Debug for Extensions {
        fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
            f.debug_struct("Extensions")
                .field("len", &self.map.len())
                .finish()
        }
    }

    /// Configure automatic decompression.
    ///
    /// By default, the client libraries automatically decompress responses.
    /// Internal users can disable this behavior if they need to access the raw
    /// compressed bytes.
    pub fn with_automatic_decompression<F, Cr>(
        mut builder: super::ClientBuilder<F, Cr>,
        v: bool,
    ) -> super::ClientBuilder<F, Cr> {
        builder.config.disable_automatic_decompression = !v;
        builder
    }

    /// Configure HTTP redirects.
    ///
    /// By default, the client libraries automatically follow HTTP redirects.
    /// Internal users can disable this behavior if they need to handle redirects
    /// manually (e.g. for 308 Resume Incomplete).
    pub fn with_follow_redirects<F, Cr>(
        mut builder: super::ClientBuilder<F, Cr>,
        v: bool,
    ) -> super::ClientBuilder<F, Cr> {
        builder.config.disable_follow_redirects = !v;
        builder
    }
}

#[doc(hidden)]
pub mod examples {
    //! This module contains helper types used in the rustdoc examples.
    //!
    //! The examples require relatively complex types to be useful.

    type Config = super::internal::ClientConfig<Credentials>;
    use super::Result;

    /// A client type for use in examples.
    ///
    /// This type is used in examples as a placeholder for a real client. It
    /// does not work, but illustrates how to use `ClientBuilder`.
    #[allow(dead_code)]
    pub struct Client(Config);
    impl Client {
        /// Create a builder to initialize new instances of this client.
        pub fn builder() -> client::Builder {
            super::internal::new_builder(client::Factory)
        }

        async fn new(config: super::internal::ClientConfig<Credentials>) -> Result<Self> {
            Ok(Self(config))
        }
    }
    mod client {
        pub type Builder = super::super::ClientBuilder<Factory, super::Credentials>;
        pub struct Factory;
        impl super::super::internal::ClientFactory for Factory {
            type Credentials = super::Credentials;
            type Client = super::Client;
            async fn build(
                self,
                config: crate::client_builder::internal::ClientConfig<Self::Credentials>,
            ) -> super::Result<Self::Client> {
                Self::Client::new(config).await
            }
        }
    }

    #[derive(Clone, Debug, Default, PartialEq)]
    pub struct Credentials {
        pub scopes: Vec<String>,
    }

    pub mod credentials {
        pub mod mds {
            #[derive(Clone, Default)]
            pub struct Builder(super::super::Credentials);
            impl Builder {
                pub fn new() -> Self {
                    Self(super::super::Credentials::default())
                }
                pub fn build(self) -> super::super::Credentials {
                    self.0
                }
                pub fn scopes<I, V>(mut self, iter: I) -> Self
                where
                    I: IntoIterator<Item = V>,
                    V: Into<String>,
                {
                    self.0.scopes = iter.into_iter().map(|v| v.into()).collect();
                    self
                }
            }
        }
    }

    // We use the examples as scaffolding for the tests.
    #[cfg(test)]
    mod tests {
        use super::*;
        use std::time::Duration;

        #[tokio::test]
        async fn build_default() {
            let client = Client::builder().build().await.unwrap();
            let config = client.0;
            assert_eq!(config.endpoint, None);
            assert_eq!(config.cred, None);
            assert!(!config.tracing);
            assert!(
                format!("{config:?}").contains("AdaptiveThrottler"),
                "{config:?}"
            );
            assert!(config.retry_policy.is_none(), "{config:?}");
            assert!(config.backoff_policy.is_none(), "{config:?}");
            assert!(config.polling_error_policy.is_none(), "{config:?}");
            assert!(config.polling_backoff_policy.is_none(), "{config:?}");
            assert!(!config.disable_automatic_decompression, "{config:?}");
            assert!(!config.disable_follow_redirects, "{config:?}");
        }

        #[tokio::test]
        async fn endpoint() {
            let client = Client::builder()
                .with_endpoint("http://example.com")
                .build()
                .await
                .unwrap();
            let config = client.0;
            assert_eq!(config.endpoint.as_deref(), Some("http://example.com"));
        }

        #[tokio::test]
        async fn tracing() {
            let client = Client::builder().with_tracing().build().await.unwrap();
            let config = client.0;
            assert!(config.tracing);
        }

        #[tokio::test]
        async fn automatic_decompression() {
            let client = Client::builder();
            let client = super::super::internal::with_automatic_decompression(client, false)
                .build()
                .await
                .unwrap();
            let config = client.0;
            assert!(config.disable_automatic_decompression);

            let client = Client::builder();
            let client = super::super::internal::with_automatic_decompression(client, true)
                .build()
                .await
                .unwrap();
            let config = client.0;
            assert!(!config.disable_automatic_decompression);
        }

        #[tokio::test]
        async fn follow_redirects() {
            let client = Client::builder();
            let client = super::super::internal::with_follow_redirects(client, false)
                .build()
                .await
                .unwrap();
            let config = client.0;
            assert!(config.disable_follow_redirects);

            let client = Client::builder();
            let client = super::super::internal::with_follow_redirects(client, true)
                .build()
                .await
                .unwrap();
            let config = client.0;
            assert!(!config.disable_follow_redirects);
        }

        #[tokio::test]
        async fn credentials() {
            let client = Client::builder()
                .with_credentials(
                    credentials::mds::Builder::new()
                        .scopes(["test-scope"])
                        .build(),
                )
                .build()
                .await
                .unwrap();
            let config = client.0;
            let cred = config.cred.unwrap();
            assert_eq!(cred.scopes, vec!["test-scope".to_string()]);
        }

        #[tokio::test]
        async fn universe_domain() {
            let client = Client::builder()
                .with_universe_domain("some-universe-domain.com")
                .build()
                .await
                .unwrap();
            let config = client.0;
            assert_eq!(
                config.universe_domain,
                Some("some-universe-domain.com".to_string())
            );
        }

        #[tokio::test]
        async fn attempt_timeout() {
            let timeout = Duration::from_secs(42);
            let client = Client::builder()
                .with_attempt_timeout(timeout)
                .build()
                .await
                .unwrap();
            let config = client.0;
            assert_eq!(config.attempt_timeout, Some(timeout));
        }

        #[tokio::test]
        async fn retry_policy() {
            use crate::retry_policy::RetryPolicyExt;
            let client = Client::builder()
                .with_retry_policy(crate::retry_policy::AlwaysRetry.with_attempt_limit(3))
                .build()
                .await
                .unwrap();
            let config = client.0;
            assert!(config.retry_policy.is_some(), "{config:?}");
        }

        #[tokio::test]
        async fn backoff_policy() {
            let client = Client::builder()
                .with_backoff_policy(crate::exponential_backoff::ExponentialBackoff::default())
                .build()
                .await
                .unwrap();
            let config = client.0;
            assert!(config.backoff_policy.is_some(), "{config:?}");
        }

        #[tokio::test]
        async fn retry_throttler() {
            use crate::retry_throttler::CircuitBreaker;
            let client = Client::builder()
                .with_retry_throttler(CircuitBreaker::default())
                .build()
                .await
                .unwrap();
            let config = client.0;
            assert!(
                format!("{config:?}").contains("CircuitBreaker"),
                "{config:?}"
            );
        }

        #[tokio::test]
        async fn polling_error_policy() {
            use crate::polling_error_policy::PollingErrorPolicyExt;
            let client = Client::builder()
                .with_polling_error_policy(
                    crate::polling_error_policy::AlwaysContinue.with_attempt_limit(3),
                )
                .build()
                .await
                .unwrap();
            let config = client.0;
            assert!(config.polling_error_policy.is_some(), "{config:?}");
        }

        #[tokio::test]
        async fn polling_backoff_policy() {
            let client = Client::builder()
                .with_polling_backoff_policy(
                    crate::exponential_backoff::ExponentialBackoff::default(),
                )
                .build()
                .await
                .unwrap();
            let config = client.0;
            assert!(config.polling_backoff_policy.is_some(), "{config:?}");
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::error::Error as _;

    #[test]
    fn error_credentials() {
        let source = wkt::TimestampError::OutOfRange;
        let error = Error::cred(source);
        assert!(error.is_default_credentials(), "{error:?}");
        assert!(error.to_string().contains("default credentials"), "{error}");
        let got = error
            .source()
            .and_then(|e| e.downcast_ref::<wkt::TimestampError>());
        assert!(
            matches!(got, Some(wkt::TimestampError::OutOfRange)),
            "{error:?}"
        );
    }

    #[test]
    fn transport() {
        let source = wkt::TimestampError::OutOfRange;
        let error = Error::transport(source);
        assert!(error.is_transport(), "{error:?}");
        assert!(error.to_string().contains("transport client"), "{error}");
        let got = error
            .source()
            .and_then(|e| e.downcast_ref::<wkt::TimestampError>());
        assert!(
            matches!(got, Some(wkt::TimestampError::OutOfRange)),
            "{error:?}"
        );
    }

    #[test]
    fn universe_domain_mismatch() {
        let error = Error::universe_domain_mismatch("my-universe.com", "googleapis.com");
        assert!(error.is_universe_domain_mismatch(), "{error:?}");
        let fmt = format!("{error:?}");
        assert!(fmt.contains("my-universe.com"), "{fmt}");
        assert!(fmt.contains("googleapis.com"), "{fmt}");
        let got = error.source();
        assert!(got.is_none(), "{got:?}");
    }

    #[test]
    fn client_config_clone_with_extensions() {
        let mut config = internal::ClientConfig::<()>::default();
        config.extensions.insert(42i32);
        let cloned = config.clone();
        assert_eq!(cloned.extensions.get::<i32>(), Some(&42));
    }

    #[test]
    fn auto_traits() {
        use static_assertions::{assert_impl_all, assert_not_impl_any};
        use std::panic::{RefUnwindSafe, UnwindSafe};

        assert_impl_all!(ClientBuilder<(), ()>: Send, Sync, Clone, std::fmt::Debug, Unpin);
        assert_not_impl_any!(ClientBuilder<(), ()>: RefUnwindSafe, UnwindSafe);

        assert_impl_all!(internal::ClientConfig<()>: Send, Sync, Clone, std::fmt::Debug, Default, Unpin);
        assert_not_impl_any!(internal::ClientConfig<()>: RefUnwindSafe, UnwindSafe);

        assert_impl_all!(internal::Extensions: Send, Sync, Clone, std::fmt::Debug, Default, Unpin);
        assert_not_impl_any!(internal::Extensions: RefUnwindSafe, UnwindSafe);
    }
}