Table of Contents

Interface IFencedDeadLetterableOutboxStore

Namespace
Excalibur.Dispatch
Assembly
Excalibur.Dispatch.Abstractions.dll

An outbox store that can evaluate the leadership fence in the same atomic action that performs the terminal dead-letter transition.

public interface IFencedDeadLetterableOutboxStore
Extension Methods

Remarks

The authority overload compares both tenure and acquisition in the same atomic action as the terminal transition. The legacy token-only overload protects tenure only and cannot establish same-tenure claim ownership. Framework workers use the authority overload; no default implementation may discard it.

Methods

MarkDeadLetteredAsync(string, string, int, OutboxWriteAuthority, CancellationToken)

Dead-letters a message only while the caller holds both accepted tenure and current claim.

ValueTask<OutboxCompletionOutcome> MarkDeadLetteredAsync(string messageId, string reason, int attemptCount, OutboxWriteAuthority authority, CancellationToken cancellationToken)

Parameters

messageId string

The persisted message identifier captured at acquisition.

reason string

The reason for the terminal disposition.

attemptCount int

Nonnegative observed logical attempt count; applied writes retain its maximum.

authority OutboxWriteAuthority

The positive tenure and nonblank acquisition identity captured by the worker.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<OutboxCompletionOutcome>

The outcome decided atomically with the guarded terminal mutation.

Remarks

Validate arguments before mutation. For valid authority evaluate the fence before row outcomes; absent/different/released claims return ClaimLost, retained terminal rows AlreadyTerminal and absent rows MessageNotFound. Do not reconstruct outcomes from a later unguarded read.

MarkDeadLetteredAsync(string, string, int, long, CancellationToken)

Moves a message to the dead-letter destination, applying it only if the caller's tenure is still current.

ValueTask<OutboxCompletionOutcome> MarkDeadLetteredAsync(string messageId, string reason, int attemptCount, long fencingToken, CancellationToken cancellationToken)

Parameters

messageId string

The unique identifier of the message to dead-letter.

reason string

The reason recorded against the dead-lettered message.

attemptCount int

Observed logical delivery attempts. Nonnegative; an applied transition atomically records the maximum of this value and the stored count. Missing, terminal, and refused transitions do not change the count.

fencingToken long

The monotonic token identifying the caller's leadership tenure.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<OutboxCompletionOutcome>

What the store did, decided by the same atomic action that performed the transition.

Remarks

Implementations MUST evaluate the fence and the transition in ONE atomic action. On a store whose terminal idiom destroys the row, the transition is irreversible: there is no later read that can establish whether the caller was entitled to make it, because the evidence is what was deleted. A fence judged in a separate round trip leaves a window in which a successor advances the mark between the check and the delete.

The refusal is REPORTED, never thrown. The drains reach this member from inside their own exception handlers, where a sibling handler on the same block cannot run, so an exception raised here escapes the cycle and abandons every message the caller still holds. ClaimLost is not reachable from this member — it carries no claim term — and an implementation returning it would be reporting a decision it did not make.

Exceptions

ArgumentException

Thrown when messageId is null or empty.

ArgumentOutOfRangeException

Thrown before mutation when attemptCount is negative.