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.