Skip to content

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:

  • foreign is 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.
  • format is the one that decoded the message. Write a reply in it, so a caller that wrote structured CloudEvents gets a structured CloudEvents answer.
  • err is ErrUnrecognised when no format claims the message and ErrAmbiguous when two do. Neither decodes, so e is empty for both. Every other refusal carries the partial event, as Decode'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.

w, err := writer.Encode(e)
if err != nil {
    return err
}

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.