Skip to main content

Marking a message dead-lettered states its outcome

IDeadLetterableOutboxStore.MarkDeadLetteredAsync now returns an outcome instead of nothing:

// Before
ValueTask MarkDeadLetteredAsync(
string messageId, string reason, int attemptCount, CancellationToken cancellationToken);

// Now
ValueTask<OutboxCompletionOutcome> MarkDeadLetteredAsync(
string messageId, string reason, int attemptCount, CancellationToken cancellationToken);

This only affects you if you implement an outbox store. If you consume one — staging messages and letting the framework drain them — nothing in your code changes, and the behaviour you get is strictly better.

Why it changed​

The drain writes the dead-letter entry first and marks the outbox row second. Every store can refuse that second step: the row may be gone, it may already be sent or dead-lettered, or another drain may hold its lease. With a ValueTask return, "I refused" and "I applied it" were the same observation, so the processor reported success either way.

The consequence was not a lost error message. It was a message left simultaneously delivered and sitting unreplayed in the dead-letter queue — the live claimant goes on to deliver it, while the entry the drain already wrote stays pending. The shipped redrive path selects pending entries by filter, so an operator draining the queue re-executes a message that already succeeded, from the framework's own bookkeeping rather than any fault of theirs.

The fenced variant, IFencedDeadLetterableOutboxStore.MarkDeadLetteredAsync, already returned an outcome and already withdrew the entry on a refusal. The unfenced path — which is the default, used whenever leader election is not configured — could not, because it could not see the refusal. The two now behave the same way.

What stops compiling​

Only a custom IDeadLetterableOutboxStore. Return the verdict your implementation already computes:

public async ValueTask<OutboxCompletionOutcome> MarkDeadLetteredAsync(
string messageId, string reason, int attemptCount, CancellationToken cancellationToken)
{
var updated = await UpdateRowAsync(messageId, reason, attemptCount, cancellationToken);
return updated > 0
? OutboxCompletionOutcome.Applied
: OutboxCompletionOutcome.MessageNotFound;
}

A decorator must forward the value rather than await and discard it. A decorator that swallows the outcome reinstates the original defect for every host that installs it, and does so invisibly — the decorated path still compiles and still logs.

What to report​

outcomewhen
Appliedthe row was mutated — the only success value
MessageNotFoundno row matched the identifier
AlreadyTerminalthe row was already sent or already dead-lettered
ClaimLostthe store holds a delivery lease for a different owner
FenceRefusednot reachable here — this member carries no fencing token
Unknownnever return this deliberately; it exists so an unset value cannot read as success

Two rules the framework relies on:

Test for Applied by name, never by excluding the refusals. Deciding success by exclusion makes every member added to the enum later start life as a success, which is the direction this contract must not fail.

Report the refusal; do not throw it. The drain reaches this member from inside its own exception handling, where a sibling handler cannot catch — an exception raised here abandons every other message in the batch.

If your store cannot distinguish the refusals​

Report the weakest one that is true rather than guessing. The shipped Postgres and Oracle providers move the row into a dead-letter table in a single statement, so a completed dead-letter leaves nothing behind and "already terminal" is genuinely indistinguishable from "no such row"; both report MessageNotFound. That is honest, and the caller's handling is identical for every non-Applied value — it withdraws the entry either way. The distinction is for your operators, not for the framework's control flow.

MessageFailureKind gained an Uncertain member in the same release. An exhaustive switch over that enum in your own code will no longer compile — see the failure-kind note.