add: request information header interceptors and plugins (#2641)

## Motivation and Context
<!--- Why is this change required? What problem does it solve? -->
<!--- If it fixes an open issue, please link to the issue here -->
#1793 

## Description
<!--- Describe your changes in detail -->
This adds a runtime plugin which provides support for a request info
header.
The plugin depends upon three interceptors:
- `ServiceClockSkewInterceptor` - tracks the approximate latency between
the client and server
- `RequestAttemptsInterceptor` - tracks the number of attempts made for
a single operation
- `RequestInfoInterceptor` - adds request metadata to outgoing requests.
Works by setting a header.

## Testing
<!--- Please describe in detail how you tested your changes -->
<!--- Include details of your testing environment, and the tests you ran
to -->
<!--- see how your change affects other areas of the code, etc. -->
I wrote one test but need to implement several more

----

_By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice._

aws/rust-runtime/aws-runtime/Cargo.toml

@@ -12,6 +12,7 @@ aws-credential-types = { path = "../aws-credential-types" }
 aws-http = { path = "../aws-http" }
 aws-sigv4 = { path = "../aws-sigv4" }
 aws-smithy-http = { path = "../../../rust-runtime/aws-smithy-http" }
+aws-smithy-runtime = { path = "../../../rust-runtime/aws-smithy-runtime" }
 aws-smithy-runtime-api = { path = "../../../rust-runtime/aws-smithy-runtime-api" }
 aws-smithy-types = { path = "../../../rust-runtime/aws-smithy-types" }
 aws-types = { path = "../aws-types" }

aws/rust-runtime/aws-runtime/external-types.toml

@@ -5,6 +5,10 @@ allowed_external_types = [
     "aws_smithy_types::*",
     "aws_smithy_runtime_api::*",
     "aws_types::*",
+    # TODO(audit-external-type-usage) We should newtype these or otherwise avoid exposing them
+    "http::header::name::HeaderName",
+    "http::header::value::HeaderValue",
     "http::request::Request",
     "http::response::Response",
+    "http::uri::Uri",
 ]

aws/rust-runtime/aws-runtime/src/lib.rs

@@ -30,3 +30,6 @@ pub mod retries;
 
 /// Supporting code for invocation ID headers in the AWS SDK.
 pub mod invocation_id;
+
+/// Supporting code for request metadata headers in the AWS SDK.
+pub mod request_info;

aws/rust-runtime/aws-runtime/src/request_info.rs

@@ -0,0 +1,224 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+use aws_smithy_runtime::client::orchestrator::interceptors::{RequestAttempts, ServiceClockSkew};
+use aws_smithy_runtime_api::client::interceptors::context::phase::BeforeTransmit;
+use aws_smithy_runtime_api::client::interceptors::{BoxError, Interceptor, InterceptorContext};
+use aws_smithy_runtime_api::config_bag::ConfigBag;
+use aws_smithy_types::date_time::Format;
+use aws_smithy_types::retry::RetryConfig;
+use aws_smithy_types::timeout::TimeoutConfig;
+use aws_smithy_types::DateTime;
+use http::{HeaderName, HeaderValue};
+use std::borrow::Cow;
+use std::time::{Duration, SystemTime};
+
+#[allow(clippy::declare_interior_mutable_const)] // we will never mutate this
+const AMZ_SDK_REQUEST: HeaderName = HeaderName::from_static("amz-sdk-request");
+
+/// Generates and attaches a request header that communicates request-related metadata.
+/// Examples include:
+///
+/// - When the client will time out this request.
+/// - How many times the request has been retried.
+/// - The maximum number of retries that the client will attempt.
+#[non_exhaustive]
+#[derive(Debug, Default)]
+pub struct RequestInfoInterceptor {}
+
+impl RequestInfoInterceptor {
+    /// Creates a new `RequestInfoInterceptor`
+    pub fn new() -> Self {
+        RequestInfoInterceptor {}
+    }
+}
+
+impl RequestInfoInterceptor {
+    fn build_attempts_pair(
+        &self,
+        cfg: &ConfigBag,
+    ) -> Option<(Cow<'static, str>, Cow<'static, str>)> {
+        let request_attempts = cfg
+            .get::<RequestAttempts>()
+            .map(|r_a| r_a.attempts())
+            .unwrap_or(1);
+        let request_attempts = request_attempts.to_string();
+        Some((Cow::Borrowed("attempt"), Cow::Owned(request_attempts)))
+    }
+
+    fn build_max_attempts_pair(
+        &self,
+        cfg: &ConfigBag,
+    ) -> Option<(Cow<'static, str>, Cow<'static, str>)> {
+        // TODO(enableNewSmithyRuntime) What config will we actually store in the bag? Will it be a whole config or just the max_attempts part?
+        if let Some(retry_config) = cfg.get::<RetryConfig>() {
+            let max_attempts = retry_config.max_attempts().to_string();
+            Some((Cow::Borrowed("max"), Cow::Owned(max_attempts)))
+        } else {
+            None
+        }
+    }
+
+    fn build_ttl_pair(&self, cfg: &ConfigBag) -> Option<(Cow<'static, str>, Cow<'static, str>)> {
+        let timeout_config = cfg.get::<TimeoutConfig>()?;
+        let socket_read = timeout_config.read_timeout()?;
+        let estimated_skew: Duration = cfg.get::<ServiceClockSkew>().cloned()?.into();
+        let current_time = SystemTime::now();
+        let ttl = current_time.checked_add(socket_read + estimated_skew)?;
+        let timestamp = DateTime::from(ttl);
+        let formatted_timestamp = timestamp
+            .fmt(Format::DateTime)
+            .expect("the resulting DateTime will always be valid");
+
+        Some((Cow::Borrowed("ttl"), Cow::Owned(formatted_timestamp)))
+    }
+}
+
+impl Interceptor for RequestInfoInterceptor {
+    fn modify_before_transmit(
+        &self,
+        context: &mut InterceptorContext<BeforeTransmit>,
+        cfg: &mut ConfigBag,
+    ) -> Result<(), BoxError> {
+        let mut pairs = RequestPairs::new();
+        if let Some(pair) = self.build_attempts_pair(cfg) {
+            pairs = pairs.with_pair(pair);
+        }
+        if let Some(pair) = self.build_max_attempts_pair(cfg) {
+            pairs = pairs.with_pair(pair);
+        }
+        if let Some(pair) = self.build_ttl_pair(cfg) {
+            pairs = pairs.with_pair(pair);
+        }
+
+        let headers = context.request_mut().headers_mut();
+        headers.insert(AMZ_SDK_REQUEST, pairs.try_into_header_value()?);
+
+        Ok(())
+    }
+}
+
+/// A builder for creating a `RequestPairs` header value. `RequestPairs` is used to generate a
+/// retry information header that is sent with every request. The information conveyed by this
+/// header allows services to anticipate whether a client will time out or retry a request.
+#[derive(Default, Debug)]
+pub struct RequestPairs {
+    inner: Vec<(Cow<'static, str>, Cow<'static, str>)>,
+}
+
+impl RequestPairs {
+    /// Creates a new `RequestPairs` builder.
+    pub fn new() -> Self {
+        Default::default()
+    }
+
+    /// Adds a pair to the `RequestPairs` builder.
+    /// Only strings that can be converted to header values are considered valid.
+    pub fn with_pair(
+        mut self,
+        pair: (impl Into<Cow<'static, str>>, impl Into<Cow<'static, str>>),
+    ) -> Self {
+        let pair = (pair.0.into(), pair.1.into());
+        self.inner.push(pair);
+        self
+    }
+
+    /// Converts the `RequestPairs` builder into a `HeaderValue`.
+    pub fn try_into_header_value(self) -> Result<HeaderValue, BoxError> {
+        self.try_into()
+    }
+}
+
+impl TryFrom<RequestPairs> for HeaderValue {
+    type Error = BoxError;
+
+    fn try_from(value: RequestPairs) -> Result<Self, BoxError> {
+        let mut pairs = String::new();
+        for (key, value) in value.inner {
+            if !pairs.is_empty() {
+                pairs.push_str("; ");
+            }
+
+            pairs.push_str(&key);
+            pairs.push('=');
+            pairs.push_str(&value);
+            continue;
+        }
+        HeaderValue::from_str(&pairs).map_err(Into::into)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::RequestInfoInterceptor;
+    use crate::request_info::RequestPairs;
+    use aws_smithy_http::body::SdkBody;
+    use aws_smithy_runtime::client::orchestrator::interceptors::RequestAttempts;
+    use aws_smithy_runtime_api::client::interceptors::context::phase::BeforeTransmit;
+    use aws_smithy_runtime_api::client::interceptors::{Interceptor, InterceptorContext};
+    use aws_smithy_runtime_api::config_bag::ConfigBag;
+    use aws_smithy_runtime_api::type_erasure::TypedBox;
+    use aws_smithy_types::retry::RetryConfig;
+    use aws_smithy_types::timeout::TimeoutConfig;
+    use http::HeaderValue;
+    use std::time::Duration;
+
+    fn expect_header<'a>(
+        context: &'a InterceptorContext<BeforeTransmit>,
+        header_name: &str,
+    ) -> &'a str {
+        context
+            .request()
+            .headers()
+            .get(header_name)
+            .unwrap()
+            .to_str()
+            .unwrap()
+    }
+
+    #[test]
+    fn test_request_pairs_for_initial_attempt() {
+        let context = InterceptorContext::<()>::new(TypedBox::new("doesntmatter").erase());
+        let mut context = context.into_serialization_phase();
+        context.set_request(http::Request::builder().body(SdkBody::empty()).unwrap());
+
+        let mut config = ConfigBag::base();
+        config.put(RetryConfig::standard());
+        config.put(
+            TimeoutConfig::builder()
+                .read_timeout(Duration::from_secs(30))
+                .build(),
+        );
+        config.put(RequestAttempts::new());
+
+        let _ = context.take_input();
+        let mut context = context.into_before_transmit_phase();
+        let interceptor = RequestInfoInterceptor::new();
+        interceptor
+            .modify_before_transmit(&mut context, &mut config)
+            .unwrap();
+
+        assert_eq!(
+            expect_header(&context, "amz-sdk-request"),
+            "attempt=0; max=3"
+        );
+    }
+
+    #[test]
+    fn test_header_value_from_request_pairs_supports_all_valid_characters() {
+        // The list of valid characters is defined by an internal-only spec.
+        let rp = RequestPairs::new()
+            .with_pair(("allowed-symbols", "!#$&'*+-.^_`|~"))
+            .with_pair(("allowed-digits", "01234567890"))
+            .with_pair((
+                "allowed-characters",
+                "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ",
+            ))
+            .with_pair(("allowed-whitespace", " \t"));
+        let _header_value: HeaderValue = rp
+            .try_into()
+            .expect("request pairs can be converted into valid header value.");
+    }
+}

