Read more than one format¶
This is for code that sits between an event and a transport, such as a messaging adapter. A service
that only ever reads one format can call that format's Decode directly.
Give Read the chain¶
Read asks every format whether it recognises the message and decodes with the one that does. Give it
every format the reader should accept:
readers := []envelope.Format{
cloudevents.Binary(cloudevents.NATS),
cloudevents.Structured(),
nservicebus.NServiceBus(),
}
e, foreign, format, err := envelope.Read(
envelope.Wire{ContentType: msg.ContentType, Headers: msg.Header, Body: msg.Data},
readers...,
)
if err != nil {
refused.Add(1)
logger.Error("refused a message", "id", e.ID, "source", e.Source, "err", err)
return
}
A reader that accepts a new format can be deployed before any writer switches to it, which is what makes the change safe.
Read returns three things beside the event:
foreignis everything on the wire that is not part of the event, such as a broker's own headers. See Read what arrived with an event.formatis the one that decoded the message. Write a reply in it, so a caller that wrote structured CloudEvents gets a structured CloudEvents answer.errisErrUnrecognisedwhen no format claims the message andErrAmbiguouswhen two do. Neither decodes, soeis empty for both. Every other refusal carries the partial event, asDecode's do.
Do not order the formats to break a tie¶
It is tempting to treat the list as a priority order and take the first format that claims a
message. No order works: a structured-mode CloudEvent carrying a stray ce-specversion header is
misread as malformed binary when binary goes first, and a binary event whose payload is itself a
structured CloudEvent is misread as the inner event when structured goes first. That is why Read
refuses a message two formats claim rather than choosing. The reasoning is in
Why Read asks every format.
Write in one format¶
Writing is not a chain: give the transport the one Format it should publish with, and put what
Encode returns where the transport keeps it.
Encode validates first and returns the format's own refusals, such as
ErrUnrepresentable, to the publisher rather than losing
the message. Each adapter section says what its format refuses.
With a go/messaging adapter¶
An adapter that supports formats takes a writer and a chain. go/messaging-rabbitmq's Settings, for
example, has Format, the one format every event is published with, and Reads, the chain every
received message is read with:
rabbitmq.New(rabbitmq.Settings{
URL: url, Exchange: "events",
Format: cloudevents.Structured(),
Reads: []envelope.Format{cloudevents.Binary(cloudevents.HTTP), cloudevents.Structured()},
})
Left unset, Format is CloudEvents binary with the ce- prefix and Reads is binary then
structured. The adapter's own README is the authority on its defaults.