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()))