What happens to an unreadable message¶
A message arrives from a producer that is not this bus, in a shape this bus does not read. The adapter
reads every received message through the Reads chain with envelope.Read. A message is unreadable
when envelope.Read refuses it, which covers three cases:
- Unclaimed: no format in the chain claims it.
- Ambiguous: two formats both claim it. The reader refuses to guess between them.
- Malformed: a format claims it and cannot decode it.
An unreadable message never becomes a Delivery, so no handler sees it. The adapter counts it in
SourceStats.Unreadable, once per attempt, and logs it at warn. It is not counted in Accepted,
Exhausted or Refused, because the bus never offered it. The design is
spec 0015,
and the core's side of the contract is in the backend contract.
Core: dropped¶
Core NATS delivers at most once and keeps nothing, so the adapter drops the message. The warning reads
messaging-nats: a message on the subject could not be read, with the attributes subscription,
subject and error.
If the unreadable message was a request, no reply is sent, and the requester waits until its own deadline.
JetStream: declined at once¶
The adapter declines the message with Nak straight away, which is the call a declined delivery gets.
It spends the message's attempts quickly, with no delay between them, and the server stops offering it
after MaxDeliver. The warning reads messaging-nats: a message on the stream could not be read, with
the same attributes, once for each attempt.
Three details:
- The last attempt is not
Exhausted. The message was never offered, so it sits outside every identity. TheNakon the last attempt is the same call, and the server simply stops. - The message stays in the stream. The adapter does not delete it or move it. Retention is the stream's.
- A failed
Nakis logged, not retried. The warning readsmessaging-nats: declining a message that could not be read failed, and the server offers the message again afterAckWait.
A message pulled while the source is retiring is held and declined only after the drain has finished,
because a Nak while a pull request is outstanding is a redelivery straight back into the same
iterator. It is still not counted Exhausted.
What it costs¶
Every unreadable message spends its consumer's attempts, one Nak after another. A stream with a
producer writing a shape this bus does not read therefore keeps the consumer busy with that producer's
messages until each has run out of attempts. Find unreadable messages
says how to see it.
Source: (*source).handle in source.go; read, decline, pull and returnDrained in
jetsource.go; the tests TestAMessageNoFormatCanReadIsCountedUnreadable and
TestAnUnreadableMessageDrainedAtRetirementIsNotExhausted.