https://awslabs.github.io/smithy/spec/http.html#httpheader-trait

• code on http trait
• httpError (and optional code)
• httpHeader—some complexity, may support lists of timestamps requiring complex parsing
• httpPayload
• httpPrefix headers

awsRestJson and AwsJson1.1 both rely on recursive structures

When a set is serialized to the request header, the ordering (unsurprisingly) is non-deterministic. We need to figure out the best way to address this in the protocol tests.

The same issue occurs when serializing sets to JSON.

One potential options is https://doc.rust-lang.org/std/collections/struct.BTreeSet.html

The final design is TBD, but all protocols will need some form of configuration object

Small once #76 is done

Small once #76 is done

Could be deferred although figuring how how they fit into the API needs to happen soon than later

DynamoDB integration tests that run against localdynamo—for now, these will use Hyper & a faker signer. The thing we actually want to exercise is the serialization & deserialization layers

Smithy allows fields to be named things that are reserved words in Rust like as. Currently, this will generate code that won't compile.

Currently, they are just deserialized as the code, but we should also attempt to parse the message

Currently, only epoch deserialization is supported. This is required for #7 and #20

• iso8601
• httpdate

Generate initial config objects for services. From the Smithy side, this is only going to contain idempotency control

Tracking issue for full support of the AWS Json 1.0 protocol

• Serialization
  • Union serializers
  • Enum serializers
  • Structure serializers
• Deserialization

