Wire protocol
Wire-format detail for AI Transport over Ably channels: the fields AI Transport writes on each message, and how a streamed response is laid out on the channel.
AI Transport writes ordinary Ably messages to the conversation's Ably channel. Any Ably client can read them, and the fields below are what AI Transport puts on them. The codec owns a message's name, data and most of its extras. The adaptor adds a small number of fields of its own.
Extras fields
Ably accepts only known keys at the top level of a message's extras. AI Transport uses three:
| Key | Written by | Contents |
|---|---|---|
extras.ai | The codec builder and the adaptor | The SDK's own fields. Ably reserves this key for AI Transport, and a value under it travels as it is, nested objects included. |
extras.headers | The codec and the caller | Flat headers, which Ably's server-side filtering reads. Values must be strings, numbers, booleans or null. |
extras.ephemeral | The codec builder | true when a codec row marks the message ephemeral. Ably delivers it to subscribed clients and keeps it out of history. |
Under extras.ai, a codec built with defineCodec writes three fields, and the adaptor writes two more:
| Field | Written by | Meaning |
|---|---|---|
type | Codec builder | The event type, which picks the codec row on decode. |
fields | Codec builder | The row's event fields that travel beside data, nested values included. |
codec | Codec builder | The codec's id, on every message the codec encodes. |
stream | Adaptor | true on every write under a live stream key: the publish that opens the stream, each append, and each update. |
ends | Adaptor | On the message that ends a stream, the serial of the stream's message. |
Every message also carries the codec's name as its message name. A decoder passes a message to its codec only when the message has both the codec's name and its id under extras.ai.codec.
A codec written by hand must also write its name and id, and can put its own fields anywhere Ably allows. The adaptor's two fields are the only ones it writes under extras.ai.
Call headers
send() and pipe() take headers, which the adaptor adds under extras.headers on every message the call publishes. A codec row can write headers there too. Where both set a key, the row's value is used. The adaptor also takes default headers for every message it publishes, and a call's value is used over a default. A subscriber reads the merged map from delivery.message.extras.headers.
The codecs that ship with the SDK write no headers of their own, so extras.headers holds only the call's headers and the adaptor's defaults. A common use is a requestId that ties a response to the prompt it answers.
Plain and streamed messages
A codec row says where each message goes:
- A plain publish has no key. It is one Ably message that nothing appends to.
- A streamed message is opened under a key. The pipe publishes it for the stream's first delta, remembers its serial under the key, and appends each later delta's
datato it. Ably concatenates appendeddata, so the message'sdatais the stream's text so far. - The message that ends a stream is published after the stream's appends have been acknowledged, with
extras.ai.endsset to the serial of the stream's message.
Ably replaces a message's name and extras with those of the latest append. That is why a stream's first delta opens the message, rather than a separate start event: history then holds the start event, one message with the stream's whole text under the delta's type, and the end event, which decode the same way as the live sequence.
Read a streamed message back
A streamed message reaches a client in one of three ways:
| How it arrives | data | Version |
|---|---|---|
| A live append | The appended fragment. | Each append has a new version.serial. |
| The first delivery after an attach | The full content so far, as a message.update. | The message's latest version.serial. |
| A history read | The whole message at its latest version. | The message's latest version.serial. |
The decoder core uses the message serial to identify the stream, and the version.serial to tell which deliveries it has already seen.
Channel options
Your application gets the channel with ably.channels.get(channelName) and sets its options, such as the channel modes. The adaptor and the decoder add no channel options, so your application can reuse the same channel for presence or LiveObjects.
Related pages
- Codec architecture: how a codec builds and reads these messages.
- Adaptor and decoder: how the pipe writes streams and the decoder reads them.
- Message appends: the Ably feature streamed messages use.