This PR makes some progress towards documenting the
`aws-smithy-runtime-api` crate, as well as some additional work to make
it more stable:
- Places the `client` module behind a `client` feature so that it will
be possible to add a `server` module/feature in the future.
- Deletes `ConfigBagAccessors`.
- Renames auth types to reflect changes in the internal spec.
- Moves `RequestAttempts` into the `client::retries` module.
- Moves several types that were in floating around in
`client::orchestrator` to their own modules.
- Renames `Connector` to `HttpConnector`.
- Changes `DynResponseDeserializer` to `SharedResponseDeserializer` for
consistency with serialization, and also so that it could be moved into
runtime components or config in the future (since those need to
implement `Clone`).
- Updates the identity and auth design doc.
- Updates READMEs and crate-level documentation.
- Fixes most, but not all, the missing documentation in the crate.
- Hides the builder macros.
----
_By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice._
So far, servers have tacitly worked with the notion that plugins come in
two flavors: "HTTP plugins" and "model plugins":
- A HTTP plugin acts on the HTTP request before it is deserialized, and
acts on the HTTP response after it is serialized.
- A model plugin acts on the modeled operation input after it is
deserialized, and acts on the modeled operation output or the modeled
operation error before it is serialized.
However, this notion was never reified in the type system. Thus, users
who pass in a model plugin where a HTTP plugin is expected or
viceversa in several APIs:
```rust
let pipeline = PluginPipeline::new().push(http_plugin).push(model_plugin);
let app = SimpleService::builder_with_plugins(http_plugins, IdentityPlugin)
.post_operation(handler)
/* ... */
.build()
.unwrap();
```
would get the typical Tower service compilation errors, which can get
very confusing:
```
error[E0631]: type mismatch in function arguments
--> simple/rust-server-codegen/src/main.rs:47:6
|
15 | fn new_svc<S, Ext>(inner: S) -> model_plugin::PostOperationService<S, Ext> {
| -------------------------------------------------------------------------- found signature defined here
...
47 | .post_operation(post_operation)
| ^^^^^^^^^^^^^^ expected due to this
|
= note: expected function signature `fn(Upgrade<RestJson1, (PostOperationInput, _), PostOperationService<aws_smithy_http_server::operation::IntoService<simple::operation_shape::PostOperation, _>, _>>) -> _`
found function signature `fn(aws_smithy_http_server::operation::IntoService<simple::operation_shape::PostOperation, _>) -> _`
= note: required for `LayerFn<fn(aws_smithy_http_server::operation::IntoService<..., ...>) -> ... {new_svc::<..., ...>}>` to implement `Layer<Upgrade<RestJson1, (PostOperationInput, _), PostOperationService<aws_smithy_http_server::operation::IntoService<simple::operation_shape::PostOperation, _>, _>>>`
= note: the full type name has been written to '/local/home/davidpz/workplace/smithy-ws/src/SmithyRsSource/target/debug/deps/simple-6577f9f79749ceb9.long-type-4938700695428041031.txt'
```
This commit introduces the `HttpPlugin` and `ModelPlugin` marker traits,
allowing plugins to be marked as an HTTP plugin, a model plugin, or
both. It also removes the primary way of concatenating plugins,
`PluginPipeline`, in favor of `HttpPlugins` and `ModelPlugins`, which
eagerly check that whenever a plugin is `push`ed, it is of the expected
type. The generated service type in the server SDKs'
`builder_with_plugins` constructor now takes an `HttpPlugin` as its
first parameter, and a `ModelPlugin` as its second parameter.
I think this change perhaps goes counter to the generally accepted
wisdom that trait bounds in Rust should be enforced "at the latest
possible moment", that is, only when the behavior encoded in the trait
implementation is relied upon in the code (citation needed).
However, the result is that exposing the concepts of HTTP plugin and
model plugin in the type system makes for code that is easier to reason
about, and produces more helpful compiler error messages.
Documentation about the plugin system has been expanded, particularly on
how to implement model plugins.
## Checklist
<!--- If a checkbox below is not applicable, then please DELETE it
rather than leaving it unchecked -->
- [x] I have updated `CHANGELOG.next.toml` if I made changes to the
smithy-rs codegen or runtime crates
----
_By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice._
## Motivation and Context
Closes https://github.com/awslabs/smithy-rs/issues/1839
Currently, `Plugin` is parameterized by protocol and operation. To
improve symmetry, extensibility and uniformity we switch this to be
parameterized by service instead. The protocol can still be recovered
via the `type Protocol` associated type on `ServiceShape`.
## Description
- Add `ServiceShape` trait, encoding the properties of a Smithy service.
- Change `Plugin<Protocol, Operation, S>` to `Plugin<Service, Operation,
S>`.
- Add `FilterByOperation` and `filter_by_operation` `Plugin`s.
This replaces the existing custom interceptor disable logic with shared
logic to allow generally disabling any public interceptors from Runtime
plugins. The previous behavior was very brittle because it relied
heavily on runtime plugin execution order.
## Motivation and Context
- simplify presigning behavior
- generalize logic to disable interceptors
## Description
Create `disable_interceptor` struct, which, when inserted into the
configuration bag can disable an interceptor via the `Interceptors`
execution interface.
## Testing
- ` (cd aws/sdk/build/aws-sdk/sdk/s3 && cargo test --test presigning)`
## Checklist
<!--- If a checkbox below is not applicable, then please DELETE it
rather than leaving it unchecked -->
- [ ] I have updated `CHANGELOG.next.toml` if I made changes to the
smithy-rs codegen or runtime crates
- [ ] I have updated `CHANGELOG.next.toml` if I made changes to the AWS
SDK, generated SDK code, or SDK runtime crates
----
_By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice._
## Motivation and Context
Closes https://github.com/awslabs/smithy-rs/issues/2004
## Description
Run `mdbook test` over the `design` folder.
## TODO
- [x] Ignore the RFC sections using `ignore` tag on the code blocks.
- [ ] Fix the remaining examples.
- [x] Ensure local `rust-runtime` dependencies are being used.
---------
Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
Co-authored-by: 82marbag <69267416+82marbag@users.noreply.github.com>
* Show how to plug a connector
* For TLS: keep rustls, only
## Checklist
<!--- If a checkbox below is not applicable, then please DELETE it
rather than leaving it unchecked -->
- [x] I have updated `CHANGELOG.next.toml` if I made changes to the
smithy-rs codegen or runtime crates
- [x] I have updated `CHANGELOG.next.toml` if I made changes to the AWS
SDK, generated SDK code, or SDK runtime crates
----
_By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice._
---------
Signed-off-by: Daniele Ahmed <ahmeddan@amazon.de>
## Motivation and Context
This PR adds a design doc for client identity and auth for the new
client orchestrator.
----
_By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice._
---------
Co-authored-by: Zelda Hessler <zhessler@amazon.com>
This document is intended to capture the philosophy and ideas
underpinning the current state of the orchestrator and should grow
alongside the orchestrator.
Abhinav requested something like this and I think it'll be helpful for
future people.
----
_By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice._
---------
Co-authored-by: John DiSanti <jdisanti@amazon.com>
* Remove deprecated ResolveAwsEndpoint and related interfaces.
* update changelog with pointer
* Rename AwsEndpointDecorator to have a more appropriate name
* Allow endpoint resolver to be omitted
* Split endpoint resolution middleware into two parts & refactor endpoint generation
* Endpoints 2.0 Integration pre-work
This PR does a 3 bits of pre-work ahead of ep2 integration:
1. Split endpoint resolution into two separate middlewares:
1. A smithy native middleware that applies URI and headers
2. An AWS middleware that applies the auth schemes
2. Add vendorParams support to the ProtocolTestGenerator so that protocol tests can insert a region.
3. Simplify endpoint resolution logic by allowing `make_operation` to fail when an endpoint cannot be resolved.
* Back out previous change to insert endpoint directly into the bag
* backout changes to property bag
* Update changelog & add more docs
* Fix AWS test
* Fix test
* Link to super from Handler and OperationService
* Note that structure documentation is from model
* Don't refer to ZSTs in operation_shape.rs opener
* Re-export everything from service to root
* Add reference to root documentation on service
* Fix spelling of MissingOperationsError
* #[doc(hidden)] for opaque_future
* Rename from-parts.md to from_parts.md
* Fix Connected link
* Use S type parameter and service as variable name
* Remove MissingOperation dead code
* Remove Operation header from operation.rs
* Remove reference to closures
* Document ConnectInfo<T> .0
* Add BoxBody documentation
* Rephrase operation.rs documentation
* Reference PluginPipeline from PluginStack
* Move the BoxBody documentation
* Document Plugin associated types
* Add example implementation for Plugin
* Link to plugin module from Plugin
* Improve FromParts/FromRequest documentation
* Remove links to doc(hidden) RuntimeError
* Add link from Upgradable to operation module
* Implement RFC 23, with the exception of PluginBuilder
* Update documentation.
* Avoid star re-exports.
* Elide implementation details in `Upgradable`.
* Update wording in docs to avoid personal pronouns.
* Update `Upgradable`'s documentation.
* Template the service builder name.
* Template MissingOperationsError directly.
* Code-generate an array directly.
* Sketch out the implementation of `PluginPipeline`.
Remove `PluginExt`.
Add a public constructor for `FilterByOperationName`.
* Ask for a `PluginPipeline` as input for the generated builder.
* Rename `add` to `push`.
* Remove Pluggable.
Rename `composer` module to `pipeline`.
* Remove all mentions of `Pluggable` from docs and examples.
* Fix punctuation.
* Rename variable from `composer` to `pipeline` in doc examples.
* Add a free-standing function for filtering.
* Rename.
* Rename.
* Update design/src/server/anatomy.md
Co-authored-by: david-perez <d@vidp.dev>
* Use `rust` where we do not need templating.
* Remove unused variable.
* Add `expect` message to point users at our issue board in case a panic slips through.
* Typo.
* Update `expect` error message.
* Refactor the `for` loop in ``requestSpecMap` into an `associateWith` call.
* Remove unnecessary bound - since `new` is private, the condition is already enforced via `filter_by_operation_name`.
* Use `Self` in `new`.
* Rename `inner` to `into_inner`
* Rename `concat` to `append` to correctly mirror Vec's API terminology.
* Fix codegen to use renamed method.
* Cut down the public API surface to key methods for a sequence-like interface.
* Add a note about ordering.
* Add method docs.
* Add Default implementation.
* Fix new pokemon bin example.
* Fix new pokemon bin example.
* Fix code-generated builder.
* Fix unresolved symbolProvider.
* Assign the `expect` error message to a variable.
* Do not require a PluginPipeline as input to `builder_with_plugins`.
* Reverse plugin application order.
* Upgrade documentation.
* Add a test to verify that plugin layers are executed in registration order.
* Add license header.
* Update middleware.md
* Typo.
* Fix more builder() calls.
Co-authored-by: david-perez <d@vidp.dev>
* Implement RFC 23, with the exception of PluginBuilder
* Update documentation.
* Elide implementation details in `Upgradable`.
* Update wording in docs to avoid personal pronouns.
* Update `Upgradable`'s documentation.
* Template the service builder name.
* Template MissingOperationsError directly.
* Code-generate an array directly.
* Update design/src/server/anatomy.md
Co-authored-by: david-perez <d@vidp.dev>
* Use `rust` where we do not need templating.
* Remove unused variable.
* Add `expect` message to point users at our issue board in case a panic slips through.
* Typo.
* Update `expect` error message.
* Refactor the `for` loop in ``requestSpecMap` into an `associateWith` call.
* Fix new pokemon bin example.
* Fix new pokemon bin example.
* Fix unresolved symbolProvider.
* Assign the `expect` error message to a variable.
* Omit additional generic parameters in Upgradable when it's first introduced.
Co-authored-by: david-perez <d@vidp.dev>
* RFC draft.
* Fix checkbox.
* Briefly describe the strategy in the `Overview` section.
* Add setter snippet
* Dive deeper into alternative mechanisms for scoping plugins.
* Add more changes.
* Fix snippet.
* Elaborate on type erasure.
* Remove dangling footnote.
* Fix common type.
* Add more caveats.
* Update the first approach for lazy type erasure
Russell Cohen