• Event Stream frame encoding/decoding (#609)
• http::Response -> operation::Response refactoring in smithy-http (#635)
• Refactor sigv4 to sign arbitrary data rather than http::Request
• Track the initial signature in the property bag
• Rust implementation for Event Stream sender in input
• Rust implementation for Event Stream receiver in output
• Codegen
  • Event Stream input sender w/ signing
  • Event Stream output receiver
  • Event Stream traits
  • Selection of HTTP protocol version via Smithy traits (e.g., @restXml)
    • Current service models aren't using these correctly, and some operations actually require HTTP 1 for bidirectional event streaming
    • For now: error out if there's an operation that doesn't specify HTTP 2 for bidirectional streaming, and customize models for known bad operations to specify HTTP 2
  • Events marked with @error are terminal; should filter them out of the event stream union and handle them as actual SdkErrors
  • Make Event Stream recv() errors compatible with other SdkErrors when using the ? operator
  • Non-HTTP bound protocols like AWS JSON send initial members as a struct embedded in a first event frame
  • Generate new error type for Event Stream recv() since it's not 1-to-1 with the operation errors
• Testing
  • Record bidirectional traffic against all supported protocols:
    • restJson1
    • awsJson1 and awsJson1_1
    • awsQuery
    • ec2Query
    • restXml
  • Exercise all event stream header types
  • Exercise all event stream payload types (blob, string, struct, union)
  • Write replay tests
• Test the developer experience when the Event Stream input stream yields an error (where does the error go?)

The docs as they come out of Smithy have a number of shortcomings:

• They are mostly HTML, which, while technically markdown is very hard to read in code
• They don't respect rustdoc's first-line-is-the-header convention which leads to docs which are either missing headers or have too much in the header
• The <code>FooInput</code> that is used can't use rustdocs links unless we parse that out and reparent it to an actual thing.
• Since we are renaming Exception to Error, if we continue to do that, we must also update the docs
• Cargo.toml description field cannot have Markdown in it
• Rustdoc for Rust 1.53 requires bare links to be surrounded by angle brackets (e.g., <https://github.com> rather than https://github.com)
• Generate code examples for operations that have no required args

Probably something like:

struct Set<T: Hash>(Vec<T>)

Operations should produce an enum of their possible error variants.

This is a general unmodeled error fallback. We should try to extract deserialize and find a message.

Currently, the Rust code generator assumes that all members with the httpLabel trait are required. This isn't always true. For example, S3's GetObjectRequest structure binds partNumber to a URI element, but it's necessarily optional since it's only accepted when retrieving a single part of a multi-part object. As is, the generated code forces this field to be specified in all requests.

I'd say "just examine the member for the required trait," but I sadly don't see many models using it. FWIW, The AWS service models bundled with botocore appear to correctly model all required members regardless of where they appear on the wire. Are these service definitions hand-maintained?

Currently, we aren't used the smithy @documentation trait

• Endpoint trait support
• Basic AWS endpoint implementation
• endpoints.json dynamic resolver generation
• Design endpoint discovery
• Endpoint discovery implementation

The current strategy of the Rust SDK is to rename Exception to Error and Error to Error_ (to prevent conflicts with a similarly named Exception.

While this strategy is sound, it's worth a discussion about whether it's a thing we want to do.

The URI specified by a request may also specify literals

Needs to be backwards compatible to add and remove, which I think means that a custom debug implementation is probably required.

Another option large design option could be making all fields private and using accessors.

This would allow us to have a string accessor even though the underlying type was Sensitive

Needs to support some degree of external customization

Should be pretty straightforward once #10 is done

As noted in #53, refactor generated code to expose a single top level operations model

See #102 — when a queryParam (or any field) is unboxed and is a 0 value, it should not be serialized into the http request

Needs to generate real UUIDs normally & "0000 etc." in protocol tests

• Design/RFC developer experience
• Implement Jmespath Smithy shape traversal (#3526)
• Code generate waiters and hook into existing retry strategy

Automated CI jobs. Should run on pull requests.

• Codegen tests pass
• Integration tests pass
• Ktlint passes
• < 5 minutes to finish

These tests should target the operation shape and use the #61 to ensure the correct type of error is deserialized

Currently, the StructuredDate representation in Smithy types doesn't support dates where the epoch timestamp is negative

Design how event streams fit into the rest of the API

Support for all features in https://awslabs.github.io/smithy/spec/http-protocol-compliance-tests.html#httprequesttests

• structures created
• query strings validated
• headers validated
• bodies validated

Could be pure rust or backed by the CRT

As requested by @rcoh; here are few things I've noticed from reading the documentation.

• dynamo::model::FailureException is the only type in the model module that represents an error. I think this happened because the underlying Smithy definition might be incorrect.
  • Generally speaking, I don't think that "Exception" shouldn't appear in any Rust code
• The operation module is noisy from the builder module [appendix one]. It also hides the actual input operations below the documentation's fold. Unfortunately, applying #[doc(hidden)] to a module applies to all nested modules and exports, which means that the builder options are hidden: rust-lang/rust#59368
• When documenting input structs, consider using the operation's documentation instead of the input object's documentation [appendix two]. Input structs are the customer's entrypoint to the service, not the operation itself. With a sans-io interface, there's no place to document operations, which often serve as the why of a service's operation.
• The separate impl blocks for inputs without different generic bounds feel off to me [appendix three]. I'd unify the two.
  • I'm not sure that an assemble associated function is necessary for non-streaming operations, but I believe this relates to the (somewhat) open design question around (de)serialization.
• Intra-doc links don't resolve to a URL. You might need to define a [docs-url] in the root of each crate: tokio-rs/tracing#1078 (comment).
  • Consider using the tokio-rs/tracing repo as an example for documentation configuration. Members of the rustdoc team have use tokio-rs/tracing as a testbed for unstable features.

Appendix

Appendix One

Appendix Two

Appendix Three

Generate deserializers for response bodies

Request ids are returned in different locations in each protocol (eg. headers, JSON body, XML body etc.).

As an end customer, it should be straightforward to extract that request id from any given response.

• Make it trivial to access the request ID programmatically
• Add a tracing::debug! or tracing::debug_span! somewhere in the AWS middleware to attach the request ID to logs

It should be possible to remove the need to call .build() by implementing Into<T> for builders

Tracking issue for AwsJson 1.1 support

AwsJson1.1 is done when the protocol tests pass for serialization and deserialization

• Support recursive structures (#6)
• Document type support (#31)
• Error deserializer support

Do we use serde with renames? Do we do something more complex? Do we need our own aws-xml-serde?

Large at least until #113 is finalized