Skip to content

Wire format

Source: format.go. The event is go/envelope's, and a format is an envelope.Format. This page is the AMQP mapping; each format's own rules are on its package.

What a publish writes

The format encodes the event to headers, a content type and a body. The backend places them:

AMQP field Value
header durable true
property message-id hex SHA-256 of the event's Source, a zero byte, and its ID
property to the subject's address
property content-type the format's content type, if it has one
application properties the format's headers, first value of each only, as strings
application property _AMQ_DUPL_ID the same hash as message-id, when Features.Deduplicates is true (always, on Artemis)
body one data section holding the format's body

Publish then waits for the broker's disposition. Accepted returns nil; any other disposition is an error.

Duplicates are dropped by the broker

_AMQ_DUPL_ID keys Artemis's duplicate-id cache. A second publish of an event with the same Source and ID is accepted by the broker and not enqueued, and Publish returns nil. This was observed across a broker restart: the cache is persistent. An ID that repeats within a Source therefore never reaches a subscriber a second time.

What a read accepts

From the message Used as
application properties whose value is a string the headers. Other value types are ignored.
property content-type the content type
data sections the body: one section as is, several concatenated
property to the delivery's subject; the subscription's Pattern if to is absent

A message whose body is an amqp-value or amqp-sequence section has an empty body, because only data sections are read.

The message is read with the Reads chain by envelope.Read, and exactly one format must claim it. A message that none claims, that two claim, or that one claims and cannot decode is unreadable: see Delivery, settlement and flow control.

String application properties that no format takes reach the handler through Delivery.Foreign(), a tracing header or Artemis's own _AMQ_DUPL_ID among them. They are never sent on.

The four formats the suite runs under

Settings.Format chooses the writer. Settings.Reads chooses the chain. Unset, the writer is CloudEvents binary and the chain is binary then structured.

Format Constructor On the wire
CloudEvents binary (default) cloudevents.Binary(cloudevents.AMQP) attributes as application properties under the cloudEvents_ prefix, and the payload's type on content-type. Reads the cloudEvents: prefix the binding also permits.
CloudEvents structured cloudevents.Structured() content-type is application/cloudevents+json and the attributes travel in the body.
MassTransit masstransit.MassTransit() content-type is application/vnd.masstransit+json. Refuses at publish an ID that is not a UUID and a payload that is not JSON.
NServiceBus nservicebus.NServiceBus() NServiceBus's headers as application properties, the payload's type on content-type.

The CloudEvents formats are from gitlab.com/phpboyscout/go/envelope-cloudevents, MassTransit's from go/envelope-masstransit and NServiceBus's from go/envelope-nservicebus. All three are v0.1.0 in the module's go.mod. The conformance suite runs once under each of the four. The MassTransit and NServiceBus runs read with [binary, structured, <that format>], so they also prove the formats tell each other apart.

A fifth format would have to be added to Reads and, to write it, Format; it has not been run through the suite.

Moving a deployment between formats

A consumer can read structured before any producer writes it. Upgrade the readers first, with Reads including the new format, and switch the writers after. See Choose a wire format.