diff --git a/design/src/SUMMARY.md b/design/src/SUMMARY.md index 4e4fd2f7eb..f104234efc 100644 --- a/design/src/SUMMARY.md +++ b/design/src/SUMMARY.md @@ -1,4 +1,5 @@ # Summary + - [Design Overview](./overview.md) - [Tenets](./tenets.md) - [Design FAQ](./faq.md) @@ -7,11 +8,16 @@ - [HTTP Middleware](transport/middleware.md) - [Smithy](./smithy/overview.md) - - [Simple Shapes](./smithy/simple_shapes.md) - - [Recursive Shapes](./smithy/recursive_shapes.md) - - [Aggregate Shapes](./smithy/aggregate_shapes.md) - - [Endpoint Resolution](smithy/endpoint.md) - - [Backwards Compatibility](smithy/backwards-compat.md) + - [Simple Shapes](./smithy/simple_shapes.md) + - [Recursive Shapes](./smithy/recursive_shapes.md) + - [Aggregate Shapes](./smithy/aggregate_shapes.md) + - [Endpoint Resolution](smithy/endpoint.md) + - [Backwards Compatibility](smithy/backwards-compat.md) + +- [Server](./server/overview.md) + - [Generating Common Service Code](./server/code_generation.md) + - [Generating the Pokémon Service](./server/pokemon_service.md) + - [Instrumentation](./server/instrumentation.md) - [RFCs](./rfcs/overview.md) - [RFC-0001: Sharing configuration between multiple clients](./rfcs/rfc0001_shared_config.md) diff --git a/design/src/docs/code_generation.md b/design/src/server/code_generation.md similarity index 99% rename from design/src/docs/code_generation.md rename to design/src/server/code_generation.md index f0a8bd3793..20da6c46c6 100644 --- a/design/src/docs/code_generation.md +++ b/design/src/server/code_generation.md @@ -1,9 +1,9 @@ -## Generating common service code +# Generating Common Service Code How a service is constructed and how to plug in new business logic is described in [Pokémon Service][1]. This document introduces the project and how code is being generated. It is written for developers who want to start contributing to `smithy-rs`. -### Folder structure +## Folder structure The project is divided in: @@ -15,7 +15,7 @@ which contains common functions used by other crates, [copied into][2] the sourc `/rust-runtime` crates ("runtime crates") are added to a crate's dependency only when used. If a model uses event streams, it will depend on [`aws-smithy-eventstream`][3]. -### Generating code +## Generating code `smithy-rs`'s entry points are Smithy code-generation plugins, and is not a command. One entry point is in [RustCodegenPlugin::execute][4] and inherits from `SmithyBuildPlugin` in [smithy-build][5]. Code generation is in Kotlin and shared common, non-Rust specific code with the [`smithy` Java repository][6]. They plug into the [Smithy gradle][7] plugin, which is a gradle plugin. diff --git a/design/src/docs/instrumentation.md b/design/src/server/instrumentation.md similarity index 100% rename from design/src/docs/instrumentation.md rename to design/src/server/instrumentation.md diff --git a/design/src/server/overview.md b/design/src/server/overview.md new file mode 100644 index 0000000000..2b023112c5 --- /dev/null +++ b/design/src/server/overview.md @@ -0,0 +1,7 @@ +# Smithy Server + +Smithy Rust provides the ability to generate a server whose operations are provided by the customer. + +- [Generating Common Service Code](./code_generation.md) +- [Generating the Pokémon Service](./pokemon_service.md) +- [Instrumentation](./instrumentation.md) diff --git a/design/src/docs/pokemon_service.md b/design/src/server/pokemon_service.md similarity index 89% rename from design/src/docs/pokemon_service.md rename to design/src/server/pokemon_service.md index d1209696b6..6842bcf5c4 100644 --- a/design/src/docs/pokemon_service.md +++ b/design/src/server/pokemon_service.md @@ -1,4 +1,4 @@ -## Code generating the Pokémon Service +# Generating the Pokémon Service This is an overview of client and server of the Pokémon service. It introduces: @@ -10,7 +10,7 @@ All the code shown and linked to is from the repository at this commit: [db48039 The Smithy model used to generate the code snippets is: [Pokémon][2] -### Building the service +## Building the service The entry point of a service is [main.rs][3] @@ -59,37 +59,37 @@ let app: Router = OperationRegistryBuilder::default() Each of these operations is a function that can take any of these signatures. -1. If the operation is not fallible and does not share any state: +1. If the operation is not fallible and does not share any state: -```rust -pub async fn health_check_operation(_input: input::HealthCheckOperationInput) -> output::HealthCheckOperationOutput {...} -``` + ```rust + pub async fn health_check_operation(_input: input::HealthCheckOperationInput) -> output::HealthCheckOperationOutput {...} + ``` -2. If the operation is fallible and does not share any state: +2. If the operation is fallible and does not share any state: -```rust -pub async fn capture_pokemon( - mut input: input::CapturePokemonOperationInput, -) -> Result {...} -``` + ```rust + pub async fn capture_pokemon( + mut input: input::CapturePokemonOperationInput, + ) -> Result {...} + ``` -3. If the operation is not fallible and shares some state: +3. If the operation is not fallible and shares some state: -```rust -pub async fn get_server_statistics( - _input: input::GetServerStatisticsInput, - state: Extension>, -) -> output::GetServerStatisticsOutput {...} -``` + ```rust + pub async fn get_server_statistics( + _input: input::GetServerStatisticsInput, + state: Extension>, + ) -> output::GetServerStatisticsOutput {...} + ``` -4. If the operation is fallible and shares some state: +4. If the operation is fallible and shares some state: -```rust -pub async fn get_storage( - input: input::GetStorageInput, - _state: Extension>, -) -> Result {...} -``` + ```rust + pub async fn get_storage( + input: input::GetStorageInput, + _state: Extension>, + ) -> Result {...} + ``` All of these are operations which implementors define; they are the business logic of the application. The rest is code generated.