Feature: Customizable Operations

CHANGELOG.next.toml

@@ -50,7 +50,7 @@ author = "Velfi"
 [[smithy-rs]]
 message = "Add codegen version to generated package metadata"
 references = ["smithy-rs#1612"]
-meta = { "breaking" = false, "tada" = false, "bug" = false }
+meta = { "breaking" = false, "tada" = false, "bug" = false, "target" = "all" }
 author = "unexge"
 
 [[smithy-rs]]
@@ -94,7 +94,7 @@ Then all runtime crates are set with version 0.47.0 by default unless overridden
 implies that we're using `aws-smithy-http` 0.47.1 specifically. For the rest of the crates, it will default to 0.47.0.
 """
 references = ["smithy-rs#1635", "smithy-rs#1416"]
-meta = { "breaking" = true, "tada" = true, "bug" = false }
+meta = { "breaking" = true, "tada" = true, "bug" = false, "target" = "all" }
 author = "weihanglo"
 
 [[smithy-rs]]
@@ -108,6 +108,102 @@ references = ["smithy-rs#1544"]
 meta = { "breaking" = true, "tada" = false, "bug" = false, "target" = "server" }
 author = "82marbag"
 
+[[aws-sdk-rust]]
+message = """
+Implemented customizable operations per [RFC-0017](https://awslabs.github.io/smithy-rs/design/rfcs/rfc0017_customizable_client_operations.html).
+
+Before this change, modifying operations before sending them required using lower-level APIs:
+
+```rust
+let input = SomeOperationInput::builder().some_value(5).build()?;
+
+let operation = {
+    let op = input.make_operation(&service_config).await?;
+    let (request, response) = op.into_request_response();
+
+    let request = request.augment(|req, _props| {
+        req.headers_mut().insert(
+            HeaderName::from_static("x-some-header"),
+            HeaderValue::from_static("some-value")
+        );
+        Result::<_, Infallible>::Ok(req)
+    })?;
+
+    Operation::from_parts(request, response)
+};
+
+let response = smithy_client.call(operation).await?;
+```
+
+Now, users may easily modify operations before sending with the `customize` method:
+
+```rust
+let response = client.some_operation()
+    .some_value(5)
+    .customize()
+    .await?
+    .mutate_request(|mut req| {
+        req.headers_mut().insert(
+            HeaderName::from_static("x-some-header"),
+            HeaderValue::from_static("some-value")
+        );
+    })
+    .send()
+    .await?;
+```
+"""
+references = ["smithy-rs#1112"]
+meta = { "breaking" = false, "tada" = true, "bug" = false }
+author = "Velfi"
+
+[[smithy-rs]]
+message = """
+Implemented customizable operations per [RFC-0017](https://awslabs.github.io/smithy-rs/design/rfcs/rfc0017_customizable_client_operations.html).
+
+Before this change, modifying operations before sending them required using lower-level APIs:
+
+```rust
+let input = SomeOperationInput::builder().some_value(5).build()?;
+
+let operation = {
+    let op = input.make_operation(&service_config).await?;
+    let (request, response) = op.into_request_response();
+
+    let request = request.augment(|req, _props| {
+        req.headers_mut().insert(
+            HeaderName::from_static("x-some-header"),
+            HeaderValue::from_static("some-value")
+        );
+        Result::<_, Infallible>::Ok(req)
+    })?;
+
+    Operation::from_parts(request, response)
+};
+
+let response = smithy_client.call(operation).await?;
+```
+
+Now, users may easily modify operations before sending with the `customize` method:
+
+```rust
+let response = client.some_operation()
+    .some_value(5)
+    .customize()
+    .await?
+    .mutate_request(|mut req| {
+        req.headers_mut().insert(
+            HeaderName::from_static("x-some-header"),
+            HeaderValue::from_static("some-value")
+        );
+    })
+    .send()
+    .await?;
+```
+"""
+references = ["smithy-rs#1112"]
+meta = { "breaking" = false, "tada" = true, "bug" = false, "target" = "client"}
+author = "Velfi"
+
 [[smithy-rs]]
 message = """
 There is a canonical and easier way to run smithy-rs on Lambda [see example].

aws/sdk/integration-tests/s3/tests/customizable-operation.rs

@@ -0,0 +1,75 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+use aws_http::user_agent::AwsUserAgent;
+use aws_sdk_s3::{Credentials, Region};
+use aws_smithy_async::rt::sleep::TokioSleep;
+use aws_smithy_client::test_connection::capture_request;
+
+use std::convert::Infallible;
+use std::sync::Arc;
+use std::time::{Duration, UNIX_EPOCH};
+
+#[tokio::test]
+async fn test_s3_ops_are_customizable() -> Result<(), aws_sdk_s3::Error> {
+    let creds = Credentials::new(
+        "ANOTREAL",
+        "notrealrnrELgWzOk3IfjzDKtFBhDby",
+        Some("notarealsessiontoken".to_string()),
+        None,
+        "test",
+    );
+    let conf = aws_sdk_s3::Config::builder()
+        .credentials_provider(creds)
+        .region(Region::new("us-east-1"))
+        .sleep_impl(Arc::new(TokioSleep::new()))
+        .build();
+    let (conn, rcvr) = capture_request(None);
+
+    let client = aws_sdk_s3::Client::from_conf_conn(conf, conn);
+
+    let op = client
+        .list_buckets()
+        .customize()
+        .await
+        .expect("list_buckets is customizable")
+        .map_operation(|mut op| {
+            op.properties_mut()
+                .insert(UNIX_EPOCH + Duration::from_secs(1624036048));
+            op.properties_mut().insert(AwsUserAgent::for_tests());
+
+            Result::<_, Infallible>::Ok(op)
+        })
+        .expect("inserting into the property bag is infallible");
+
+    // The response from the fake connection won't return the expected XML but we don't care about
+    // that error in this test
+    let _ = op
+        .send()
+        .await
+        .expect_err("this will fail due to not receiving a proper XML response.");
+
+    let expected_req = rcvr.expect_request();
+    let auth_header = expected_req
+        .headers()
+        .get("Authorization")
+        .unwrap()
+        .to_owned();
+
+    // This is a snapshot test taken from a known working test result
+    let snapshot_signature =
+        "Signature=c2028dc806248952fc533ab4b1d9f1bafcdc9b3380ed00482f9935541ae11671";
+    assert!(
+        auth_header
+            .to_str()
+            .unwrap()
+            .contains(snapshot_signature),
+        "authorization header signature did not match expected signature: got {}, expected it to contain {}",
+        auth_header.to_str().unwrap(),
+        snapshot_signature
+    );
+
+    Ok(())
+}

codegen/src/main/kotlin/software/amazon/smithy/rust/codegen/rustlang/RustReservedWords.kt

@@ -150,6 +150,7 @@ object RustReservedWords : ReservedWords {
         "abstract",
         "become",
         "box",
+        "customize",
         "do",
         "final",
         "macro",

codegen/src/main/kotlin/software/amazon/smithy/rust/codegen/smithy/InlineSmithyDependency.kt

@@ -0,0 +1,15 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.rust.codegen.smithy
+
+import software.amazon.smithy.rust.codegen.rustlang.InlineDependency
+import software.amazon.smithy.rust.codegen.rustlang.RustDependency
+import software.amazon.smithy.rust.codegen.rustlang.Visibility
+
+object InlineSmithyDependency {
+    fun forRustFile(file: String, visibility: Visibility = Visibility.PRIVATE, vararg additionalDependency: RustDependency): InlineDependency =
+        InlineDependency.forRustFile(file, "aws-smithy-inlineable", visibility, *additionalDependency)
+}

codegen/src/main/kotlin/software/amazon/smithy/rust/codegen/smithy/generators/client/FluentClientDecorator.kt

@@ -40,6 +40,8 @@ import software.amazon.smithy.rust.codegen.rustlang.stripOuter
 import software.amazon.smithy.rust.codegen.rustlang.writable
 import software.amazon.smithy.rust.codegen.smithy.ClientCodegenContext
 import software.amazon.smithy.rust.codegen.smithy.CoreCodegenContext
+import software.amazon.smithy.rust.codegen.smithy.InlineSmithyDependency
+import software.amazon.smithy.rust.codegen.smithy.RuntimeConfig
 import software.amazon.smithy.rust.codegen.smithy.RuntimeType
 import software.amazon.smithy.rust.codegen.smithy.RustCrate
 import software.amazon.smithy.rust.codegen.smithy.RustSymbolProvider
@@ -56,12 +58,21 @@ import software.amazon.smithy.rust.codegen.smithy.generators.builderSymbol
 import software.amazon.smithy.rust.codegen.smithy.generators.error.errorSymbol
 import software.amazon.smithy.rust.codegen.smithy.generators.isPaginated
 import software.amazon.smithy.rust.codegen.smithy.generators.setterName
+import software.amazon.smithy.rust.codegen.smithy.generators.smithyHttp
 import software.amazon.smithy.rust.codegen.smithy.rustType
 import software.amazon.smithy.rust.codegen.util.inputShape
 import software.amazon.smithy.rust.codegen.util.orNull
 import software.amazon.smithy.rust.codegen.util.outputShape
 import software.amazon.smithy.rust.codegen.util.toSnakeCase
 
+fun RuntimeConfig.smithyCustomizableOperation() = RuntimeType.forInlineDependency(
+    InlineSmithyDependency.forRustFile(
+        "customizable_operation", visibility = Visibility.PUBLIC,
+        CargoDependency.Http,
+        CargoDependency.SmithyHttp(this),
+    ),
+)
+
 class FluentClientDecorator : RustCodegenDecorator<ClientCodegenContext> {
     override val name: String = "FluentClient"
     override val order: Byte = 0
@@ -493,13 +504,34 @@ class FluentClientGenerator(
                     val inputType = symbolProvider.toSymbol(operation.inputShape(model))
                     val outputType = symbolProvider.toSymbol(operation.outputShape(model))
                     val errorType = operation.errorSymbol(model, symbolProvider, CodegenTarget.CLIENT)
+                    // TODO figure out how to properly get the RetryPolicy here
                     rustTemplate(
                         """
                         /// Creates a new `${operationSymbol.name}`.
                         pub(crate) fn new(handle: std::sync::Arc<super::Handle${generics.inst}>) -> Self {
                             Self { handle, inner: Default::default() }
                         }
 
+                        /// Consume this builder, creating a customizable operation that can be modified before being
+                        /// sent. The operation's inner [http::Request] can be modified as well.
+                        pub async fn customize(self) -> Result<
+                            #{CustomizableOperation}<
+                                #{Operation},
+                                impl #{ClassifyResponse}<
+                                    #{SdkSuccess}<#{OperationOutput}>,
+                                    #{SdkError}<#{OperationError}>
+                                > + Send + Sync>,
+                            #{SdkError}<#{OperationError}>
+                        > {
+                            let handle = self.handle.clone();
+                            let operation = self.inner.build().map_err(|err|#{SdkError}::ConstructionFailure(err.into()))?
+                                .make_operation(&handle.conf)
+                                .await
+                                .map_err(|err|#{SdkError}::ConstructionFailure(err.into()))?;
+
+                            Ok(#{CustomizableOperation} { handle, operation })
+                        }
+
                         /// Sends the request and returns the response.
                         ///
                         /// If an error occurs, an `SdkError` will be returned with additional details that
@@ -508,19 +540,22 @@ class FluentClientGenerator(
                         /// By default, any retryable failures will be retried twice. Retry behavior
                         /// is configurable with the [RetryConfig](aws_smithy_types::retry::RetryConfig), which can be
                         /// set when configuring the client.
-                        pub async fn send(self) -> std::result::Result<#{ok}, #{sdk_err}<#{operation_err}>>
+                        pub async fn send(self) -> std::result::Result<#{OperationOutput}, #{SdkError}<#{OperationError}>>
                         #{send_bounds:W} {
-                            let op = self.inner.build().map_err(|err|#{sdk_err}::ConstructionFailure(err.into()))?
+                            let op = self.inner.build().map_err(|err|#{SdkError}::ConstructionFailure(err.into()))?
                                 .make_operation(&self.handle.conf)
                                 .await
-                                .map_err(|err|#{sdk_err}::ConstructionFailure(err.into()))?;
+                                .map_err(|err|#{SdkError}::ConstructionFailure(err.into()))?;
                             self.handle.client.call(op).await
                         }
                         """,
-                        "ok" to outputType,
-                        "operation_err" to errorType,
-                        "sdk_err" to CargoDependency.SmithyHttp(runtimeConfig).asType()
-                            .copy(name = "result::SdkError"),
+                        "ClassifyResponse" to runtimeConfig.smithyHttp().member("retry::ClassifyResponse"),
+                        "CustomizableOperation" to runtimeConfig.smithyCustomizableOperation().member("CustomizableOperation"),
+                        "Operation" to symbolProvider.toSymbol(operation),
+                        "OperationError" to errorType,
+                        "OperationOutput" to outputType,
+                        "SdkError" to runtimeConfig.smithyHttp().member("result::SdkError"),
+                        "SdkSuccess" to runtimeConfig.smithyHttp().member("result::SdkSuccess"),
                         "send_bounds" to generics.sendBounds(inputType, outputType, errorType),
                     )
                     PaginatorGenerator.paginatorType(coreCodegenContext, generics, operation)?.also { paginatorType ->

codegen/src/main/kotlin/software/amazon/smithy/rust/codegen/smithy/generators/protocol/MakeOperationGenerator.kt

@@ -39,7 +39,7 @@ open class MakeOperationGenerator(
     private val protocol: Protocol,
     private val bodyGenerator: ProtocolPayloadGenerator,
     private val public: Boolean,
-    /** Whether or not to include default values for content-length and content-type */
+    /** Whether to include default values for content-length and content-type */
     private val includeDefaultPayloadHeaders: Boolean,
     private val functionName: String = "make_operation",
 ) {

design/src/rfcs/rfc0017_customizable_client_operations.md

@@ -1,7 +1,7 @@
 RFC: Customizable Client Operations
 ===================================
 
-> Status: Accepted
+> Status: Implemented
 
 For a summarized list of proposed changes, see the [Changes Checklist](#changes-checklist) section.
 
@@ -190,9 +190,9 @@ that would conflict with the new function, so adding it would not be a breaking
 Changes Checklist
 -----------------
 
-- [ ] Create `CustomizableOperation` as an inlinable, and code generate it into `client` so that it has access to `Handle`
-- [ ] Code generate the `customize` method on fluent builders
-- [ ] Update the `RustReservedWords` class to include `customize`
-- [ ] Add ability to mutate the HTTP request on `Operation`
+- [x] Create `CustomizableOperation` as an inlinable, and code generate it into `client` so that it has access to `Handle`
+- [x] Code generate the `customize` method on fluent builders
+- [x] Update the `RustReservedWords` class to include `customize`
+- [x] Add ability to mutate the HTTP request on `Operation`
 - [ ] Add examples for both approaches
 - [ ] Comment on older discussions asking about how to do this with this improved approach

rust-runtime/Cargo.toml

@@ -8,6 +8,7 @@ members = [
     "aws-smithy-eventstream",
     "aws-smithy-http",
     "aws-smithy-http-tower",
+    "aws-smithy-inlineable",
     "aws-smithy-json",
     "aws-smithy-protocol-test",
     "aws-smithy-query",

rust-runtime/aws-smithy-http/src/operation.rs

@@ -188,6 +188,16 @@ impl<H, R> Operation<H, R> {
         self.request.properties()
     }
 
+    /// Gives mutable access to the underlying HTTP request.
+    pub fn request_mut(&mut self) -> &mut http::Request<SdkBody> {
+        self.request.http_mut()
+    }
+
+    /// Gives readonly access to the underlying HTTP request.
+    pub fn request(&self) -> &http::Request<SdkBody> {
+        self.request.http()
+    }
+
     pub fn with_metadata(mut self, metadata: Metadata) -> Self {
         self.parts.metadata = Some(metadata);
         self

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

@@ -0,0 +1,25 @@
+[package]
+name = "aws-smithy-inlineable"
+version = "0.0.0-smithy-rs-head"
+authors = ["AWS Rust SDK Team <aws-sdk-rust@amazon.com>", "Zelda Hessler <zhessler@amazon.com>"]
+description = """
+The modules of this crate are intended to be inlined directly into smithy clients as needed. The dependencies here
+are to allow this crate to be compilable and testable in isolation, no client code actually takes these dependencies.
+"""
+edition = "2021"
+license = "Apache-2.0"
+publish = false
+repository = "https://github.com/awslabs/smithy-rs"
+
+[dependencies]
+aws-smithy-client = { path = "../aws-smithy-client" }
+aws-smithy-http = { path = "../aws-smithy-http" }
+aws-smithy-types = { path = "../aws-smithy-types" }
+http = "0.2.8"
+tower-service = "0.3.2"
+
+[package.metadata.docs.rs]
+all-features = true
+targets = ["x86_64-unknown-linux-gnu"]
+rustdoc-args = ["--cfg", "docsrs"]
+# End of docs.rs metadata