mirror of https://github.com/smithy-lang/smithy-rs
c63e792454
RPC v2 CBOR is a new protocol that ~is being added~ has [recently been
added](https://smithy.io/2.0/additional-specs/protocols/smithy-rpc-v2.html)
to the Smithy
specification.
_(I'll add more details here as the patchset evolves)_
Credit goes to @jjant for initial implementation of the router, which I
built on top of from his
[`jjant/smithy-rpc-v2-exploration`](https://github.com/awslabs/smithy-rs/tree/jjant/smithy-rpc-v2-exploration)
branch.
Tracking issue: https://github.com/smithy-lang/smithy-rs/issues/3573.
## Caveats
`TODO`s are currently exhaustively sprinkled throughout the patch
documenting what remains to be done. Most of these need to be addressed
before this can be merged in; some can be punted on to not make this PR
bigger.
However, I'd like to call out the major caveats and blockers here. I'll
keep updating this list as the patchset evolves.
- [x] RPC v2 has still not been added to the Smithy specification. It is
currently being worked on over in the
[`smithy-rpc-v2`](https://github.com/awslabs/smithy/tree/smithy-rpc-v2)
branch. The following are prerrequisites for this PR to be merged;
**until they are done CI on this PR will fail**:
- [x] Smithy merges in RPC v2 support.
- [x] Smithy releases a new version incorporating RPC v2 support.
- Released in [Smithy
v1.47](https://github.com/smithy-lang/smithy/releases/tag/1.47.0)
- [x] smithy-rs updates to the new version.
- Updated in https://github.com/smithy-lang/smithy-rs/pull/3552
- [x] ~Protocol tests for the protocol do not currently exist in Smithy.
Until those get written~, this PR resorts to Rust unit tests and
integration tests that use `serde` to round-trip messages and compare
`serde`'s encoders and decoders with ours for correctness.
- Protocol tests are under the
[`smithy-protocol-tests`](https://github.com/smithy-lang/smithy/tree/main/smithy-protocol-tests/model/rpcv2Cbor)
directory in Smithy.
- We're keeping the `serde_cbor` round-trip tests for defense in depth.
- [ ] https://github.com/smithy-lang/smithy-rs/issues/3709 - Currently
only server-side support has been implemented, because that's what I'm
most familiar. However, we're almost all the way there to add
client-side support.
- ~[ ] [Smithy `document`
shapes](https://smithy.io/2.0/spec/simple-types.html#document) are not
supported. RPC v2's specification currently doesn't indicate how to
implement them.~
- [The
spec](https://smithy.io/2.0/additional-specs/protocols/smithy-rpc-v2.html#shape-serialization)
ended up leaving them as unsupported: "Document types are not currently
supported in this protocol."
## Prerequisite PRs
This section lists prerequisite PRs and issues that would make the diff
for this one lighter or easier to understand. It's preferable that these
PRs be merged prior to this one; some are hard prerequisites. They
mostly relate to parts of the codebase I've had to touch or ~pilfer~
inspect in this PR where I've made necessary changes, refactors and
"drive-by improvements" that are mostly unrelated, although some
directly unlock things I've needed in this patchset. It makes sense to
pull them out to ease reviewability and make this patch more
semantically self-contained.
- https://github.com/awslabs/smithy-rs/pull/2516
- https://github.com/awslabs/smithy-rs/pull/2517
- https://github.com/awslabs/smithy-rs/pull/2522
- https://github.com/awslabs/smithy-rs/pull/2524
- https://github.com/awslabs/smithy-rs/pull/2528
- https://github.com/awslabs/smithy-rs/pull/2536
- https://github.com/awslabs/smithy-rs/pull/2537
- https://github.com/awslabs/smithy-rs/pull/2531
- https://github.com/awslabs/smithy-rs/pull/2538
- https://github.com/awslabs/smithy-rs/pull/2539
- https://github.com/awslabs/smithy-rs/pull/2542
- https://github.com/smithy-lang/smithy-rs/pull/3684
- https://github.com/smithy-lang/smithy-rs/pull/3678
- https://github.com/smithy-lang/smithy-rs/pull/3690
- https://github.com/smithy-lang/smithy-rs/pull/3713
- https://github.com/smithy-lang/smithy-rs/pull/3726
- https://github.com/smithy-lang/smithy-rs/pull/3752
## Testing
<!--- Please describe in detail how you tested your changes -->
<!--- Include details of your testing environment, and the tests you ran
to -->
<!--- see how your change affects other areas of the code, etc. -->
~RPC v2 has still not been added to the Smithy specification. It is
currently being worked on over in the
[`smithy-rpc-v2`](https://github.com/awslabs/smithy/tree/smithy-rpc-v2)
branch.~
This can only be tested _locally_ following these steps:
~1. Clone [the Smithy
repository](https://github.com/smithy-lang/smithy/tree/smithy-rpc-v2)
and checkout the `smithy-rpc-v2` branch.
2. Inside your local checkout of smithy-rs pointing to this PR's branch,
make sure you've added `mavenLocal()` as a repository in the
`build.gradle.kts` files.
[Example](
|
||
|---|---|---|
| .. | ||
| pokemon-service | ||
| pokemon-service-client-usage | ||
| pokemon-service-common | ||
| pokemon-service-lambda | ||
| pokemon-service-tls | ||
| python | ||
| .gitignore | ||
| BENCHMARKS.md | ||
| Cargo.toml | ||
| Makefile | ||
| README.md | ||
README.md
Smithy Rust Server SDK examples
This folder contains:
- example services showcasing Smithy Rust Server SDK, also known as the Rust service framework,
- benchmarking tooling
Three server implementations are available:
/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.
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.
Pre-requisites
You will need install Java 17 to run the smithy-rs code generator and an
installation of Rust, including cargo, to compile the generated code.
(Optional) The Cargo Lambda 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, 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 targets:
codegen: generates the Pokémon service crates (default)build: compiles the generated client and serverclean: deletes build artifactsclippy: lints the codedistclean: delete generated code and build artifactsdoc-open: builds and opens the rustdoc documentationlambda_invoke: invokes a running serverlambda_watch: runs the service on an emulated AWS Lambda environmentrun: runs the Pokémon servicetest: runs integration and unit tests
Running services
To run one of the three server implementations locally, provide the appropriate
service name to the --bin flag:
cargo run --bin pokemon-service[(-lambda|-tls)]
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:
cargo run --bin <service> -- --help
Testing
The /pokemon-test*/tests folders provide integration tests involving the
generated clients.
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.
Benchmarking
Servers running locally (see "Running services") can be benchmarked with any
load testing tool, such as Artillery or wrk.
Please see BENCHMARKS.md for benchmarking results produced by the smithy-rs team.