Skip to content

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.