Wire formats and message layout¶
Where an event goes¶
Publish writes the event with Settings.Format, as an envelope.Wire, onto an AMQP message:
| AMQP | Content |
|---|---|
content_type property |
the wire's content type |
| headers table | each of the wire's headers, as a string; a header with several values is written as its first value |
| body | the wire's body |
delivery_mode |
2, persistent |
message_id |
hex SHA-256 of the event's Source, a NUL byte and its ID |
| routing key | the subject |
On receipt the adapter builds a wire from the message's content_type, the headers table's string
entries and the body, and asks the chain in Settings.Reads to read it. The routing key becomes
Delivery.Subject. Entries that are not strings are not offered to a format, so the broker's
x-delivery-count and x-death never reach one, and neither does any other non-string header.
The four formats in the suite¶
| Name in the suite | Format |
Reads |
Writes |
|---|---|---|---|
binary |
unset | unset | CloudEvents binary. Attributes in ce- headers (ce-id, ce-source and the rest); datacontenttype in the content_type property; the data as the body. |
structured |
cloudevents.Structured() |
unset | CloudEvents structured. content_type is application/cloudevents+json; every attribute is in the JSON body. |
masstransit |
masstransit.MassTransit() |
the defaults and masstransit.MassTransit() |
MassTransit's JSON envelope; content_type is application/vnd.masstransit+json. |
nservicebus |
nservicebus.NServiceBus() |
the defaults and nservicebus.NServiceBus() |
NServiceBus's own headers in the table, and the payload's type on content_type. |
The CloudEvents formats are from gitlab.com/phpboyscout/go/envelope-cloudevents. No CloudEvents
binding covers AMQP 0-9-1, so binary uses the HTTP binding's ce- prefix, which is what the module
wrote before formats existed. The MassTransit and NServiceBus formats are from
gitlab.com/phpboyscout/go/envelope-masstransit and gitlab.com/phpboyscout/go/envelope-nservicebus;
their rules, such as MassTransit's refusal of a non-UUID ID and of a payload that is not JSON, are on
their packages. go/envelope documents all of them.
The suite is not format-aware. It runs once per row of this table, each on its own exchange and
queue prefix. The binary run proves the default. The interop formats read behind the default chain,
so their runs also prove that the formats tell each other apart. Separate tests check that what goes
out is claimed by the writer's format and by no other.
Any other envelope.Format can be set. The suite does not run under it.
Reading¶
- The default chain is CloudEvents binary then structured. Exactly one format must claim a message.
- A string header no format takes reaches a handler through
Delivery.Foreign(). It is never sent on. - A message no format can read never reaches a handler; see What happens to a message nothing can read.
Size¶
The properties, which are content_type, message_id and every header, travel in the content header
frame. Publish refuses an event whose encoded properties plus 22 bytes of frame overhead exceed the
negotiated frame size. It estimates each header as 1 + len(name) + 1 + 4 bytes plus the length of a
string value, and the properties as len(content_type) + len(message_id) + 4. A frame size of zero
skips the check. The body is limited by the broker's max_message_size, which the adapter does not
check.