Skip to content

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

type Wire struct {
    ContentType string
    Headers     map[string][]string
    Body        []byte
}

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

type Foreign struct {
    Headers   map[string][]string
    Conflicts []string
}

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

func Read(w Wire, formats ...Format) (Event, Foreign, Format, error)

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.