Skip to content

Commit

Permalink
Update design docs
Browse files Browse the repository at this point in the history
  • Loading branch information
aws-sdk-rust-ci committed Nov 10, 2023
1 parent 9056936 commit 893b597
Show file tree
Hide file tree
Showing 33 changed files with 244 additions and 1,706 deletions.
2 changes: 1 addition & 1 deletion design/client/orchestrator.html
Original file line number Diff line number Diff line change
Expand Up @@ -355,7 +355,7 @@ <h3 id="avoiding-generics-at-all-costs"><a class="header" href="#avoiding-generi
<p><em>NOTE: When inserting values into a config bag, using one of the <code>set_&lt;component&gt;</code> methods is always preferred, as this prevents mistakes related to inserting similar, but incorrect types.</em></p>
</blockquote>
<h3 id="the-actual-code"><a class="header" href="#the-actual-code">The actual code</a></h3>
<p>The current implementation of <code>orchestrate</code> is defined <a href="https://github.com/awslabs/smithy-rs/blob/8bc93fc04dd8c8d7447bfe3f5196a75cba0b10ba/rust-runtime/aws-smithy-runtime/src/client/orchestrator.rs#L23">here</a>, in the <a href="https://github.com/awslabs/smithy-rs/tree/main/rust-runtime/aws-smithy-runtime"><code>aws-smithy-runtime</code> crate</a>. Related code can be found in the <a href="https://github.com/awslabs/smithy-rs/tree/main/rust-runtime/aws-smithy-runtime"><code>aws-smithy-runtime-api</code> crate</a>.</p>
<p>The current implementation of <code>orchestrate</code> is defined <a href="https://github.com/smithy-lang/smithy-rs/blob/8bc93fc04dd8c8d7447bfe3f5196a75cba0b10ba/rust-runtime/aws-smithy-runtime/src/client/orchestrator.rs#L23">here</a>, in the <a href="https://github.com/smithy-lang/smithy-rs/tree/main/rust-runtime/aws-smithy-runtime"><code>aws-smithy-runtime</code> crate</a>. Related code can be found in the <a href="https://github.com/smithy-lang/smithy-rs/tree/main/rust-runtime/aws-smithy-runtime"><code>aws-smithy-runtime-api</code> crate</a>.</p>
<h2 id="frequently-asked-questions"><a class="header" href="#frequently-asked-questions">Frequently asked questions</a></h2>
<h3 id="why-cant-users-create-and-use-their-own-runtime-plugins"><a class="header" href="#why-cant-users-create-and-use-their-own-runtime-plugins">Why can't users create and use their own runtime plugins?</a></h3>
<p>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.</p>
Expand Down
973 changes: 121 additions & 852 deletions design/print.html

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion design/rfcs/rfc0003_presigning_api.html
Original file line number Diff line number Diff line change
Expand Up @@ -339,7 +339,7 @@ <h3 id="avoiding-name-collision"><a class="header" href="#avoiding-name-collisio
<p>If a presignable operation input has a member named <code>presigned</code>, then there will be a name collision with
the function to generate a presigned URL. To mitigate this, <code>RustReservedWords</code> will be updated
to rename the <code>presigned</code> member to <code>presigned_value</code>
<a href="https://github.com/awslabs/smithy-rs/blob/3d61226b5d446f4cc20bf4969f0e56d106cf478b/codegen/src/main/kotlin/software/amazon/smithy/rust/codegen/rustlang/RustReservedWords.kt#L28">similar to how <code>send</code> is renamed</a>.</p>
<a href="https://github.com/smithy-lang/smithy-rs/blob/3d61226b5d446f4cc20bf4969f0e56d106cf478b/codegen/src/main/kotlin/software/amazon/smithy/rust/codegen/rustlang/RustReservedWords.kt#L28">similar to how <code>send</code> is renamed</a>.</p>
<h2 id="changes-checklist"><a class="header" href="#changes-checklist">Changes Checklist</a></h2>
<ul>
<li><input disabled="" type="checkbox" checked=""/>
Expand Down
2 changes: 1 addition & 1 deletion design/rfcs/rfc0004_retry_behavior.html
Original file line number Diff line number Diff line change
Expand Up @@ -319,7 +319,7 @@ <h2 id="changes-checklist"><a class="header" href="#changes-checklist">Changes c
<li><input disabled="" type="checkbox" checked=""/>
Create new Kotlin decorator <code>RetryConfigDecorator</code>
<ul>
<li>Based on <a href="https://github.com/awslabs/smithy-rs/blob/main/aws/sdk-codegen/src/main/kotlin/software/amazon/smithy/rustsdk/RegionDecorator.kt">RegionDecorator.kt</a></li>
<li>Based on <a href="https://github.com/smithy-lang/smithy-rs/blob/main/aws/sdk-codegen/src/main/kotlin/software/amazon/smithy/rustsdk/RegionDecorator.kt">RegionDecorator.kt</a></li>
<li>This decorator will live in the <code>codegen</code> project because it has relevance outside the SDK</li>
</ul>
</li>
Expand Down
2 changes: 1 addition & 1 deletion design/rfcs/rfc0006_service_specific_middleware.html
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@ <h1 class="menu-title">Smithy Rust</h1>
<main>
<h1 id="rfc-service-specific-middleware"><a class="header" href="#rfc-service-specific-middleware">RFC: Service-specific middleware</a></h1>
<blockquote>
<p>Status: <a href="https://github.com/awslabs/smithy-rs/pull/959">Implemented</a></p>
<p>Status: <a href="https://github.com/smithy-lang/smithy-rs/pull/959">Implemented</a></p>
</blockquote>
<p>For a summarized list of proposed changes, see the <a href="#changes-checklist">Changes Checklist</a> section.</p>
<p>Currently, all services use a centralized <code>AwsMiddleware</code> that is defined in the (poorly named) <code>aws-hyper</code> crate. This
Expand Down
2 changes: 1 addition & 1 deletion design/rfcs/rfc0007_split_release_process.html
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@ <h1 class="menu-title">Smithy Rust</h1>
<main>
<h1 id="rfc-split-release-process"><a class="header" href="#rfc-split-release-process">RFC: Split Release Process</a></h1>
<blockquote>
<p>Status: Implemented in <a href="https://github.com/awslabs/smithy-rs/pull/986">smithy-rs#986</a> and <a href="https://github.com/awslabs/aws-sdk-rust/pull/351">aws-sdk-rust#351</a></p>
<p>Status: Implemented in <a href="https://github.com/smithy-lang/smithy-rs/pull/986">smithy-rs#986</a> and <a href="https://github.com/awslabs/aws-sdk-rust/pull/351">aws-sdk-rust#351</a></p>
</blockquote>
<p>At the time of writing, the <code>aws-sdk-rust</code> repository is used exclusively
for the entire release process of both the Rust runtime crates from <code>smithy-rs</code> as
Expand Down
2 changes: 1 addition & 1 deletion design/rfcs/rfc0009_example_consolidation.html
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ <h1 id="rfc-examples-consolidation"><a class="header" href="#rfc-examples-consol
</blockquote>
<p>Currently, the AWS Rust SDK's examples are duplicated across
<a href="https://github.com/awslabs/aws-sdk-rust"><code>awslabs/aws-sdk-rust</code></a>,
<a href="https://github.com/awslabs/smithy-rs"><code>awslabs/smithy-rs</code></a>,
<a href="https://github.com/smithy-lang/smithy-rs"><code>smithy-lang/smithy-rs</code></a>,
and <a href="https://github.com/awsdocs/aws-doc-sdk-examples"><code>awsdocs/aws-doc-sdk-examples</code></a>.
The <code>smithy-rs</code> repository was formerly the source of truth for examples,
with the examples being copied over to <code>aws-sdk-rust</code> as part of the release
Expand Down
2 changes: 1 addition & 1 deletion design/rfcs/rfc0010_waiters.html
Original file line number Diff line number Diff line change
Expand Up @@ -306,7 +306,7 @@ <h2 id="waiter-implementation"><a class="header" href="#waiter-implementation">W
)
}</code></pre>
<p>The retry delay time should be calculated by the same exponential backoff with jitter code that the
<a href="https://github.com/awslabs/smithy-rs/blob/main/rust-runtime/aws-smithy-client/src/retry.rs#L252-L292">default <code>RetryHandler</code> uses in <code>aws-smithy-client</code></a>. This function will need to be split up and made
<a href="https://github.com/smithy-lang/smithy-rs/blob/main/rust-runtime/aws-smithy-client/src/retry.rs#L252-L292">default <code>RetryHandler</code> uses in <code>aws-smithy-client</code></a>. This function will need to be split up and made
available to the waiter implementations so that just the delay can be calculated.</p>
<h2 id="changes-checklist"><a class="header" href="#changes-checklist">Changes Checklist</a></h2>
<ul>
Expand Down
4 changes: 2 additions & 2 deletions design/rfcs/rfc0011_crates_io_alpha_publishing.html
Original file line number Diff line number Diff line change
Expand Up @@ -271,9 +271,9 @@ <h2 id="proposal"><a class="header" href="#proposal">Proposal</a></h2>
<h3 id="short-term-changes-checklist"><a class="header" href="#short-term-changes-checklist">Short-term Changes Checklist</a></h3>
<ul>
<li><input disabled="" type="checkbox" checked=""/>
Prepare runtime crate manifests for publication to crates.io (https://github.com/awslabs/smithy-rs/pull/755)</li>
Prepare runtime crate manifests for publication to crates.io (https://github.com/smithy-lang/smithy-rs/pull/755)</li>
<li><input disabled="" type="checkbox" checked=""/>
Update SDK generator to set correct crate versions (https://github.com/awslabs/smithy-rs/pull/755)</li>
Update SDK generator to set correct crate versions (https://github.com/smithy-lang/smithy-rs/pull/755)</li>
<li><input disabled="" type="checkbox" checked=""/>
Write bulk publish script</li>
<li><input disabled="" type="checkbox" checked=""/>
Expand Down
18 changes: 9 additions & 9 deletions design/rfcs/rfc0012_independent_crate_versioning.html
Original file line number Diff line number Diff line change
Expand Up @@ -191,7 +191,7 @@ <h2 id="terminology"><a class="header" href="#terminology">Terminology</a></h2>
<ul>
<li><strong>AWS SDK Crate</strong>: A crate that provides a client for calling a given AWS service, such as <code>aws-sdk-s3</code> for calling S3.</li>
<li><strong>AWS Runtime Crate</strong>: Any runtime crate that the AWS SDK generated code relies on, such as <code>aws-types</code>.</li>
<li><strong>Smithy Runtime Crate</strong>: Any runtime crate that the <a href="https://github.com/awslabs/smithy-rs">smithy-rs</a> generated code relies on, such as <code>smithy-types</code>.</li>
<li><strong>Smithy Runtime Crate</strong>: Any runtime crate that the <a href="https://github.com/smithy-lang/smithy-rs">smithy-rs</a> generated code relies on, such as <code>smithy-types</code>.</li>
</ul>
<h2 id="requirements"><a class="header" href="#requirements">Requirements</a></h2>
<h3 id="versioning"><a class="header" href="#versioning">Versioning</a></h3>
Expand All @@ -212,7 +212,7 @@ <h3 id="versioning"><a class="header" href="#versioning">Versioning</a></h3>
<li>Breaking changes</li>
<li>Dependency updates for dependencies that are part of the public API</li>
<li>Model updates with API changes</li>
<li>For code-generated crates: when a newer version of <a href="https://github.com/awslabs/smithy-rs">smithy-rs</a> is used to generate the crate</li>
<li>For code-generated crates: when a newer version of <a href="https://github.com/smithy-lang/smithy-rs">smithy-rs</a> is used to generate the crate</li>
</ul>
</li>
<li><code>patch</code>:
Expand All @@ -230,7 +230,7 @@ <h3 id="versioning"><a class="header" href="#versioning">Versioning</a></h3>
<li>Changes that aren't breaking</li>
<li>Dependency updates for dependencies that are part of the public API</li>
<li>Model updates with API changes</li>
<li>For code-generated crates: when a newer version of <a href="https://github.com/awslabs/smithy-rs">smithy-rs</a> is used to generate the crate</li>
<li>For code-generated crates: when a newer version of <a href="https://github.com/smithy-lang/smithy-rs">smithy-rs</a> is used to generate the crate</li>
</ul>
</li>
<li><code>patch</code>:
Expand Down Expand Up @@ -283,13 +283,13 @@ <h3 id="version-tracking"><a class="header" href="#version-tracking">Version Tra
the version numbers from runtime crates directly, and it will use the rules from the next section to determine
the version numbers for the generated crates.</p>
<h3 id="versioning-for-code-generated-sdk-service-crates"><a class="header" href="#versioning-for-code-generated-sdk-service-crates">Versioning for Code Generated (SDK Service) Crates</a></h3>
<p>Code generated crates will have their <code>minor</code> version bumped when the version of <a href="https://github.com/awslabs/smithy-rs">smithy-rs</a> used to generate
<p>Code generated crates will have their <code>minor</code> version bumped when the version of <a href="https://github.com/smithy-lang/smithy-rs">smithy-rs</a> used to generate
them changes, or when model updates with API changes are made. Three pieces of information are required to
handle this process: the previously released version number, the <a href="https://github.com/awslabs/smithy-rs">smithy-rs</a> version used to generate the code,
handle this process: the previously released version number, the <a href="https://github.com/smithy-lang/smithy-rs">smithy-rs</a> version used to generate the code,
and the level of model updates being applied. For this last one, if there are multiple model updates that
affect only documentation, but then one model update that affects an API, then as a whole they will be
considered as affecting an API and require a <code>minor</code> version bump.</p>
<p>The previously released version number will be retrieved from crates.io using its API. The <a href="https://github.com/awslabs/smithy-rs">smithy-rs</a> version
<p>The previously released version number will be retrieved from crates.io using its API. The <a href="https://github.com/smithy-lang/smithy-rs">smithy-rs</a> version
used during code generation will become a build artifact that is saved to <code>versions.toml</code> in <a href="https://github.com/awslabs/aws-sdk-rust">aws-sdk-rust</a>.
During phase 1, the tooling required to know if a model is a documentation-only change will not be available,
so all model changes will result in a <code>minor</code> version bump during this phase.</p>
Expand All @@ -303,11 +303,11 @@ <h3 id="versioning-for-code-generated-sdk-service-crates"><a class="header" href
</pre>
<ul>
<li><strong>A: smithy-rs changed?</strong>: Compare the <code>smithy_rs_version</code> in the previous <code>versions.toml</code> with the
next <code>versions.toml</code> file, and if the values are different, consider <a href="https://github.com/awslabs/smithy-rs">smithy-rs</a> to have changed.</li>
next <code>versions.toml</code> file, and if the values are different, consider <a href="https://github.com/smithy-lang/smithy-rs">smithy-rs</a> to have changed.</li>
<li><strong>B: model changed?</strong>: Similarly, compare the <code>model_hash</code> for the crate in <code>versions.toml</code>.</li>
</ul>
<h3 id="versioning-for-runtime-crates"><a class="header" href="#versioning-for-runtime-crates">Versioning for Runtime Crates</a></h3>
<p>The old scheme of all runtime crates in <a href="https://github.com/awslabs/smithy-rs">smithy-rs</a> having a fake <code>0.0.0-smithy-rs-head</code> version number with
<p>The old scheme of all runtime crates in <a href="https://github.com/smithy-lang/smithy-rs">smithy-rs</a> having a fake <code>0.0.0-smithy-rs-head</code> version number with
a build step to replace those with a consistent <code>major.minor</code> will be removed. These runtime crates will begin
having their actual next version number in the Cargo.toml file in smithy-rs.</p>
<p>This introduces a new problem where a developer can forget to bump a runtime crate version, so a method of
Expand Down Expand Up @@ -367,7 +367,7 @@ <h3 id="changes-checklist"><a class="header" href="#changes-checklist">Changes C
<li><input disabled="" type="checkbox"/>
Establish initial <code>versions.toml</code> in <code>aws-sdk-rust/main</code></li>
<li><input disabled="" type="checkbox"/>
Set version numbers in runtime crates in <a href="https://github.com/awslabs/smithy-rs">smithy-rs</a></li>
Set version numbers in runtime crates in <a href="https://github.com/smithy-lang/smithy-rs">smithy-rs</a></li>
<li><input disabled="" type="checkbox"/>
Update the auto-sync tool to generate <code>versions.toml</code></li>
<li><input disabled="" type="checkbox"/>
Expand Down
4 changes: 2 additions & 2 deletions design/rfcs/rfc0013_body_callback_apis.html
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,7 @@ <h2 id="the-implementation"><a class="header" href="#the-implementation">The Imp
fn make_new(&amp;self) -&gt; Box&lt;dyn SendCallback&gt; { BodyCallback::make_new(self) }
}</code></pre>
<p>The changes we need to make to <code>ByteStream</code>:</p>
<p><em>(The current version of <code>ByteStream</code> and <code>Inner</code> can be seen <a href="https://github.com/awslabs/smithy-rs/blob/f76bc159bf16510a0873f5fba691cb05816f4192/rust-runtime/aws-smithy-http/src/byte_stream.rs#L205">here</a>.)</em></p>
<p><em>(The current version of <code>ByteStream</code> and <code>Inner</code> can be seen <a href="https://github.com/smithy-lang/smithy-rs/blob/f76bc159bf16510a0873f5fba691cb05816f4192/rust-runtime/aws-smithy-http/src/byte_stream.rs#L205">here</a>.)</em></p>
<pre><code class="language-rust ignore">// in `aws_smithy_http::byte_stream`...

// We add a new method to `ByteStream` for inserting callbacks
Expand All @@ -226,7 +226,7 @@ <h2 id="the-implementation"><a class="header" href="#the-implementation">The Imp
}
}</code></pre>
<p>The changes we need to make to <code>SdkBody</code>:</p>
<p><em>(The current version of <code>SdkBody</code> can be seen <a href="https://github.com/awslabs/smithy-rs/blob/f76bc159bf16510a0873f5fba691cb05816f4192/rust-runtime/aws-smithy-http/src/body.rs#L71">here</a>.)</em></p>
<p><em>(The current version of <code>SdkBody</code> can be seen <a href="https://github.com/smithy-lang/smithy-rs/blob/f76bc159bf16510a0873f5fba691cb05816f4192/rust-runtime/aws-smithy-http/src/body.rs#L71">here</a>.)</em></p>
<pre><code class="language-rust ignore">// In aws_smithy_http::body...

#[pin_project]
Expand Down
Loading

0 comments on commit 893b597

Please sign in to comment.