Move examples to root, refactor to workspace, and refactor integration tests (#2481)

* Move examples

* Update documentation

* Add to CI

* Fix CI

* Cleanup

* Fix clippy lints

* Fix documentation

* Bump example dependencies

* Cleanup

* Update documentation

---------

Co-authored-by: Matteo Bigoi <1781140+crisidev@users.noreply.github.com>

Author: hlbarber

README.md

@@ -38,6 +38,7 @@ Project Layout
 * [`design`](design): Design documentation. See the [design/README.md](design/README.md) for details about building / viewing.
 * `codegen-server`: Whitelabel Smithy server code generation
 * `codegen-server-test`: Smithy protocol test generation & integration tests for Smithy server whitelabel code
+* `examples`: A collection of server implementation examples
 
 Testing
 -------

design/src/server/anatomy.md

@@ -648,7 +648,7 @@ stateDiagram-v2
     Op1 --> Op2 : Plugin#colon;#colon;map
 ```
 
-An example `Plugin` implementation can be found in [aws-smithy-http-server/examples/pokemon-service/src/plugin.rs](https://github.com/awslabs/smithy-rs/blob/main/rust-runtime/aws-smithy-http-server/examples/pokemon-service/src/plugin.rs).
+An example `Plugin` implementation can be found in [/examples/pokemon-service/src/plugin.rs](https://github.com/awslabs/smithy-rs/blob/main/examples/pokemon-service/src/plugin.rs).
 
 The service builder API requires plugins to be specified upfront - they must be passed as an argument to `builder_with_plugins` and cannot be modified afterwards.
 This constraint is in place to ensure that all handlers are upgraded using the same set of plugins.

design/src/server/instrumentation.md

@@ -69,7 +69,7 @@ let app = PokemonService::builder_with_plugins(plugins)
 
 ### Example
 
-The Pokémon service example, located at `rust-runtime/aws-smithy-http-server/examples/pokemon-service`, sets up a `tracing` `Subscriber` as follows:
+The Pokémon service example, located at `/examples/pokemon-service`, sets up a `tracing` `Subscriber` as follows:
 
 ```rust
 /// Setup `tracing::subscriber` to read the log level from RUST_LOG environment variable.

rust-runtime/aws-smithy-http-server/examples/.gitignore renamed to examples/.gitignore

@@ -1,2 +1,3 @@
 pokemon-service-client/
 pokemon-service-server-sdk/
+Cargo.lock

rust-runtime/aws-smithy-http-server/examples/BENCHMARKS.md renamed to examples/BENCHMARKS.md

@@ -5,11 +5,12 @@ using [wrk](https://github.com/wg/wrk).
 
 <!-- vim-markdown-toc Marked -->
 
-* [2022-03-04](#2022-03-04)
-    * [c6i.8xlarge](#c6i.8xlarge)
-        * [Full result](#full-result)
-    * [c6g.8xlarge](#c6g.8xlarge)
-        * [Full result](#full-result)
+- [Smithy Rust Server SDK benchmarks](#smithy-rust-server-sdk-benchmarks)
+  - [2022-03-04](#2022-03-04)
+    - [c6i.8xlarge](#c6i8xlarge)
+      - [Full result](#full-result)
+    - [c6g.8xlarge](#c6g8xlarge)
+      - [Full result](#full-result-1)
 
 <!-- vim-markdown-toc -->
 
@@ -20,19 +21,19 @@ returning an empty output and can be used to stress test the framework overhead.
 
 ### c6i.8xlarge
 
-* 32 cores Intel(R) Xeon(R) Platinum 8375C CPU @ 2.90GHz
-* 64 Gb memory
-* Benchmark:
-    - Duration: 10 minutes
-    - Connections: 1024
-    - Threads: 16
-* Result:
-    - Request/sec: 1_608_742
-    * RSS[^1] memory: 72200 bytes
+- 32 cores Intel(R) Xeon(R) Platinum 8375C CPU @ 2.90GHz
+- 64 Gb memory
+- Benchmark:
+  - Duration: 10 minutes
+  - Connections: 1024
+  - Threads: 16
+- Result:
+  - Request/sec: 1_608_742
+  - RSS[^1] memory: 72200 bytes
 
 #### Full result
 
-```
+```text
 ❯❯❯ wrk -t16 -c1024 -d10m --latency http://localhost:13734/empty-operation
 Running 10m test @ http://localhost:13734/empty-operation
   16 threads and 1024 connections
@@ -52,20 +53,20 @@ Transfer/sec:    167.23MB
 
 ### c6g.8xlarge
 
-* 32 cores Amazon Graviton 2 @ 2.50GHz
-* 64 Gb memory
-* Benchmark:
-    - Duration: 10 minutes
-    - Connections: 1024
-    - Threads: 16
-* Result:
-    - Request/sec: 1_379_942
-    - RSS[^1] memory: 70264 bytes
+- 32 cores Amazon Graviton 2 @ 2.50GHz
+- 64 Gb memory
+- Benchmark:
+  - Duration: 10 minutes
+  - Connections: 1024
+  - Threads: 16
+- Result:
+  - Request/sec: 1_379_942
+  - RSS[^1] memory: 70264 bytes
 
 
 #### Full result
 
-```
+```text
 ❯❯❯ wrk -t16 -c1024 -d10m --latency http://localhost:13734/empty-operation
 Running 10m test @ http://localhost:13734/empty-operation
   16 threads and 1024 connections

rust-runtime/aws-smithy-http-server/examples/Cargo.toml renamed to examples/Cargo.toml

@@ -1,9 +1,12 @@
 # Without this configuration, the workspace will be read from `rust-runtime`, causing the build to fail.
 [workspace]
 members = [
+    "pokemon-service-common",
     "pokemon-service",
+    "pokemon-service-tls",
+    "pokemon-service-lambda",
     "pokemon-service-server-sdk",
-    "pokemon-service-client",
+    "pokemon-service-client"
 ]
 
 [profile.release]

rust-runtime/aws-smithy-http-server/examples/Makefile renamed to examples/Makefile

@@ -0,0 +1,49 @@
+# Smithy Rust Server SDK examples
+
+This folder contains an example services showcasing the service framework capabilities and to run benchmarks.
+
+- `/pokemon-service`, a HTTP server implementation demonstrating [middleware](https://awslabs.github.io/smithy-rs/design/server/middleware.html)
+and [extractors](https://awslabs.github.io/smithy-rs/design/server/from_parts.html).
+- `/pokemon-service-tls`, a minimal HTTPS server implementation.
+- `/pokemon-service-lambda`, a minimal Lambda deployment.
+
+The `/{binary}/tests` folders are integration tests involving the generated clients.
+
+## Build
+
+Since this example requires both the server and client SDK to be code-generated
+from their [model](/codegen-server-test/model/pokemon.smithy), a Makefile is
+provided to build and run the service. Just run `make` to prepare the first
+build.
+
+Once the example has been built successfully the first time, idiomatic `cargo`
+can be used directly.
+
+`make distclean` can be used for a complete cleanup of all artefacts.
+
+## Run
+
+To run a binary use
+
+```bash
+cargo run -p $BINARY
+```
+
+CLI arguments can be passed to the servers, use
+
+```bash
+cargo run -p $BINARY -- --help
+```
+
+for more information.
+
+## Test
+
+`cargo test` can be used to spawn a service and run some simple integration
+tests against it. Use `-p $BINARY` to filter by package.
+
+More info can be found in the `tests` folder of each package.
+
+## Benchmarks
+
+Please see [BENCHMARKS.md](/examples/BENCHMARKS.md).

examples/README.md

@@ -0,0 +1,24 @@
+[package]
+name = "pokemon-service-common"
+version = "0.1.0"
+edition = "2021"
+publish = false
+authors = ["Smithy-rs Server Team <smithy-rs-server@amazon.com>"]
+description = "A smithy Rust service to retrieve information about Pokémon."
+
+[dependencies]
+async-stream = "0.3"
+http = "0.2.9"
+rand = "0.8"
+tracing = "0.1"
+tracing-subscriber = { version = "0.3.16", features = ["env-filter", "json"] }
+tokio = { version = "1", default-features = false, features = ["time"] }
+
+# Local paths
+aws-smithy-http = { path = "../../rust-runtime/aws-smithy-http" }
+aws-smithy-http-server = { path = "../../rust-runtime/aws-smithy-http-server" }
+pokemon-service-client = { path = "../pokemon-service-client" }
+pokemon-service-server-sdk = { path = "../pokemon-service-server-sdk" }
+
+[dev-dependencies]
+tower = "0.4"

examples/pokemon-service-common/Cargo.toml

@@ -10,17 +10,19 @@
 use std::{
     collections::HashMap,
     convert::TryInto,
+    process::Child,
     sync::{atomic::AtomicUsize, Arc},
 };
 
 use async_stream::stream;
+use aws_smithy_http::operation::Request;
 use aws_smithy_http_server::Extension;
-use pokemon_service_server_sdk::{error, input, model, model::CapturingPayload, output, types::Blob};
+use pokemon_service_server_sdk::{
+    error, input, model, model::CapturingPayload, output, types::Blob,
+};
 use rand::Rng;
 use tracing_subscriber::{prelude::*, EnvFilter};
 
-pub mod plugin;
-
 const PIKACHU_ENGLISH_FLAVOR_TEXT: &str =
     "When several of these Pokémon gather, their electricity could build and cause lightning storms.";
 const PIKACHU_SPANISH_FLAVOR_TEXT: &str =
@@ -30,13 +32,37 @@ const PIKACHU_ITALIAN_FLAVOR_TEXT: &str =
 const PIKACHU_JAPANESE_FLAVOR_TEXT: &str =
     "ほっぺたの りょうがわに ちいさい でんきぶくろを もつ。ピンチのときに ほうでんする。";
 
+/// Rewrites the base URL of a request
+pub fn rewrite_base_url(base_url: String) -> impl Fn(Request) -> Request + Clone {
+    move |mut req| {
+        let http_req = req.http_mut();
+        let uri = format!("{base_url}{}", http_req.uri().path());
+        *http_req.uri_mut() = uri.parse().unwrap();
+        req
+    }
+}
+
+/// Kills [`Child`] process when dropped.
+#[derive(Debug)]
+#[must_use]
+pub struct ChildDrop(pub Child);
+
+impl Drop for ChildDrop {
+    fn drop(&mut self) {
+        self.0.kill().expect("failed to kill process")
+    }
+}
+
 /// Setup `tracing::subscriber` to read the log level from RUST_LOG environment variable.
 pub fn setup_tracing() {
     let format = tracing_subscriber::fmt::layer().json();
     let filter = EnvFilter::try_from_default_env()
         .or_else(|_| EnvFilter::try_new("info"))
         .unwrap();
-    tracing_subscriber::registry().with(format).with(filter).init();
+    tracing_subscriber::registry()
+        .with(format)
+        .with(filter)
+        .init();
 }
 
 /// Structure holding the translations for a Pokémon description.
@@ -134,7 +160,10 @@ pub async fn get_pokemon_species(
     input: input::GetPokemonSpeciesInput,
     state: Extension<Arc<State>>,
 ) -> Result<output::GetPokemonSpeciesOutput, error::GetPokemonSpeciesError> {
-    state.0.call_count.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+    state
+        .0
+        .call_count
+        .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
     // We only support retrieving information about Pikachu.
     let pokemon = state.0.pokemons_translations.get(&input.name);
     match pokemon.as_ref() {
@@ -215,7 +244,9 @@ pub async fn capture_pokemon(
 ) -> Result<output::CapturePokemonOutput, error::CapturePokemonError> {
     if input.region != "Kanto" {
         return Err(error::CapturePokemonError::UnsupportedRegionError(
-            error::UnsupportedRegionError { region: input.region },
+            error::UnsupportedRegionError {
+                region: input.region,
+            },
         ));
     }
     let output_stream = stream! {
@@ -307,7 +338,10 @@ mod tests {
             .find(|flavor_text| flavor_text.language == model::Language::Spanish)
             .unwrap();
 
-        assert_eq!(PIKACHU_SPANISH_FLAVOR_TEXT, actual_spanish_flavor_text.flavor_text());
+        assert_eq!(
+            PIKACHU_SPANISH_FLAVOR_TEXT,
+            actual_spanish_flavor_text.flavor_text()
+        );
 
         let input = input::GetServerStatisticsInput {};
         let stats = get_server_statistics(input, Extension(state.clone())).await;