The Format seam¶
A format is a module that implements Format. The core defines the seam and nothing that crosses it.
type Format interface {
Encode(e Event) (Wire, error)
Recognises(w Wire) bool
Decode(w Wire) (Event, Foreign, error)
}
Format¶
| Method | Contract |
|---|---|
Encode |
Renders e. It validates first, so a format never emits an event Validate refuses. It may refuse an event that is valid but that its envelope cannot carry, with ErrUnrepresentable. |
Recognises |
Reports, without decoding, whether w is in this format. A claim, not a promise: a claimed message that fails to decode is malformed rather than somebody else's. |
Decode |
Reads w. It returns what it managed to read alongside any error, so a refused message can still be logged by its id, and returns whatever arrived that is not part of the event as Foreign. |
Wire¶
A message as a transport carries it. Only adapters build one.
| Field | Meaning |
|---|---|
ContentType |
The transport's own content type. AMQP and RabbitMQ carry it as a native property. On a transport without one the adapter writes it as the content-type header, and a format reads it from either place. |
Headers |
Everything else the transport carries beside the body. |
Body |
The body. |
Foreign¶
What arrived with an event but is not part of it: a broker's own headers, or a foreign envelope's fields with no CloudEvents equivalent. For reading. Nothing in this module sends it.
| Field | Meaning |
|---|---|
Headers |
The remainder, under the key it arrived with. |
Conflicts |
The keys an envelope set that the transport also carried with another value. The envelope's value is in the event; the transport's is in Headers. Only envelopes with fields headers can shadow produce one. |
Read¶
Decodes w with the one format that recognises it, and returns that format so a reply can be written
in it. Every format is asked, never the first that claims the message.
Formats that claim w |
Result |
|---|---|
| none | An empty event, no format, and ErrUnrecognised naming the content type and the formats asked |
| one | That format's Decode, with the event, the Foreign, the format and the error exactly as it returned them |
| two or more | An empty event, no format, and ErrAmbiguous naming the claimants |
A format is named in an error by its String method when it has one, and by its Go type otherwise.
The shipped formats are binary(ce-) and so on for CloudEvents, structured, masstransit and
nservicebus.
What each format claims¶
| Format | Claims a message when |
|---|---|
| CloudEvents binary | a header named specversion under the binding's prefix is present, in any case |
| CloudEvents structured | the content type, parsed as a media type, is application/cloudevents+json |
| MassTransit | the content type, parsed as a media type, is application/vnd.masstransit+json |
| NServiceBus | an NServiceBus.MessageId header is present with a value, in any case |
Each row is the format's own Recognises.