[smithy-rs] 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._

sdk/aws-runtime/Cargo.toml

@@ -33,6 +33,10 @@ version = "0.55.2"
 path = "../aws-smithy-http"
 version = "0.55.2"
 
+[dependencies.aws-smithy-runtime]
+path = "../aws-smithy-runtime"
+version = "0.55.2"
+
 [dependencies.aws-smithy-runtime-api]
 path = "../aws-smithy-runtime-api"
 version = "0.55.2"

sdk/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",
 ]

sdk/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;

sdk/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.");
+    }
+}

sdk/aws-smithy-runtime/Cargo.toml

@@ -23,7 +23,7 @@ http = "0.2.8"
 http-body = "0.4.5"
 pin-project-lite = "0.2.7"
 pin-utils = "0.1.0"
-tracing = "0.1"
+tracing = "0.1.37"
 
 [dependencies.aws-smithy-async]
 path = "../aws-smithy-async"

sdk/aws-smithy-runtime/src/client/orchestrator.rs

@@ -23,6 +23,7 @@ mod auth;
 /// Defines types that implement a trait for endpoint resolution
 pub mod endpoints;
 mod http;
+pub mod interceptors;
 
 #[doc(hidden)]
 #[macro_export]

sdk/aws-smithy-runtime/src/client/orchestrator/interceptors.rs

@@ -0,0 +1,10 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+mod request_attempts;
+mod service_clock_skew;
+
+pub use request_attempts::{RequestAttempts, RequestAttemptsInterceptor};
+pub use service_clock_skew::{ServiceClockSkew, ServiceClockSkewInterceptor};

sdk/aws-smithy-runtime/src/client/orchestrator/interceptors/request_attempts.rs

@@ -0,0 +1,68 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+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;
+
+#[derive(Debug, Clone, Default)]
+#[non_exhaustive]
+pub struct RequestAttempts {
+    attempts: u32,
+}
+
+impl RequestAttempts {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    // There is no legitimate reason to set this unless you're testing things.
+    // Therefore, this is only available for tests.
+    #[cfg(test)]
+    pub fn new_with_attempts(attempts: u32) -> Self {
+        Self { attempts }
+    }
+
+    pub fn attempts(&self) -> u32 {
+        self.attempts
+    }
+
+    fn increment(mut self) -> Self {
+        self.attempts += 1;
+        self
+    }
+}
+
+#[derive(Debug, Default)]
+#[non_exhaustive]
+pub struct RequestAttemptsInterceptor {}
+
+impl RequestAttemptsInterceptor {
+    pub fn new() -> Self {
+        Self::default()
+    }
+}
+
+impl Interceptor for RequestAttemptsInterceptor {
+    fn modify_before_retry_loop(
+        &self,
+        _ctx: &mut InterceptorContext<BeforeTransmit>,
+        cfg: &mut ConfigBag,
+    ) -> Result<(), BoxError> {
+        cfg.put(RequestAttempts::new());
+        Ok(())
+    }
+
+    fn modify_before_transmit(
+        &self,
+        _ctx: &mut InterceptorContext<BeforeTransmit>,
+        cfg: &mut ConfigBag,
+    ) -> Result<(), BoxError> {
+        if let Some(request_attempts) = cfg.get::<RequestAttempts>().cloned() {
+            cfg.put(request_attempts.increment());
+        }
+        Ok(())
+    }
+}