promote aws-smithy-mocks out of experimental (#4098)

## Motivation and Context
* #4074
* #3926

## Description
* Rename `aws-smithy-mocks-experimental` to `aws-smithy-mocks` and reset
version to `0.1.0`
* Fix [#3926](#3926) by
having `mock_client!` macro always set an HTTP client. By default it
returns a dummy I'm a teapot response to aid in debugging and be easy to
tell where that response is coming from. Also when a rule sets an HTTP
response it is not set as an extension in the request and returned by
the HTTP client. This allows for more thorough and accurate integration
testing as the client/runtime will see the response coming from the HTTP
client instead of being ignored and then replaced as it was before
* Added a new sequence builder API for allowing a rule to generate more
than one response. This allows for testing retries for example.
* Also deleted a hyper 1.x test that is no longer needed and was ignored
anyway

## Questions

* In this PR I've simply renamed/moved `aws-smithy-mocks-experimental`
to `aws-smithy-mocks`. Do we want or need to publish one last version of
`aws-smithy-mocks-experimental` with a deprecated API that instructs
users it has moved? Alternatively we could publish an [informational
advisory notice](https://github.com/RustSec/advisory-db#advisory-format)
about the rename. We don't currently promote the crate anywhere and the
dev guide will get updated so I'm on the fence for what we want to do.

## Testing
* Added new unit tests to exercise the API without needing an SDK client
by leveraging the manual `Operation` APIs.
* Added new integration tests for S3 to cover the macros and test the
library e2e.

## Checklist
<!--- If a checkbox below is not applicable, then please DELETE it
rather than leaving it unchecked -->
- [x] For changes to the smithy-rs codegen or runtime crates, I have
created a changelog entry Markdown file in the `.changelog` directory,
specifying "client," "server," or both in the `applies_to` key.
- [x] For changes to the AWS SDK, generated SDK code, or SDK runtime
crates, I have created a changelog entry Markdown file in the
`.changelog` directory, specifying "aws-sdk-rust" in the `applies_to`
key.

----

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

Author: aajtodd

.changelog/1745330307.md

@@ -0,0 +1,62 @@
+---
+applies_to:
+- client
+- aws-sdk-rust
+authors:
+- aajtodd
+references:
+  - smithy-rs#4074
+  - smithy-rs#3926
+breaking: false
+new_feature: true
+bug_fix: true
+---
+Promote `aws-smithy-mocks-experimental` to `aws-smithy-mocks`. This crate is now a recommended tool for testing
+generated SDK clients. This release includes several fixes as well as a new sequence builder API that can be
+used to test more complex scenarios such as retries.
+
+```rust
+use aws_sdk_s3::operation::get_object::GetObjectOutput;
+use aws_sdk_s3::config::retry::RetryConfig;
+use aws_smithy_types::byte_stream::ByteStream;
+use aws_smithy_mocks::{mock, mock_client, RuleMode};
+
+#[tokio::test]
+async fn test_retry_behavior() {
+    // Create a rule that returns 503 twice, then succeeds
+    let retry_rule = mock!(aws_sdk_s3::Client::get_object)
+        .sequence()
+        .http_status(503, None)
+        .times(2)                                            // Return 503 HTTP status twice
+        .output(|| GetObjectOutput::builder()                // Finally return a successful output
+            .body(ByteStream::from_static(b"success"))
+            .build())
+        .build();
+
+    // Create a mocked client with the rule
+    let s3 = mock_client!(
+        aws_sdk_s3,
+        RuleMode::Sequential,
+        [&retry_rule],
+        |client_builder| {
+            client_builder.retry_config(RetryConfig::standard().with_max_attempts(3))
+        }
+    );
+
+    // This should succeed after two retries
+    let result = s3
+        .get_object()
+        .bucket("test-bucket")
+        .key("test-key")
+        .send()
+        .await
+        .expect("success after retries");
+
+    // Verify the response
+    let data = result.body.collect().await.expect("successful read").to_vec();
+    assert_eq!(data, b"success");
+
+    // Verify all responses were used
+    assert_eq!(retry_rule.num_calls(), 3);
+}
+```

aws/rust-runtime/Cargo.lock

@@ -29,6 +29,7 @@ import software.amazon.smithy.rust.codegen.core.rustlang.CargoDependency.Compani
 import software.amazon.smithy.rust.codegen.core.rustlang.CargoDependency.Companion.TracingSubscriber
 import software.amazon.smithy.rust.codegen.core.rustlang.CargoDependency.Companion.TracingTest
 import software.amazon.smithy.rust.codegen.core.rustlang.CargoDependency.Companion.smithyHttpClient
+import software.amazon.smithy.rust.codegen.core.rustlang.CargoDependency.Companion.smithyMocks
 import software.amazon.smithy.rust.codegen.core.rustlang.CargoDependency.Companion.smithyProtocolTestHelpers
 import software.amazon.smithy.rust.codegen.core.rustlang.CargoDependency.Companion.smithyRuntime
 import software.amazon.smithy.rust.codegen.core.rustlang.CargoDependency.Companion.smithyRuntimeApiTestUtil
@@ -170,5 +171,6 @@ class S3TestDependencies(private val runtimeConfig: RuntimeConfig) : LibRsCustom
             addDependency(TempFile)
             addDependency(TracingAppender)
             addDependency(TracingTest)
+            addDependency(smithyMocks(runtimeConfig))
         }
 }

aws/rust-runtime/aws-config/Cargo.lock

@@ -27,6 +27,7 @@ aws-smithy-runtime = { path = "../../build/aws-sdk/sdk/aws-smithy-runtime", feat
 aws-smithy-runtime-api = { path = "../../build/aws-sdk/sdk/aws-smithy-runtime-api", features = ["test-util", "http-1x"] }
 aws-smithy-types = { path = "../../build/aws-sdk/sdk/aws-smithy-types" }
 aws-smithy-http-client = { path = "../../build/aws-sdk/sdk/aws-smithy-http-client", features = ["default-client", "rustls-ring", "test-util", "wire-mock"] }
+aws-smithy-mocks = { path = "../../build/aws-sdk/sdk/aws-smithy-mocks" }
 aws-types = { path = "../../build/aws-sdk/sdk/aws-types" }
 bytes = "1"
 bytes-utils = "0.1.2"

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

@@ -0,0 +1,180 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+//! Integration tests for `aws-smithy-mocks`. These tests are not necessarily specific to S3 but
+//! we need to test the macros against an actual SDK.
+
+use aws_sdk_s3::config::retry::RetryConfig;
+use aws_sdk_s3::operation::get_object::{GetObjectError, GetObjectOutput};
+use aws_sdk_s3::operation::list_buckets::ListBucketsError;
+use aws_smithy_mocks::{mock, mock_client, RuleMode};
+use aws_smithy_runtime_api::client::orchestrator::HttpResponse;
+use aws_smithy_runtime_api::http::StatusCode;
+use aws_smithy_types::body::SdkBody;
+use aws_smithy_types::byte_stream::ByteStream;
+use aws_smithy_types::error::metadata::ProvideErrorMetadata;
+use aws_smithy_types::error::ErrorMetadata;
+
+const S3_NO_SUCH_KEY: &str = r#"<?xml version="1.0" encoding="UTF-8"?>
+<Error>
+  <Code>NoSuchKey</Code>
+  <Message>The resource you requested does not exist</Message>
+  <Resource>/mybucket/myfoto.jpg</Resource>
+  <RequestId>4442587FB7D0A2F9</RequestId>
+</Error>"#;
+
+#[tokio::test]
+async fn test_mock_client() {
+    let s3_404 = mock!(aws_sdk_s3::Client::get_object)
+        .match_requests(|inp| {
+            inp.bucket() == Some("test-bucket") && inp.key() != Some("correct-key")
+        })
+        .then_http_response(|| {
+            HttpResponse::new(
+                StatusCode::try_from(400).unwrap(),
+                SdkBody::from(S3_NO_SUCH_KEY),
+            )
+        });
+
+    let s3_real_object = mock!(aws_sdk_s3::Client::get_object)
+        .match_requests(|inp| {
+            inp.bucket() == Some("test-bucket") && inp.key() == Some("correct-key")
+        })
+        .then_output(|| {
+            GetObjectOutput::builder()
+                .body(ByteStream::from_static(b"test-test-test"))
+                .build()
+        });
+
+    let modeled_error = mock!(aws_sdk_s3::Client::list_buckets).then_error(|| {
+        ListBucketsError::generic(ErrorMetadata::builder().code("InvalidAccessKey").build())
+    });
+
+    let s3 = mock_client!(aws_sdk_s3, &[&s3_404, &s3_real_object, &modeled_error]);
+
+    let error = s3
+        .get_object()
+        .bucket("test-bucket")
+        .key("foo")
+        .send()
+        .await
+        .expect_err("404");
+
+    assert!(matches!(
+        error.into_service_error(),
+        GetObjectError::NoSuchKey(_)
+    ));
+
+    assert_eq!(s3_404.num_calls(), 1);
+
+    let data = s3
+        .get_object()
+        .bucket("test-bucket")
+        .key("correct-key")
+        .send()
+        .await
+        .expect("success response")
+        .body
+        .collect()
+        .await
+        .expect("successful read")
+        .to_vec();
+
+    assert_eq!(data, b"test-test-test");
+    assert_eq!(s3_real_object.num_calls(), 1);
+
+    let err = s3.list_buckets().send().await.expect_err("bad access key");
+    assert_eq!(err.code(), Some("InvalidAccessKey"));
+}
+
+#[tokio::test]
+async fn test_mock_client_sequence() {
+    let rule = mock!(aws_sdk_s3::Client::get_object)
+        .sequence()
+        .http_status(400, Some(S3_NO_SUCH_KEY.to_string()))
+        .output(|| {
+            GetObjectOutput::builder()
+                .body(ByteStream::from_static(b"test-test-test"))
+                .build()
+        })
+        .build();
+
+    // test client builder override
+    let s3 = mock_client!(
+        aws_sdk_s3,
+        RuleMode::Sequential,
+        [&rule],
+        |client_builder| { client_builder.endpoint_url("http://localhost:9000") }
+    );
+
+    let error = s3
+        .get_object()
+        .bucket("test-bucket")
+        .key("foo")
+        .send()
+        .await
+        .expect_err("404");
+
+    assert!(matches!(
+        error.into_service_error(),
+        GetObjectError::NoSuchKey(_)
+    ));
+    assert_eq!(1, rule.num_calls());
+    let data = s3
+        .get_object()
+        .bucket("test-bucket")
+        .key("correct-key")
+        .send()
+        .await
+        .expect("success response")
+        .body
+        .collect()
+        .await
+        .expect("successful read")
+        .to_vec();
+
+    assert_eq!(data, b"test-test-test");
+    assert_eq!(2, rule.num_calls());
+}
+
+#[tokio::test]
+async fn test_mock_client_retries() {
+    let rule = mock!(aws_sdk_s3::Client::get_object)
+        .sequence()
+        .http_status(503, None)
+        .times(2)
+        .output(|| {
+            GetObjectOutput::builder()
+                .body(ByteStream::from_static(b"test-test-test"))
+                .build()
+        })
+        .build();
+
+    // test client builder override
+    let s3 = mock_client!(
+        aws_sdk_s3,
+        RuleMode::Sequential,
+        [&rule],
+        |client_builder| {
+            client_builder.retry_config(RetryConfig::standard().with_max_attempts(3))
+        }
+    );
+
+    let data = s3
+        .get_object()
+        .bucket("test-bucket")
+        .key("correct-key")
+        .send()
+        .await
+        .expect("success response")
+        .body
+        .collect()
+        .await
+        .expect("successful read")
+        .to_vec();
+
+    assert_eq!(data, b"test-test-test");
+    assert_eq!(3, rule.num_calls());
+}

aws/sdk/Cargo.lock

@@ -70,6 +70,7 @@ object CrateSet {
             "aws-smithy-http-auth",
             "aws-smithy-http-tower",
             "aws-smithy-json",
+            "aws-smithy-mocks",
             "aws-smithy-mocks-experimental",
             "aws-smithy-observability",
             "aws-smithy-observability-otel",

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

@@ -394,6 +394,9 @@ data class CargoDependency(
 
         fun smithyXml(runtimeConfig: RuntimeConfig) = runtimeConfig.smithyRuntimeCrate("smithy-xml")
 
+        fun smithyMocks(runtimeConfig: RuntimeConfig) =
+            runtimeConfig.smithyRuntimeCrate("smithy-mocks", scope = DependencyScope.Dev)
+
         // behind feature-gate
         val Serde =
             CargoDependency("serde", CratesIo("1.0"), features = setOf("derive"), scope = DependencyScope.CfgUnstable)