Unverified Commit efd1508e authored by Thomas Cameron's avatar Thomas Cameron Committed by GitHub
Browse files

Update the event stream section in RFC30 (#2243)

parent 7ad342aa
Loading
Loading
Loading
Loading
+31 −28
Original line number Diff line number Diff line
@@ -206,53 +206,56 @@ The resulting size of the serialized data is smaller when tagged externally, as

For the reasons mentioned above, we implement an enum that is externally tagged.

## Data Types to Skip
We are going to skip serialization and deserialization of fields that have the datatype that corresponds to `@streaming blob` and `@streaming union` from smithy.
Any fields with these data types are tagged with `#[serde(skip, default = "..name of the function for tailored serialization/de-serialization")]`.
## Data Types to Skip Serialization/Deserialization
We are going to skip serialization and deserialization of fields that have the datatype that corresponds to `@streaming blob` from smithy.
Any fields with these data types are tagged with `#[serde(skip)]`.

As of writing, this decision affects following Rust data types.
- `aws_smithy_http::byte_stream::ByteStream`
- `aws_smithy_http::event_stream::Receiver`
- `aws_smithy_http::event_stream::EventStreamSender`
By skipping, corresponding field's value will be assigned the value generated by `Default` trait.

Here are some examples of data types affected by this decision:
- `aws_sdk_transcribestreaming::client::fluent_builders::StartMedicalStreamTranscription`
As of writing, `aws_smithy_http::byte_stream::ByteStream` is the only data type that is affected by this decision.

Here is an example of data types affected by this decision:
- `aws_sdk_s3::input::put_object_input::PutObjectInput`

We considered serializing them as bytes, however, it could take some time for a stream to reach the end, and the resulting serialized data may be too big for itself to fit into the ram.
Additionally, those data types are sometimes used to represent bi-directional data transfer, which is not serializable.

Here is an example of struct with a field that comes with custom serialization/de-serialization logic.
Here is an example snippet.
```rust
#[allow(missing_docs)]
#[cfg_attr(
    all(aws-sdk-unstable, feature = "serialize"),
    all(aws-sdk-unstable, feature = "serde-serialize"),
    derive(serde::Serialize)
)]
#[cfg_attr(
    all(aws-sdk-unstable, feature = "deserialize"),
    all(aws-sdk-unstable, feature = "serde-deserialize"),
    derive(serde::Deserialize)
)]
#[non_exhaustive]
#[derive(std::fmt::Debug)]
pub struct ExampleStreamTranscriptionOutput {
    #[cfg_attr(
        any(
            all(aws-sdk-unstable, feature = "deserialize"),
            all(aws-sdk-unstable, feature = "serialize")
        ),
        serde(
            skip,
            default = "aws_smithy_http::event_stream::Receiver::deserialized_receiver"
        )
    )]
    pub transcript_result_stream: aws_smithy_http::event_stream::Receiver<
        crate::model::ExampleTranscriptResultStream,
        crate::error::ExampleTranscriptResultStreamError,
    >
pub struct PutObjectInput {
    pub acl: std::option::Option<crate::model::ObjectCannedAcl>,
    pub body: aws_smithy_http::byte_stream::ByteStream,
    // ... other fields
}
```

## Data types to exclude from ser/de code generation
For data types that include `@streaming union` in any of their fields, we do NOT implement `serde` traits.

As of writing, following Rust data types corresponds to `@streaming union`.
- `aws_smithy_http::event_stream::Receiver`
- `aws_smithy_http::event_stream::EventStreamSender`

Here is an example of data type affected by this decision;
- `aws_sdk_transcribestreaming::client::fluent_builders::StartMedicalStreamTranscription`

We considered skipping relevant fields on serialization and creating a custom de-serialization function which creates event stream that will always result in error when a user tries to send/receive data.
However, we believe that our decision is justified for following reason.
- All for operations that feature event streams since the stream is ephemeral (tied to the HTTP connection), and is effectively unusable after serialization and deserialization
- Most event stream operations don't have fields that go along with them, making the stream the sole component in them, which makes ser/de not so useful
- SDK that uses event stream, such as `aws-sdk-transcribestreaming` only has just over 5000 all-time downloads with recent downloads of just under 1000 as of writing (2023/01/21); It makes it difficult to justify since the implementation impacts smaller number of people.


## `Serde` traits implemented on Builder of Output Types
Output data, such as `aws_sdk_dynamodb::output::UpdateTableOutput` has builder types.
These builder types are available to users, however, no API requires users to build data types by themselves.