Expand example documentation (#2570)

# Smithy Rust Server SDK examples

This folder contains an example services showcasing the service framework capabilities and to run benchmarks.

This folder contains some example services showcasing Smithy Rust Server SDK, 

also known as the Rust 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.

Three server implementations are available:

The `/{binary}/tests` folders are integration tests involving the generated clients.

- `/pokemon-service`, a HTTP server demonstrating [middleware] and [extractors].

- `/pokemon-service-tls`, a HTTPS server. This server can do 

   its own TLS negotiation, rather than relying on a load balancer. 

- `/pokemon-service-lambda`, a server that can be deployed onto AWS Lambda.

## Build

These servers, and their clients, are generated using smithy-rs. You're invited

to benchmark the performance of these servers to see whether smithy-rs might be

a suitable choice for implementing your web service.

Since this example requires both the server and client SDK to be code-generated

[middleware]: https://awslabs.github.io/smithy-rs/design/server/middleware.html

[extractors]: https://awslabs.github.io/smithy-rs/design/server/from_parts.html

## Pre-requisites

You will need install Java 11 to run the smithy-rs code generator and an

installation of Rust, including `cargo`, to compile the generated code.

(Optional) The [Cargo Lambda](https://cargo-lambda.info/) sub-command for 

`cargo` is required to support the AWS Lambda integration.

## Building

Since these examples require 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.

### Make targets:

- `codegen`: generates the Pokémon service crates (default)

- `build`: compiles the generated client and server

- `clean`: deletes build artifacts

- `clippy`: lints the code

- `distclean`: delete generated code and build artifacts 

- `doc-open`: builds and opens the rustdoc documentation

- `lambda_invoke`: invokes a running server 

- `lambda_watch`: runs the service on an emulated AWS Lambda environment

- `run`: runs the Pokémon service

- `test`: runs integration and unit tests

## Run

## Running services

To run a binary use

To run one of the three server implementations locally, provide the appropriate 

service name to the `--bin` flag:

```bash

cargo run -p $BINARY

cargo run --bin pokemon-service[(-lambda|-tls)]

```

CLI arguments can be passed to the servers, use

CLI arguments can be passed to the server binaries by adding them after `--`. 

For example, to see a service's help information, use the following:

```bash

cargo run -p $BINARY -- --help

cargo run --bin <service> -- --help

```

for more information.

## Testing

## Test

The `/pokemon-test*/tests` folders provide integration tests involving the 

generated clients.

`cargo test` can be used to spawn a service and run some simple integration

tests against it. Use `-p $BINARY` to filter by package.

They can be invoked with `cargo test`. This will spawn each service in turn 

and run some integration tests against it. Use `-p <package>` to filter by 

package.

More info can be found in the `tests` folder of each package.

## Benchmarks

Please see [BENCHMARKS.md](/examples/BENCHMARKS.md).

## Benchmarking

Servers running locally (see "Running services") can be benchmarked with any 

load testing tool, such as Artillery or `wrk`.

Please see [BENCHMARKS.md](/examples/BENCHMARKS.md) for benchmarking results 

produced by the smithy-rs team.