Why Read asks every format¶
envelope.Read is not a loop that stops at the first format whose Recognises says yes. It asks all
of them, and decodes only when exactly one claims the message.
No order is safe¶
Two messages defeat every ordering of CloudEvents' own two formats:
- A structured message with a stray
ce-specversionheader is claimed by both. Binary first misreads it as a malformed binary event. - A binary event whose payload is itself a structured CloudEvent is claimed by both. Structured first misreads it as the inner event.
Neither misreading errors. Each hands the caller a well-formed event that is the wrong one. A priority order moves the failure from one message to the other and hides it in both.
So a message two formats claim is ErrAmbiguous, naming the
formats, and is decoded with neither. The interop formats raise the same case: a MassTransit
envelope that also carries a ce-specversion header is claimed by binary CloudEvents and by
MassTransit.
Recognising is a claim, not a promise¶
Recognises answers "is this mine?" without decoding. It is deliberately narrow: binary CloudEvents
looks for a specversion header under its prefix, structured for the content type
application/cloudevents+json, MassTransit for application/vnd.masstransit+json, and NServiceBus
for an NServiceBus.MessageId header. A claimed message that then fails to decode is malformed, and
says so, rather than falling through to a format that might accept it.
That keeps "not in any format this reader was given" apart from "in a format, and broken". The first
is ErrUnrecognised, and the remedy is a missing format in
the chain. The second is the claiming format's own refusal, and the remedy is the producer.
The cost¶
A strict chain asks every format, so it costs more than a direct decode. It is the price of never choosing silently between two answers. The design record measured 25 to 80 percent over a direct decode, which it puts at microseconds.
The design is go/messaging spec 0014, OQ2.