diff --git a/design/client/orchestrator.html b/design/client/orchestrator.html
index 5de48f5e28..5d35229746 100644
--- a/design/client/orchestrator.html
+++ b/design/client/orchestrator.html
@@ -355,7 +355,7 @@
-The current implementation of orchestrate
is defined here, in the aws-smithy-runtime
crate. Related code can be found in the aws-smithy-runtime-api
crate.
+The current implementation of orchestrate
is defined here, in the aws-smithy-runtime
crate. Related code can be found in the aws-smithy-runtime-api
crate.
We chose to hide the runtime plugin API from users because we are concerned that exposing it will cause more problems than it solves. Instead, we encourage users to use interceptors. This is because, when setting a runtime plugin, any existing runtime plugin with the same type will be replaced. For example, there can only be one retry strategy or response deserializer. Errors resulting from unintentionally overriding a plugin would be difficult for users to diagnose, and would consume valuable development time.
diff --git a/design/print.html b/design/print.html
index 977e9adf90..8a3b4094bc 100644
--- a/design/print.html
+++ b/design/print.html
@@ -356,10 +356,10 @@
Shape: The core Smithy primitive. A smithy model is composed of nested shapes defining an API.
-Symbol
: A Representation of a type including namespaces and any dependencies required to use a type. A shape can be converted into a symbol by a SymbolVisitor
. A SymbolVisitor
maps shapes to types in your programming language (e.g. Rust). In the Rust SDK, see SymbolVisitor.kt. Symbol visitors are composable—many specific behaviors are mixed in via small & focused symbol providers, e.g. support for the streaming trait is mixed in separately.
+Symbol
: A Representation of a type including namespaces and any dependencies required to use a type. A shape can be converted into a symbol by a SymbolVisitor
. A SymbolVisitor
maps shapes to types in your programming language (e.g. Rust). In the Rust SDK, see SymbolVisitor.kt. Symbol visitors are composable—many specific behaviors are mixed in via small & focused symbol providers, e.g. support for the streaming trait is mixed in separately.
-Writer
: Writers are code generation primitives that collect code prior to being written to a file. Writers enable language specific helpers to be added to simplify codegen for a given language. For example, smithy-rs
adds rustBlock
to RustWriter
to create a "Rust block" of code.
+Writer
: Writers are code generation primitives that collect code prior to being written to a file. Writers enable language specific helpers to be added to simplify codegen for a given language. For example, smithy-rs
adds rustBlock
to RustWriter
to create a "Rust block" of code.
writer.rustBlock("struct Model") {
model.fields.forEach {
write("${field.name}: #T", field.symbol)
@@ -393,8 +393,8 @@
double | f64 |
bigInteger | BigInteger (Not implemented yet) |
bigDecimal | BigDecimal (Not implemented yet) |
-timestamp | DateTime |
-document | Document |
+timestamp | DateTime |
+document | Document |
@@ -405,7 +405,7 @@
pub struct BigDecimal(String);
}
This will enable us to add helpers over time as requested. Users will also be able to define their own conversions into their preferred large-number libraries.
-As of 5/23/2021 BigInteger / BigDecimal are not included in AWS models. Implementation is tracked here.
+As of 5/23/2021 BigInteger / BigDecimal are not included in AWS models. Implementation is tracked here.
chrono is the current de facto library for datetime in Rust, but it is pre-1.0. DateTimes are represented by an SDK defined structure modeled on std::time::Duration
from the Rust standard library.
#![allow(unused)]
@@ -482,7 +482,7 @@
-This occurs because Rust types must be a size known at compile time. The way around this, as the message suggests, is to Box the offending type. smithy-rs
implements this design in RecursiveShapeBoxer.kt
+This occurs because Rust types must be a size known at compile time. The way around this, as the message suggests, is to Box the offending type. smithy-rs
implements this design in RecursiveShapeBoxer.kt
To support this, as the message suggests, we must "Box
" the offending type. There is a touch of trickiness—only one element in the cycle needs to be boxed, but we need to select it deterministically such that we always pick the same element between multiple codegen runs. To do this the Rust SDK will:
- Topologically sort the graph of shapes.
@@ -526,7 +526,7 @@
-Handlers and operations are upgraded to a Route
as soon as they are registered against the service builder. You can think of Route
as a boxing layer in disguise.
+Handlers and operations are upgraded to a Route
as soon as they are registered against the service builder. You can think of Route
as a boxing layer in disguise.
You can transform a builder instance into a complete service (PokemonService
) using one of the following methods:
build
. The transformation fails if one or more operations do not have a registered handler;
@@ -2512,50 +2512,50 @@
Crates in /rust-runtime
(informally referred to as "runtime crates") are added to a crate's dependency only when used.
For example, if a model uses event streams, the generated crates will depend on aws-smithy-eventstream
.
-smithy-rs
's entry points are Smithy code-generation plugins, and is not a command. One entry point is in RustCodegenPlugin::execute and
+
smithy-rs
's entry points are Smithy code-generation plugins, and is not a command. One entry point is in RustCodegenPlugin::execute and
inherits from SmithyBuildPlugin
in smithy-build. Code generation is in Kotlin and shared common, non-Rust specific code with the smithy
Java repository. They plug into the Smithy gradle plugin, which is a gradle plugin.
The comment at the beginning of execute
describes what a Decorator
is and uses the following terms:
- Context: contains the model being generated, projection and settings for the build
-- Decorator: (also referred to as customizations) customizes how code is being generated. AWS services are required to sign with the SigV4 protocol, and a decorator adds Rust code to sign requests and responses.
+
- Decorator: (also referred to as customizations) customizes how code is being generated. AWS services are required to sign with the SigV4 protocol, and a decorator adds Rust code to sign requests and responses.
Decorators are applied in reverse order of being added and have a priority order.
- Writer: creates files and adds content; it supports templating, using
#
for substitutions
- Location: the file where a symbol will be written to
-The only task of a RustCodegenPlugin
is to construct a CodegenVisitor
and call its execute() method.
-CodegenVisitor::execute()
is given a Context
and decorators, and calls a CodegenVisitor.
+The only task of a RustCodegenPlugin
is to construct a CodegenVisitor
and call its execute() method.
+CodegenVisitor::execute()
is given a Context
and decorators, and calls a CodegenVisitor.
CodegenVisitor, RustCodegenPlugin, and wherever there are different implementations between client and server, such as in generating error types,
have corresponding server versions.
Objects used throughout code generation are:
-- Symbol: a node in a graph, an abstraction that represents the qualified name of a type; symbols reference and depend on other symbols, and have some common properties among languages (such as a namespace or a definition file). For Rust, we add properties to include more metadata about a symbol, such as its type
-- RustType:
Option<T>
, HashMap
, ... along with their namespaces of origin such as std::collections
-- RuntimeType: the information to locate a type, plus the crates it depends on
+- Symbol: a node in a graph, an abstraction that represents the qualified name of a type; symbols reference and depend on other symbols, and have some common properties among languages (such as a namespace or a definition file). For Rust, we add properties to include more metadata about a symbol, such as its type
+- RustType:
Option<T>
, HashMap
, ... along with their namespaces of origin such as std::collections
+- RuntimeType: the information to locate a type, plus the crates it depends on
- ShapeId: an immutable object that identifies a
Shape
Useful conversions are:
SymbolProvider.toSymbol(shape)
where SymbolProvider
constructs symbols for shapes. Some symbols require to create other symbols and types;
-event streams and other streaming shapes are an example.
-Symbol providers are all applied in order; if a shape uses a reserved keyword in Rust, its name is converted to a new name by a symbol provider,
-and all other providers will work with this new symbol.
+event streams and other streaming shapes are an example.
+Symbol providers are all applied in order; if a shape uses a reserved keyword in Rust, its name is converted to a new name by a symbol provider,
+and all other providers will work with this new symbol.
Model.expectShape(shapeId)
Each model has a shapeId
to shape
map; this method returns the shape associated with this shapeId.
-Some objects implement a transform
method that only change the input model, so that code generation will work on that new model. This is used to, for example, add a trait to a shape.
-CodegenVisitor
is a ShapeVisitor
. For all services in the input model, shapes are converted into Rust;
-here is how a service is constructed,
-here a structure and so on.
-Code generation flows from writer to files and entities are (mostly) generated only on a need-by-need basis.
-The complete result is a Rust crate,
-in which all dependencies are written into their modules and lib.rs
is generated (here).
-execute()
ends by running cargo fmt,
+
Some objects implement a transform
method that only change the input model, so that code generation will work on that new model. This is used to, for example, add a trait to a shape.
+CodegenVisitor
is a ShapeVisitor
. For all services in the input model, shapes are converted into Rust;
+here is how a service is constructed,
+here a structure and so on.
+Code generation flows from writer to files and entities are (mostly) generated only on a need-by-need basis.
+The complete result is a Rust crate,
+in which all dependencies are written into their modules and lib.rs
is generated (here).
+execute()
ends by running cargo fmt,
to avoid having to format correctly Rust in Writer
s and to be sure the generated code follows the styling rules.
What is an RFC?: An RFC is a document that proposes a change to smithy-rs
or the AWS Rust SDK. Request for Comments means a request for discussion and oversight about the future of the project from maintainers, contributors and users.
@@ -3240,7 +3240,7 @@ At the time of writing, the aws-sdk-rust
repository is used exclusively
for the entire release process of both the Rust runtime crates from smithy-rs
as
@@ -3950,7 +3950,7 @@