Struct Builder

pub struct Builder { /* private fields */ }

Builder for creating a Config.

Implementations

impl Builder

pub fn new() -> Self

Constructs a config builder.

pub fn stalled_stream_protection( self, stalled_stream_protection_config: StalledStreamProtectionConfig, ) -> Self

Set the StalledStreamProtectionConfig to configure protection for stalled streams.

pub fn set_stalled_stream_protection( &mut self, stalled_stream_protection_config: Option<StalledStreamProtectionConfig>, ) -> &mut Self

Set the StalledStreamProtectionConfig to configure protection for stalled streams.

pub fn http_client(self, http_client: impl HttpClient + 'static) -> Self

Sets the HTTP client to use when making requests.

Examples

use std::time::Duration;
use aws_sdk_kms::config::Config;
use aws_smithy_runtime::client::http::hyper_014::HyperClientBuilder;

let https_connector = hyper_rustls::HttpsConnectorBuilder::new()
    .with_webpki_roots()
    .https_only()
    .enable_http1()
    .enable_http2()
    .build();
let hyper_client = HyperClientBuilder::new().build(https_connector);

// This connector can then be given to a generated service Config
let config = my_service_client::Config::builder()
    .endpoint_url("https://example.com")
    .http_client(hyper_client)
    .build();
let client = my_service_client::Client::from_conf(config);

pub fn set_http_client( &mut self, http_client: Option<SharedHttpClient>, ) -> &mut Self

Sets the HTTP client to use when making requests.

Examples

use std::time::Duration;
use aws_sdk_kms::config::{Builder, Config};
use aws_smithy_runtime::client::http::hyper_014::HyperClientBuilder;

fn override_http_client(builder: &mut Builder) {
    let https_connector = hyper_rustls::HttpsConnectorBuilder::new()
        .with_webpki_roots()
        .https_only()
        .enable_http1()
        .enable_http2()
        .build();
    let hyper_client = HyperClientBuilder::new().build(https_connector);
    builder.set_http_client(Some(hyper_client));
}

let mut builder = aws_sdk_kms::Config::builder();
override_http_client(&mut builder);
let config = builder.build();

pub fn endpoint_resolver( self, endpoint_resolver: impl ResolveEndpoint + 'static, ) -> Self

Sets the endpoint resolver to use when making requests.

When unset, the client will used a generated endpoint resolver based on the endpoint resolution rules for aws_sdk_kms.

Note: setting an endpoint resolver will replace any endpoint URL that has been set. This method accepts an endpoint resolver specific to this service. If you want to provide a shared endpoint resolver, use Self::set_endpoint_resolver.

Examples

Create a custom endpoint resolver that resolves a different endpoing per-stage, e.g. staging vs. production.

use aws_sdk_kms::config::endpoint::{ResolveEndpoint, EndpointFuture, Params, Endpoint};
#[derive(Debug)]
struct StageResolver { stage: String }
impl ResolveEndpoint for StageResolver {
    fn resolve_endpoint(&self, params: &Params) -> EndpointFuture<'_> {
        let stage = &self.stage;
        EndpointFuture::ready(Ok(Endpoint::builder().url(format!("{stage}.myservice.com")).build()))
    }
}
let resolver = StageResolver { stage: std::env::var("STAGE").unwrap() };
let config = aws_sdk_kms::Config::builder().endpoint_resolver(resolver).build();
let client = aws_sdk_kms::Client::from_conf(config);

pub fn set_endpoint_resolver( &mut self, endpoint_resolver: Option<SharedEndpointResolver>, ) -> &mut Self

Sets the endpoint resolver to use when making requests.

When unset, the client will used a generated endpoint resolver based on the endpoint resolution rules for aws_sdk_kms.

pub fn retry_config(self, retry_config: RetryConfig) -> Self

Set the retry_config for the builder

Examples

use aws_sdk_kms::config::Config;
use aws_sdk_kms::config::retry::RetryConfig;

let retry_config = RetryConfig::standard().with_max_attempts(5);
let config = Config::builder().retry_config(retry_config).build();

pub fn set_retry_config( &mut self, retry_config: Option<RetryConfig>, ) -> &mut Self

Set the retry_config for the builder

Examples

use aws_sdk_kms::config::{Builder, Config};
use aws_sdk_kms::config::retry::RetryConfig;

fn disable_retries(builder: &mut Builder) {
    let retry_config = RetryConfig::standard().with_max_attempts(1);
    builder.set_retry_config(Some(retry_config));
}

let mut builder = Config::builder();
disable_retries(&mut builder);
let config = builder.build();

pub fn sleep_impl(self, sleep_impl: impl AsyncSleep + 'static) -> Self

Set the sleep_impl for the builder

Examples

use aws_sdk_kms::config::{AsyncSleep, Config, SharedAsyncSleep, Sleep};

#[derive(Debug)]
pub struct ForeverSleep;

impl AsyncSleep for ForeverSleep {
    fn sleep(&self, duration: std::time::Duration) -> Sleep {
        Sleep::new(std::future::pending())
    }
}

let sleep_impl = SharedAsyncSleep::new(ForeverSleep);
let config = Config::builder().sleep_impl(sleep_impl).build();

pub fn set_sleep_impl( &mut self, sleep_impl: Option<SharedAsyncSleep>, ) -> &mut Self

Set the sleep_impl for the builder

Examples

use aws_sdk_kms::config::{AsyncSleep, Builder, Config, SharedAsyncSleep, Sleep};

#[derive(Debug)]
pub struct ForeverSleep;

impl AsyncSleep for ForeverSleep {
    fn sleep(&self, duration: std::time::Duration) -> Sleep {
        Sleep::new(std::future::pending())
    }
}

fn set_never_ending_sleep_impl(builder: &mut Builder) {
    let sleep_impl = SharedAsyncSleep::new(ForeverSleep);
    builder.set_sleep_impl(Some(sleep_impl));
}

let mut builder = Config::builder();
set_never_ending_sleep_impl(&mut builder);
let config = builder.build();

pub fn timeout_config(self, timeout_config: TimeoutConfig) -> Self

Set the timeout_config for the builder

Examples

use aws_sdk_kms::config::Config;
use aws_sdk_kms::config::timeout::TimeoutConfig;

let timeout_config = TimeoutConfig::builder()
    .operation_attempt_timeout(Duration::from_secs(1))
    .build();
let config = Config::builder().timeout_config(timeout_config).build();

pub fn set_timeout_config( &mut self, timeout_config: Option<TimeoutConfig>, ) -> &mut Self

Set the timeout_config for the builder.

Setting this to None has no effect if another source of configuration has set timeouts. If you are attempting to disable timeouts, use TimeoutConfig::disabled

Examples

use aws_sdk_kms::config::{Builder, Config};
use aws_sdk_kms::config::timeout::TimeoutConfig;

fn set_request_timeout(builder: &mut Builder) {
    let timeout_config = TimeoutConfig::builder()
        .operation_attempt_timeout(Duration::from_secs(1))
        .build();
    builder.set_timeout_config(Some(timeout_config));
}

let mut builder = Config::builder();
set_request_timeout(&mut builder);
let config = builder.build();

pub fn retry_partition(self, retry_partition: RetryPartition) -> Self

Set the partition for retry-related state. When clients share a retry partition, they will also share things like token buckets and client rate limiters. By default, all clients for the same service will share a partition.

pub fn set_retry_partition( &mut self, retry_partition: Option<RetryPartition>, ) -> &mut Self

Set the partition for retry-related state. When clients share a retry partition, they will also share things like token buckets and client rate limiters. By default, all clients for the same service will share a partition.

pub fn identity_cache( self, identity_cache: impl ResolveCachedIdentity + 'static, ) -> Self

Set the identity cache for auth.

The identity cache defaults to a lazy caching implementation that will resolve an identity when it is requested, and place it in the cache thereafter. Subsequent requests will take the value from the cache while it is still valid. Once it expires, the next request will result in refreshing the identity.

This configuration allows you to disable or change the default caching mechanism. To use a custom caching mechanism, implement the ResolveCachedIdentity trait and pass that implementation into this function.

Examples

Disabling identity caching:

use aws_sdk_kms::config::IdentityCache;

let config = aws_sdk_kms::Config::builder()
    .identity_cache(IdentityCache::no_cache())
    // ...
    .build();
let client = aws_sdk_kms::Client::from_conf(config);

Customizing lazy caching:

use aws_sdk_kms::config::IdentityCache;
use std::time::Duration;

let config = aws_sdk_kms::Config::builder()
    .identity_cache(
        IdentityCache::lazy()
            // change the load timeout to 10 seconds
            .load_timeout(Duration::from_secs(10))
            .build()
    )
    // ...
    .build();
let client = aws_sdk_kms::Client::from_conf(config);

pub fn set_identity_cache( &mut self, identity_cache: impl ResolveCachedIdentity + 'static, ) -> &mut Self

Set the identity cache for auth.

The identity cache defaults to a lazy caching implementation that will resolve an identity when it is requested, and place it in the cache thereafter. Subsequent requests will take the value from the cache while it is still valid. Once it expires, the next request will result in refreshing the identity.

This configuration allows you to disable or change the default caching mechanism. To use a custom caching mechanism, implement the ResolveCachedIdentity trait and pass that implementation into this function.

Examples

Disabling identity caching:

use aws_sdk_kms::config::IdentityCache;

let config = aws_sdk_kms::Config::builder()
    .identity_cache(IdentityCache::no_cache())
    // ...
    .build();
let client = aws_sdk_kms::Client::from_conf(config);

Customizing lazy caching:

use aws_sdk_kms::config::IdentityCache;
use std::time::Duration;

let config = aws_sdk_kms::Config::builder()
    .identity_cache(
        IdentityCache::lazy()
            // change the load timeout to 10 seconds
            .load_timeout(Duration::from_secs(10))
            .build()
    )
    // ...
    .build();
let client = aws_sdk_kms::Client::from_conf(config);

pub fn interceptor(self, interceptor: impl Intercept + 'static) -> Self

Add an interceptor that runs at specific stages of the request execution pipeline.

Interceptors targeted at a certain stage are executed according to the pre-defined priority. The SDK provides a default set of interceptors. An interceptor configured by this method will run after those default interceptors.

Examples

use aws_smithy_runtime_api::client::interceptors::context::phase::BeforeTransmit;
use aws_smithy_runtime_api::client::interceptors::{Interceptor, InterceptorContext};
use aws_smithy_types::config_bag::ConfigBag;
use aws_sdk_kms::config::Config;

fn base_url() -> String {
    // ...
}

#[derive(Debug)]
pub struct UriModifierInterceptor;
impl Intercept for UriModifierInterceptor {
    fn modify_before_signing(
        &self,
        context: &mut InterceptorContext<BeforeTransmit>,
        _cfg: &mut ConfigBag,
    ) -> Result<(), aws_smithy_runtime_api::client::interceptors::BoxError> {
        let request = context.request_mut();
        let uri = format!("{}{}", base_url(), request.uri().path());
        *request.uri_mut() = uri.parse()?;

        Ok(())
    }
}

let config = Config::builder()
    .interceptor(UriModifierInterceptor)
    .build();

pub fn push_interceptor(&mut self, interceptor: SharedInterceptor) -> &mut Self

Add a SharedInterceptor that runs at specific stages of the request execution pipeline.

Interceptors targeted at a certain stage are executed according to the pre-defined priority. The SDK provides a default set of interceptors. An interceptor configured by this method will run after those default interceptors.

Examples

use aws_smithy_runtime_api::client::interceptors::context::phase::BeforeTransmit;
use aws_smithy_runtime_api::client::interceptors::{Interceptor, InterceptorContext, SharedInterceptor};
use aws_smithy_types::config_bag::ConfigBag;
use aws_sdk_kms::config::{Builder, Config};

fn base_url() -> String {
    // ...
}

fn modify_request_uri(builder: &mut Builder) {
    #[derive(Debug)]
    pub struct UriModifierInterceptor;
    impl Intercept for UriModifierInterceptor {
        fn modify_before_signing(
            &self,
            context: &mut InterceptorContext<BeforeTransmit>,
            _cfg: &mut ConfigBag,
        ) -> Result<(), aws_smithy_runtime_api::client::interceptors::BoxError> {
            let request = context.request_mut();
            let uri = format!("{}{}", base_url(), request.uri().path());
            *request.uri_mut() = uri.parse()?;

            Ok(())
        }
    }
    builder.push_interceptor(SharedInterceptor::new(UriModifierInterceptor));
}

let mut builder = Config::builder();
modify_request_uri(&mut builder);
let config = builder.build();

pub fn set_interceptors( &mut self, interceptors: impl IntoIterator<Item = SharedInterceptor>, ) -> &mut Self

Set SharedInterceptors for the builder.

pub fn time_source(self, time_source: impl TimeSource + 'static) -> Self

Sets the time source used for this service

pub fn set_time_source( &mut self, time_source: Option<SharedTimeSource>, ) -> &mut Self

Sets the time source used for this service

pub fn retry_classifier( self, retry_classifier: impl ClassifyRetry + 'static, ) -> Self

Add type implementing ClassifyRetry that will be used by the RetryStrategy to determine what responses should be retried.

A retry classifier configured by this method will run according to its priority.

Examples

use aws_smithy_runtime_api::client::interceptors::context::InterceptorContext;
use aws_smithy_runtime_api::client::orchestrator::OrchestratorError;
use aws_smithy_runtime_api::client::retries::classifiers::{
    ClassifyRetry, RetryAction, RetryClassifierPriority,
};
use aws_smithy_types::error::metadata::ProvideErrorMetadata;
use aws_smithy_types::retry::ErrorKind;
use std::error::Error as StdError;
use std::marker::PhantomData;
use aws_sdk_kms::config::Config;

const RETRYABLE_ERROR_CODES: &[&str] = [
    // List error codes to be retried here...
];

// When classifying at an operation's error type, classifiers require a generic parameter.
// When classifying the HTTP response alone, no generic is needed.
#[derive(Debug, Default)]
pub struct ErrorCodeClassifier<E> {
    _inner: PhantomData<E>,
}

impl<E> ExampleErrorCodeClassifier<E> {
    pub fn new() -> Self {
        Self {
            _inner: PhantomData,
        }
    }
}

impl<E> ClassifyRetry for ExampleErrorCodeClassifier<E>
where
    // Adding a trait bound for ProvideErrorMetadata allows us to inspect the error code.
    E: StdError + ProvideErrorMetadata + Send + Sync + 'static,
{
    fn classify_retry(&self, ctx: &InterceptorContext) -> RetryAction {
        // Check for a result
        let output_or_error = ctx.output_or_error();
        // Check for an error
        let error = match output_or_error {
            Some(Ok(_)) | None => return RetryAction::NoActionIndicated,
              Some(Err(err)) => err,
        };

        // Downcast the generic error and extract the code
        let error_code = OrchestratorError::as_operation_error(error)
            .and_then(|err| err.downcast_ref::<E>())
            .and_then(|err| err.code());

        // If this error's code is in our list, return an action that tells the RetryStrategy to retry this request.
        if let Some(error_code) = error_code {
            if RETRYABLE_ERROR_CODES.contains(&error_code) {
                return RetryAction::transient_error();
            }
        }

        // Otherwise, return that no action is indicated i.e. that this classifier doesn't require a retry.
        // Another classifier may still classify this response as retryable.
        RetryAction::NoActionIndicated
    }

    fn name(&self) -> &'static str { "Example Error Code Classifier" }
}

let config = Config::builder()
    .retry_classifier(ExampleErrorCodeClassifier::<SomeOperationError>::new())
    .build();

pub fn push_retry_classifier( &mut self, retry_classifier: SharedRetryClassifier, ) -> &mut Self

Add a SharedRetryClassifier that will be used by the RetryStrategy to determine what responses should be retried.

A retry classifier configured by this method will run according to its priority.

Examples

use aws_smithy_runtime_api::client::interceptors::context::InterceptorContext;
use aws_smithy_runtime_api::client::orchestrator::OrchestratorError;
use aws_smithy_runtime_api::client::retries::classifiers::{
    ClassifyRetry, RetryAction, RetryClassifierPriority,
};
use aws_smithy_types::error::metadata::ProvideErrorMetadata;
use aws_smithy_types::retry::ErrorKind;
use std::error::Error as StdError;
use std::marker::PhantomData;
use aws_sdk_kms::config::{Builder, Config};

const RETRYABLE_ERROR_CODES: &[&str] = [
    // List error codes to be retried here...
];
fn set_example_error_code_classifier(builder: &mut Builder) {
    // When classifying at an operation's error type, classifiers require a generic parameter.
    // When classifying the HTTP response alone, no generic is needed.
    #[derive(Debug, Default)]
    pub struct ExampleErrorCodeClassifier<E> {
        _inner: PhantomData<E>,
    }

    impl<E> ExampleErrorCodeClassifier<E> {
        pub fn new() -> Self {
            Self {
                _inner: PhantomData,
            }
        }
    }

    impl<E> ClassifyRetry for ExampleErrorCodeClassifier<E>
    where
        // Adding a trait bound for ProvideErrorMetadata allows us to inspect the error code.
        E: StdError + ProvideErrorMetadata + Send + Sync + 'static,
    {
        fn classify_retry(&self, ctx: &InterceptorContext) -> RetryAction {
            // Check for a result
            let output_or_error = ctx.output_or_error();
            // Check for an error
            let error = match output_or_error {
                Some(Ok(_)) | None => return RetryAction::NoActionIndicated,
                  Some(Err(err)) => err,
            };

            // Downcast the generic error and extract the code
            let error_code = OrchestratorError::as_operation_error(error)
                .and_then(|err| err.downcast_ref::<E>())
                .and_then(|err| err.code());

            // If this error's code is in our list, return an action that tells the RetryStrategy to retry this request.
            if let Some(error_code) = error_code {
                if RETRYABLE_ERROR_CODES.contains(&error_code) {
                    return RetryAction::transient_error();
                }
            }

            // Otherwise, return that no action is indicated i.e. that this classifier doesn't require a retry.
            // Another classifier may still classify this response as retryable.
            RetryAction::NoActionIndicated
        }

        fn name(&self) -> &'static str { "Example Error Code Classifier" }
    }

    builder.push_retry_classifier(ExampleErrorCodeClassifier::<SomeOperationError>::new())
}

let mut builder = Config::builder();
set_example_error_code_classifier(&mut builder);
let config = builder.build();

pub fn set_retry_classifiers( &mut self, retry_classifiers: impl IntoIterator<Item = SharedRetryClassifier>, ) -> &mut Self

Set SharedRetryClassifiers for the builder, replacing any that were previously set.

pub fn app_name(self, app_name: AppName) -> Self

Sets the name of the app that is using the client.

This optional name is used to identify the application in the user agent that gets sent along with requests.

pub fn set_app_name(&mut self, app_name: Option<AppName>) -> &mut Self

Sets the name of the app that is using the client.

This optional name is used to identify the application in the user agent that gets sent along with requests.

pub fn invocation_id_generator( self, gen: impl InvocationIdGenerator + 'static, ) -> Self

Overrides the default invocation ID generator.

The invocation ID generator generates ID values for the amz-sdk-invocation-id header. By default, this will be a random UUID. Overriding it may be useful in tests that examine the HTTP request and need to be deterministic.

pub fn set_invocation_id_generator( &mut self, gen: Option<SharedInvocationIdGenerator>, ) -> &mut Self

Overrides the default invocation ID generator.

The invocation ID generator generates ID values for the amz-sdk-invocation-id header. By default, this will be a random UUID. Overriding it may be useful in tests that examine the HTTP request and need to be deterministic.

pub fn endpoint_url(self, endpoint_url: impl Into<String>) -> Self

Sets the endpoint URL used to communicate with this service Note: this is used in combination with other endpoint rules, e.g. an API that applies a host-label prefix will be prefixed onto this URL. To fully override the endpoint resolver, use Builder::endpoint_resolver.

pub fn set_endpoint_url(&mut self, endpoint_url: Option<String>) -> &mut Self

Sets the endpoint URL used to communicate with this service Note: this is used in combination with other endpoint rules, e.g. an API that applies a host-label prefix will be prefixed onto this URL. To fully override the endpoint resolver, use Builder::endpoint_resolver.

pub fn use_dual_stack(self, use_dual_stack: impl Into<bool>) -> Self

When true, use the dual-stack endpoint. If the configured endpoint does not support dual-stack, dispatching the request MAY return an error.

pub fn set_use_dual_stack(&mut self, use_dual_stack: Option<bool>) -> &mut Self

When true, use the dual-stack endpoint. If the configured endpoint does not support dual-stack, dispatching the request MAY return an error.

pub fn use_fips(self, use_fips: impl Into<bool>) -> Self

When true, send this request to the FIPS-compliant regional endpoint. If the configured endpoint does not have a FIPS compliant endpoint, dispatching the request will return an error.

pub fn set_use_fips(&mut self, use_fips: Option<bool>) -> &mut Self

When true, send this request to the FIPS-compliant regional endpoint. If the configured endpoint does not have a FIPS compliant endpoint, dispatching the request will return an error.

pub fn region(self, region: impl Into<Option<Region>>) -> Self

Sets the AWS region to use when making requests.

Examples

use aws_types::region::Region;
use aws_sdk_kms::config::{Builder, Config};

let config = aws_sdk_kms::Config::builder()
    .region(Region::new("us-east-1"))
    .build();

pub fn set_region(&mut self, region: Option<Region>) -> &mut Self

Sets the AWS region to use when making requests.

pub fn credentials_provider( self, credentials_provider: impl ProvideCredentials + 'static, ) -> Self

Sets the credentials provider for this service

pub fn set_credentials_provider( &mut self, credentials_provider: Option<SharedCredentialsProvider>, ) -> &mut Self

Sets the credentials provider for this service

pub fn behavior_version(self, behavior_version: BehaviorVersion) -> Self

Sets the behavior major version.

Over time, new best-practice behaviors are introduced. However, these behaviors might not be backwards compatible. For example, a change which introduces new default timeouts or a new retry-mode for all operations might be the ideal behavior but could break existing applications.

Examples

Set the behavior major version to latest. This is equivalent to enabling the behavior-version-latest cargo feature.

use aws_sdk_kms::config::BehaviorVersion;

let config = aws_sdk_kms::Config::builder()
    .behavior_version(BehaviorVersion::latest())
    // ...
    .build();
let client = aws_sdk_kms::Client::from_conf(config);

Customizing behavior major version:

use aws_sdk_kms::config::BehaviorVersion;

let config = aws_sdk_kms::Config::builder()
    .behavior_version(BehaviorVersion::v2023_11_09())
    // ...
    .build();
let client = aws_sdk_kms::Client::from_conf(config);

pub fn set_behavior_version( &mut self, behavior_version: Option<BehaviorVersion>, ) -> &mut Self

Sets the behavior major version.

Over time, new best-practice behaviors are introduced. However, these behaviors might not be backwards compatible. For example, a change which introduces new default timeouts or a new retry-mode for all operations might be the ideal behavior but could break existing applications.

Examples

Set the behavior major version to latest. This is equivalent to enabling the behavior-version-latest cargo feature.

use aws_sdk_kms::config::BehaviorVersion;

let config = aws_sdk_kms::Config::builder()
    .behavior_version(BehaviorVersion::latest())
    // ...
    .build();
let client = aws_sdk_kms::Client::from_conf(config);

Customizing behavior major version:

use aws_sdk_kms::config::BehaviorVersion;

let config = aws_sdk_kms::Config::builder()
    .behavior_version(BehaviorVersion::v2023_11_09())
    // ...
    .build();
let client = aws_sdk_kms::Client::from_conf(config);

pub fn behavior_version_latest(self) -> Self

Convenience method to set the latest behavior major version

This is equivalent to enabling the behavior-version-latest Cargo feature

pub fn apply_test_defaults(&mut self) -> &mut Self

Available on crate feature test-util only.

Apply test defaults to the builder

pub fn with_test_defaults(self) -> Self

Available on crate feature test-util only.

Apply test defaults to the builder

pub fn build(self) -> Config

Builds a Config.

Trait Implementations

impl Clone for Builder

fn clone(&self) -> Builder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Builder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Builder

fn default() -> Self

Returns the “default value” for a type.

impl From<&SdkConfig> for Builder

fn from(input: &SdkConfig) -> Self

Converts to this type from the input type.