aws/sdk-codegen/src/main/kotlin/software/amazon/smithy/rustsdk/AwsCodegenDecorator.kt

@@ -54,6 +54,7 @@ val DECORATORS: List<ClientCodegenDecorator> = listOf(
         DisabledAuthDecorator(),
         RecursionDetectionDecorator(),
         InvocationIdDecorator(),
+        RetryInformationHeaderDecorator(),
     ),
 
     // Service specific decorators

aws/sdk-codegen/src/main/kotlin/software/amazon/smithy/rustsdk/RetryClassifierDecorator.kt

@@ -57,7 +57,7 @@ class RetryClassifierFeature(private val runtimeConfig: RuntimeConfig) : Operati
 
 class OperationRetryClassifiersFeature(
     codegenContext: ClientCodegenContext,
-    operation: OperationShape,
+    operationShape: OperationShape,
 ) : OperationRuntimePluginCustomization() {
     private val runtimeConfig = codegenContext.runtimeConfig
     private val awsRuntime = AwsRuntimeType.awsRuntime(runtimeConfig)
@@ -72,7 +72,7 @@ class OperationRetryClassifiersFeature(
         "RetryReason" to smithyRuntimeApi.resolve("client::retries::RetryReason"),
         "ClassifyRetry" to smithyRuntimeApi.resolve("client::retries::ClassifyRetry"),
         "RetryClassifiers" to smithyRuntimeApi.resolve("client::retries::RetryClassifiers"),
-        "OperationError" to codegenContext.symbolProvider.symbolForOperationError(operation),
+        "OperationError" to codegenContext.symbolProvider.symbolForOperationError(operationShape),
         "SdkError" to RuntimeType.smithyHttp(runtimeConfig).resolve("result::SdkError"),
         "ErasedError" to RuntimeType.smithyRuntimeApi(runtimeConfig).resolve("type_erasure::TypeErasedError"),
     )

aws/sdk-codegen/src/main/kotlin/software/amazon/smithy/rustsdk/RetryInformationHeaderDecorator.kt

@@ -0,0 +1,55 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.rustsdk
+
+import software.amazon.smithy.rust.codegen.client.smithy.ClientCodegenContext
+import software.amazon.smithy.rust.codegen.client.smithy.customize.ClientCodegenDecorator
+import software.amazon.smithy.rust.codegen.client.smithy.generators.ServiceRuntimePluginCustomization
+import software.amazon.smithy.rust.codegen.client.smithy.generators.ServiceRuntimePluginSection
+import software.amazon.smithy.rust.codegen.core.rustlang.Writable
+import software.amazon.smithy.rust.codegen.core.rustlang.rust
+import software.amazon.smithy.rust.codegen.core.rustlang.writable
+import software.amazon.smithy.rust.codegen.core.smithy.RuntimeType
+import software.amazon.smithy.rust.codegen.core.util.letIf
+
+class RetryInformationHeaderDecorator : ClientCodegenDecorator {
+    override val name: String = "RetryInformationHeader"
+    override val order: Byte = 10
+
+    override fun serviceRuntimePluginCustomizations(
+        codegenContext: ClientCodegenContext,
+        baseCustomizations: List<ServiceRuntimePluginCustomization>,
+    ): List<ServiceRuntimePluginCustomization> =
+        baseCustomizations.letIf(codegenContext.smithyRuntimeMode.generateOrchestrator) {
+            it + listOf(AddRetryInformationHeaderInterceptors(codegenContext))
+        }
+}
+
+private class AddRetryInformationHeaderInterceptors(codegenContext: ClientCodegenContext) :
+    ServiceRuntimePluginCustomization() {
+    private val runtimeConfig = codegenContext.runtimeConfig
+    private val smithyRuntime = RuntimeType.smithyRuntime(runtimeConfig)
+    private val awsRuntime = AwsRuntimeType.awsRuntime(runtimeConfig)
+
+    override fun section(section: ServiceRuntimePluginSection): Writable = writable {
+        if (section is ServiceRuntimePluginSection.AdditionalConfig) {
+            // Track the latency between client and server.
+            section.registerInterceptor(runtimeConfig, this) {
+                rust("#T::new()", smithyRuntime.resolve("client::orchestrator::interceptors::ServiceClockSkewInterceptor"))
+            }
+
+            // Track the number of request attempts made.
+            section.registerInterceptor(runtimeConfig, this) {
+                rust("#T::new()", smithyRuntime.resolve("client::orchestrator::interceptors::RequestAttemptsInterceptor"))
+            }
+
+            // Add request metadata to outgoing requests. Sets a header.
+            section.registerInterceptor(runtimeConfig, this) {
+                rust("#T::new()", awsRuntime.resolve("request_info::RequestInfoInterceptor"))
+            }
+        }
+    }
+}

aws/sra-test/integration-tests/aws-sdk-s3/Cargo.toml

@@ -10,6 +10,7 @@ aws-http = { path = "../../../rust-runtime/aws-http" }
 aws-runtime = { path = "../../../rust-runtime/aws-runtime" }
 aws-sdk-s3 = { path = "../../build/sdk/aws-sdk-s3", features = ["test-util"] }
 aws-smithy-client = { path = "../../../../rust-runtime/aws-smithy-client", features = ["test-util", "rustls"] }
+aws-smithy-runtime = { path = "../../../../rust-runtime/aws-smithy-runtime" }
 aws-smithy-runtime-api = { path = "../../../../rust-runtime/aws-smithy-runtime-api" }
 aws-types = { path = "../../../rust-runtime/aws-types" }
 criterion = { version = "0.4", features = ["async_tokio"] }

aws/sra-test/integration-tests/aws-sdk-s3/benches/middleware_vs_orchestrator.rs

@@ -6,7 +6,7 @@
 #[macro_use]
 extern crate criterion;
 use aws_sdk_s3 as s3;
-use aws_smithy_runtime_api::client::interceptors::Interceptors;
+use aws_smithy_runtime_api::client::interceptors::InterceptorRegistrar;
 use aws_smithy_runtime_api::client::runtime_plugin::RuntimePlugin;
 use aws_smithy_runtime_api::config_bag::ConfigBag;
 use criterion::{BenchmarkId, Criterion};
@@ -88,14 +88,15 @@ macro_rules! middleware_bench_fn {
 }
 
 async fn orchestrator(client: &s3::Client) {
+    #[derive(Debug)]
     struct FixupPlugin {
         region: String,
     }
     impl RuntimePlugin for FixupPlugin {
         fn configure(
             &self,
             cfg: &mut ConfigBag,
-            _interceptors: &mut Interceptors,
+            _interceptors: &mut InterceptorRegistrar,
         ) -> Result<(), aws_smithy_runtime_api::client::runtime_plugin::BoxError> {
             let params_builder = s3::endpoint::Params::builder()
                 .set_region(Some(self.region.clone()))