From 328c7d317886e6e3170da3fd29d37823ca1b9a67 Mon Sep 17 00:00:00 2001 From: JordonPhillips Date: Thu, 6 Feb 2025 17:26:48 +0100 Subject: [PATCH] Add public docs for the amazon event stream format This adds documentation for the `application/vnd.amazon.eventstream` wire format as well as the common protocol semanitcs that are layered on top of it. It does NOT provide tests. Event stream protocol tests are in the works, but are not yet available. --- .../protocols/smithy-rpc-v2.rst | 2 + .../aws/amazon-eventstream-frame-diagram.png | Bin 0 -> 23717 bytes docs/source-2.0/aws/amazon-eventstream.rst | 506 ++++++++++++++++++ docs/source-2.0/aws/index.rst | 1 + .../aws/protocols/aws-json-1_0-protocol.rst | 2 + .../aws/protocols/aws-json-1_1-protocol.rst | 2 + .../aws/protocols/aws-restjson1-protocol.rst | 2 + .../aws/protocols/aws-restxml-protocol.rst | 2 + 8 files changed, 517 insertions(+) create mode 100644 docs/source-2.0/aws/amazon-eventstream-frame-diagram.png create mode 100644 docs/source-2.0/aws/amazon-eventstream.rst diff --git a/docs/source-2.0/additional-specs/protocols/smithy-rpc-v2.rst b/docs/source-2.0/additional-specs/protocols/smithy-rpc-v2.rst index 315589b401f..462b1ee9d89 100644 --- a/docs/source-2.0/additional-specs/protocols/smithy-rpc-v2.rst +++ b/docs/source-2.0/additional-specs/protocols/smithy-rpc-v2.rst @@ -53,6 +53,8 @@ list they understand when connecting to a service. A client SHOULD assume that a service supports ``http/1.1`` when no ``http`` or ``eventStreamHttp`` values are provided. +Event streaming uses the :ref:`amazon-eventstream` format. + The following example defines a service that uses ``smithy.protocols#rpcv2Cbor``. diff --git a/docs/source-2.0/aws/amazon-eventstream-frame-diagram.png b/docs/source-2.0/aws/amazon-eventstream-frame-diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..5217c2a472e1d25917d13da118f5d623db0c9229 GIT binary patch literal 23717 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 encoding, a generic data encoding designed +to support bidirectional datagram-oriented communication on top of an existing, +reliable, stream-oriented protocol. This is the encoding used by AWS services, +regardless of protocol. + +The encoding provides several capabilities: + +* Message framing and delineation, so that discrete datagrams can be transmitted + over a stream-oriented protocol. +* Comprehensive integrity checks, ensuring that corruption can always be + recognized and handled immediately. +* Extensible message metadata. +* Efficient binary framing and encoding. + +The encoding does NOT provide the following capabilities, though it could be +extended to support them: + +* Message fragmentation, or streaming a single payload as multiple messages. +* Relaying events over an unordered, unreliable transport such as UDP. + +The :rfc:`media type <6838>` for this format is +``application/vnd.amazon.eventstream``. + +.. _amazon-eventstream-wire-format: + +----------- +Wire Format +----------- + +The wire format is structured as a sequence of binary messages. This +specification adopts the presentation language of +:rfc:`RFC 5246 section 4 <5246#section-4>` to describe the format of these +messages. This language is a type of psuedocode similar to C used to define +serialized binary representations of messages. Note that all integer types are +in network byte order, or big-endian. + +.. _amazon-eventstream-message-format: + +Message Format +============== + +The wire format is structured as a sequence of messages. Messages consist of two +sections: the prelude and the data. The prelude section contains a four-byte +unsigned integer representing the total length of the message and a four-byte +unsigned integer representing the total length of the message's headers. The +data section consists of the :ref:`headers ` +followed by a payload. + +Both sections end with a four-byte unsigned integer representing a +:rfc:`CRC32 <3385>` checksum, which is the checksum of all the data from the +start of the message to the start of the checksum. Both clients and servers MUST +validate these checksums. If either checksum is invalid, the stream MUST be +terminated. + +.. code-block:: text + + struct { + uint32 total_length; + uint32 headers_length; + uint32 prelude_crc; + + byte headers[headers_length]; + byte payload[total_length - headers_length - sizeof(total_length) - sizeof(headers_length) - sizeof(prelude_crc) - sizeof(message_crc)]; + uint32 message_crc; + } Message; + +Additionally, the message has the following size restrictions: + +* The payload of a message MUST NOT exceed 25,165,824 bytes (24 MB). +* The encoded headers of a message MUST NOT exceed 131,072 bytes (128 kB). Note + that the in-memory representation of the headers, once decoded, may legally + exceed this value. + +Services MUST validate these additional size restrictions. Clients MUST NOT +validate them. + +.. _amazon-eventstream-headers-format: + +Headers Format +============== + +Headers are used to annotate a message with arbitrary metadata, such as +timestamps, message type information, additional payload checksums, and so on. +Headers are key-value pairs where the key is a UTF-8 string and the value is one +of several possible data types. Note that this is distinct from HTTP headers, +whose values are always bytes (usually UTF-8 encoded strings). Any given header +name MUST only appear once in a message. + +On the wire, each header begins with a one-byte unsigned integer that indicates +the number of UTF-8 encoded bytes used by the header's name. Header names MUST +be at least one byte long. This length prefix is followed by the UTF-8 header +name. + +The name of the header is followed by a one-byte unsigned integer indicating +the header's data type. The set of types is fixed and not open to extension. +Implementations SHOULD bind header types to the corresponding types in their +programming language. The following table shows the available types and their +indicators. + +.. list-table:: + :header-rows: 1 + :widths: 10 20 70 + + * - Indicator + - Data Type + - Description + * - ``0`` + - Boolean ``true`` + - No value bytes follow this type. + * - ``1`` + - Boolean ``false`` + - No value bytes follow this type. + * - ``2`` + - ``byte`` + - + * - ``3`` + - ``short`` + - + * - ``4`` + - ``integer`` + - + * - ``5`` + - ``long`` + - + * - ``6`` + - ``byte_array`` + - This corresponds to Smithy's :ref:`blob ` type. The value is + prefixed by a two-byte unsigned integer that indicates the length in + bytes of the following value. + * - ``7`` + - ``string`` + - The value is prefixed by a two-byte unsigned integer that indicates the + length in bytes of the following value. + * - ``8`` + - ``timestamp`` + - The value is an 8-byte unsigned integer representing the number of + **milliseconds** that have elapsed since 00:00:00 Coordinated Universal + Time (UTC), Thursday, 1 January 1970. + + .. warning:: + The unit of this value is **milliseconds**, NOT seconds. This is + unlike the ``epoch-seconds`` + :ref:`timestamp format `, which is in + **seconds**. + * - ``9`` + - ``uuid`` + - An :rfc:`9562` UUID in binary format. + +.. code-block:: text + + struct { + struct { + utf8 name<1..255>; + } header_name; + HeaderValueType type; + HeaderValue header_value; + } Header; + + enum { + boolean_true(0), + boolean_false(1), + byte(2), + short(3), + integer(4), + long(5), + byte_array(6), + string(7), + timestamp(8), + uuid(9) + } HeaderValueType; + + struct { + select (HeaderValueType) { + case boolean_true: + case boolean_false: + struct {}; + case byte: + int8 value; + case short: + int16 value; + case integer: + int32 value; + case long: + int64 value; + case byte_array: + byte data<1..2^15-1>; + case string: + utf8 data<1..2^15-1>; + case timestamp: + int64 millis_since_epoch; + case uuid: + byte value[16]; + } value; + } HeaderValue; + +An event MAY have any number of headers. The order in which headers are encoded +is meaningless; implementations MAY NOT preserve header order across encoding or +decoding. + +Diagram +======= + +The following diagram shows the components that make up a message and a header. +The header depicted in this diagram is a string header; other header types have +different value layouts. + +.. image:: ./amazon-eventstream-frame-diagram.png + :width: 714 + :alt: A schematic of the components of an event with a string header. + +.. _amazon-eventstream-semantics: + +---------------------- +Amazon Event Semantics +---------------------- + +The ``application/vnd.amazon.eventstream`` wire format is a generic encoding. +There are additional semantic requirements when using this format with AWS +protocols. Events are categorized into one of five categories: message events, +modeled error events, unmodeled error events, initial request events, and +initial response events. Each event category has its own semantic requirements. + +Message Events +============== + +The set of modeled events that may be sent over an event stream are defined by a +union with the :ref:`@streaming trait `, where each member of the +union is a different type of event. Message events are events that represent an +event union member whose target does not have the +:ref:`error trait `. All message events share the following +headers: + +.. list-table:: + :header-rows: 1 + :widths: 20 10 70 + + * - Key + - Type + - Description + * - ``:message-type`` + - string + - **Required**. The value of this header MUST always be ``event``. + * - ``:event-type`` + - string + - **Required**. The value of this header is the name of the member that + targets the event shape. + * - ``:content-type`` + - string + - The value of this header is the :rfc:`media type <6838>` of the + payload. This value follows the rules of the particular service + protocol being used. For example, a JSON payload MAY use a + ``:content-type`` of ``application/json``. + +For example, take the following model that depicts an event stream bound to a +service with a JSON-based protocol: + +.. code-block:: smithy + + @streaming + union ExampleEventStream { + structure: StructureEvent + string: StringEvent + blob: BlobEvent + headersOnly: HeadersOnlyEvent + } + + structure StructureEvent { + foo: String + } + + structure StringEvent { + @eventPayload + payload: String + } + + structure BlobEvent { + @eventPayload + payload: Blob + } + + structure HeadersOnlyEvent { + @eventHeader + sequenceNum: Integer + } + +The different events of this event stream would be serialized as shown below. +Note that these samples are in a human-readable format rather than the encoded +wire format. In particular, note that the binary payload of the third event is +represented here in base64 encoding even though on the wire it would not be +base64 encoded. Each event is delineated by a long line. + +.. code-block:: text + + ------------------------------------------------------------------------------- + :message-type: event + :event-type: structure + :content-type: application/json + + {"foo":"bar"} + ------------------------------------------------------------------------------- + :message-type: event + :event-type: string + :content-type: text/plain + + Arbitrary text + ------------------------------------------------------------------------------- + :message-type: event + :event-type: blob + :content-type: application/octet-stream + + IkFyYml0cmFyeSBiaW5hcnkiCg== + ------------------------------------------------------------------------------- + :message-type: event + :event-type: headersOnly + sequenceNum: 4 + +Modeled Error Events +==================== + +Modeled error events are events that represent an event union member whose +target has the :ref:`error trait `. All modeled error events share +the following headers: + +.. list-table:: + :header-rows: 1 + :widths: 20 10 70 + + * - Key + - Type + - Description + * - ``:message-type`` + - string + - **Required**. The value of this header MUST always be ``exception``. + * - ``:exception-type`` + - string + - **Required**. The value of this header is the name of the member that + targets the error shape. + * - ``:content-type`` + - string + - The value of this header is the :rfc:`media type <6838>` of the + payload. This value follows the rules of the particular service + protocol being used. For example, a JSON payload MAY use a + ``:content-type`` of ``application/json``. + +For example, take the following model that depicts an event stream bound to a +service with a JSON-based protocol: + +.. code-block:: smithy + + @streaming + union EventStreamWithError { + modeledError: MyError + } + + @error("client") + structure MyError { + message: String + } + +An event representing the ``modeledError`` event might look like: + +.. code-block:: text + + ------------------------------------------------------------------------------- + :message-type: exception + :exception-type: modeledError + :content-type: application/json + + {"message":"..."} + +Unmodeled Error Events +====================== + +In addition to modeled errors, servers MAY serialize unmodeled error events. +These generally represent unexpected errors. All unmodeled error events share +the following headers: + +.. list-table:: + :header-rows: 1 + :widths: 20 10 70 + + * - Key + - Type + - Description + * - ``:message-type`` + - string + - **Required**. The value of this header MUST always be ``error``. + * - ``:error-code`` + - string + - **Required**. The value of this header is a string containing the name, + type, or category of the error. + * - ``:error-message`` + - string + - **Required**. The value of this header is a human-readable error + message. + + +The following is an example unmodeled error: + +.. code-block:: text + + ------------------------------------------------------------------------------- + :message-type: error + :error-code: InternalError + :error-message: An internal server error occurred. + +Initial Message Events +====================== + +In REST protocols (:ref:`AWS restJson1 `, +:ref:`AWS restXml `), initial messages are bound to HTTP +requests and responses. Members of the input and output structures for services +using these protocols MUST NOT be bound to the HTTP body. They MAY be bound to +any other part of the HTTP message, such as the headers, URI, or query string. + +In RPC protocols (:ref:`AWS JSON 1.0 `, +:ref:`AWS JSON 1.1 `, +:ref:`Smithy RPC v2 CBOR `), initial messages take the form +of message events with the event types ``initial-request`` for request streams +and ``initial-response`` for response streams. Every member of the input or +output structure except for the event stream member MUST be serialized into the +event payload. + +The following example is a simplified excerpt from the Amazon Kinesis model for +the operation ``GetRecordStream``. This service uses the +:ref:`AWS JSON 1.1 ` protocol. + +.. code-block:: smithy + + operation GetRecordStream { + input := { + ShardIterator: String + } + output := { + streamLifetimeInMinutes: Integer + payload: GetRecordsEventStream + } + } + + @streaming + union GetRecordsEventStream { + recordsListEvent: RecordsListEvent + } + + structure RecordsListEvent { + @eventPayload + payload: GetRecordsOutput + } + +This operation is a simplex (uni-directional) stream. The request therefore is +no different than a conventional HTTP RPC request: + +.. code-block:: http + + POST / HTTP/1.1 + Host: kinesis.us-west-2.amazonaws.com + User-Agent: + Content-Type: application/x-amz-json-1.1 + Authorization: + Connection: Keep-Alive + X-Amz-Date: + X-Amz-Target: Kinesis_20131202.GetRecordStream + Content-Length: 224 + + {"ShardIterator":"..."} + +The response is an event stream, so it begins with an ``initial-response`` +event: + +.. code-block:: http + + HTTP/1.1 200 OK + x-amzn-RequestId: + Content-Type: application/vnd.amazon.eventstream + Date: + + ------------------------------------------------------------------------------- + :message-type: event + :event-type: initial-response + :content-type: application/json + + {"streamLifetimeInMinutes":5} + ------------------------------------------------------------------------------- + :message-type: event + :event-type: recordsListEvent + :content-type: application/json + + { + "MillisBehindLatest": 2100, + "NextShardIterator": "...", + "Records": [ + { + "Data": "XzxkYXRhPl8w", + "PartitionKey": "partitionKey", + "ApproximateArrivalTimestamp": 1.441215410867E9, + "SequenceNumber": "21269319989652663814458848515492872193" + } + ] + } \ No newline at end of file diff --git a/docs/source-2.0/aws/index.rst b/docs/source-2.0/aws/index.rst index ae9e5711c94..53fbac1f13e 100644 --- a/docs/source-2.0/aws/index.rst +++ b/docs/source-2.0/aws/index.rst @@ -11,6 +11,7 @@ AWS integrations aws-iam amazon-apigateway aws-cloudformation + amazon-eventstream AWS Protocols ============= diff --git a/docs/source-2.0/aws/protocols/aws-json-1_0-protocol.rst b/docs/source-2.0/aws/protocols/aws-json-1_0-protocol.rst index 081c6ab261d..61d80d80b6d 100644 --- a/docs/source-2.0/aws/protocols/aws-json-1_0-protocol.rst +++ b/docs/source-2.0/aws/protocols/aws-json-1_0-protocol.rst @@ -52,6 +52,8 @@ list they understand when connecting to a service. A client SHOULD assume that a service supports ``http/1.1`` when no ``http`` or ``eventStreamHttp`` values are provided. +Event streaming uses the :ref:`amazon-eventstream` format. + The following example defines a service that uses ``aws.protocols#awsJson1_0``. .. code-block:: smithy diff --git a/docs/source-2.0/aws/protocols/aws-json-1_1-protocol.rst b/docs/source-2.0/aws/protocols/aws-json-1_1-protocol.rst index 04e657db1d3..7fbd7f66248 100644 --- a/docs/source-2.0/aws/protocols/aws-json-1_1-protocol.rst +++ b/docs/source-2.0/aws/protocols/aws-json-1_1-protocol.rst @@ -52,6 +52,8 @@ list they understand when connecting to a service. A client SHOULD assume that a service supports ``http/1.1`` when no ``http`` or ``eventStreamHttp`` values are provided. +Event streaming uses the :ref:`amazon-eventstream` format. + The following example defines a service that uses ``aws.protocols#awsJson1_1``. .. code-block:: smithy diff --git a/docs/source-2.0/aws/protocols/aws-restjson1-protocol.rst b/docs/source-2.0/aws/protocols/aws-restjson1-protocol.rst index 9ed49343d4a..04c44d79b23 100644 --- a/docs/source-2.0/aws/protocols/aws-restjson1-protocol.rst +++ b/docs/source-2.0/aws/protocols/aws-restjson1-protocol.rst @@ -54,6 +54,8 @@ list they understand when connecting to a service. A client SHOULD assume that a service supports ``http/1.1`` when no ``http`` or ``eventStreamHttp`` values are provided. +Event streaming uses the :ref:`amazon-eventstream` format. + The following example defines a service that uses ``aws.protocols#restJson1``. .. code-block:: smithy diff --git a/docs/source-2.0/aws/protocols/aws-restxml-protocol.rst b/docs/source-2.0/aws/protocols/aws-restxml-protocol.rst index 2ce6eaecf9d..b8bc57f6c46 100644 --- a/docs/source-2.0/aws/protocols/aws-restxml-protocol.rst +++ b/docs/source-2.0/aws/protocols/aws-restxml-protocol.rst @@ -55,6 +55,8 @@ list they understand when connecting to a service. A client SHOULD assume that a service supports ``http/1.1`` when no ``http`` or ``eventStreamHttp`` values are provided. +Event streaming uses the :ref:`amazon-eventstream` format. + The following example defines a service that uses ``aws.protocols#restXml``. .. code-block:: smithy