Interface IDeadLetterStore
- Namespace
- Excalibur.Dispatch.ErrorHandling
- Assembly
- Excalibur.Dispatch.Abstractions.dll
Defines the contract for storing and retrieving messages from the dead letter queue.
public interface IDeadLetterStore : IServiceProvider
- Inherited Members
- Extension Methods
Remarks
Tenancy. This interface is tenant-scoped: every operation addresses only entries belonging to the ambient tenant, and an entry stored under a different tenant is not visible through it. That guarantee matters here specifically because the entries carry MessageBody — the failed message content — so an estate-wide result discloses one tenant's message content to another.
Implementers must enforce this. The ambient tenant is supplied by the registered tenant context; a host that registers none operates entirely under the reserved untenanted partition, which is a concrete partition like any other rather than an absence of scoping. An implementation that ignores the ambient tenant satisfies the method signatures while breaking the contract, and no signature here can prevent that — which is why implementations are expected to demonstrate isolation against the provided conformance suite rather than assert it.
The scoping applies to writes and deletes as well as reads: a caller must not be able to mark replayed, delete, or purge an entry belonging to another tenant. Scoping only the read paths turns a disclosure into silent data loss rather than removing the problem.
Optional capabilities are discovered through GetService(Type),
never by casting the store. A store answers for the capability interfaces it implements and
returns null for the rest. A decorator answers for what it adds and defers everything
else to the store it wraps, so decoration cannot silently drop a capability the underlying store has.
Casting (store is IDeadLetterStoreAdmin) sees only the outermost type and is therefore lossy
through any decorator; it must not be used.
The obligation above is enforced at registration, not merely written here. The TenantOwnedAttribute below is the declaration point: a host composing row-discriminator multi-tenancy refuses to start unless the registered provider presents a tenancy capability marker, and that marker is emitted only by the registration seam that supplies the store its ITenantContext — never registered beside it. A store built without the ambient tenant therefore cannot carry a marker attesting that it applies one. A consumer-supplied store that ignores the ambient tenant is refused at startup instead of returning another tenant's message bodies at runtime.
Methods
DeleteAsync(string, CancellationToken)
Deletes a dead letter message.
Task<bool> DeleteAsync(string messageId, CancellationToken cancellationToken)
Parameters
messageIdstringThe ID of the message to delete.
cancellationTokenCancellationTokenThe cancellation token.
Returns
GetByIdAsync(string, CancellationToken)
Retrieves a dead letter message by its ID.
Task<DeadLetterMessage?> GetByIdAsync(string messageId, CancellationToken cancellationToken)
Parameters
messageIdstringThe ID of the message to retrieve.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<DeadLetterMessage>
A task containing the dead letter message, or null if not found.
GetMessagesAsync(DeadLetterFilter, CancellationToken)
Retrieves dead letter messages based on filter criteria.
Task<IEnumerable<DeadLetterMessage>> GetMessagesAsync(DeadLetterFilter filter, CancellationToken cancellationToken)
Parameters
filterDeadLetterFilterThe filter criteria for retrieving messages.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<IEnumerable<DeadLetterMessage>>
A task containing the collection of matching dead letter messages.
MarkAsReplayedAsync(string, CancellationToken)
Claims a dead letter message for replay by marking it replayed, and reports whether this caller won the claim.
Task<DeadLetterReplayOutcome> MarkAsReplayedAsync(string messageId, CancellationToken cancellationToken)
Parameters
messageIdstringThe ID of the message to claim.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<DeadLetterReplayOutcome>
Claimed when this caller moved the message from not-replayed to replayed and may now replay it; AlreadyReplayed when it was already marked; MessageNotFound when no such message exists in the caller's tenant.
Remarks
Implementations MUST make this a conditional write whose row count is the decision — the not-replayed condition belongs in the statement, not in a prior read. A read-then-write, however carefully guarded, lets two callers both observe an unmarked message and both proceed.
Callers claim BEFORE the replay, never after it, and release the claim with ReleaseReplayClaimAsync(string, CancellationToken) when the replay does not succeed. Marking after the dispatch makes the flag a record of a replay rather than a claim on one, which is what leaves the duplicate window open.
This is not idempotent and must not be, which is a deliberate reversal. Calling it twice returns Claimed then AlreadyReplayed; a second call that reported success would make the claim worthless. Absence of a throw is not the contract — the returned outcome is.
ReleaseReplayClaimAsync(string, CancellationToken)
Returns a claimed message to the not-replayed state, so a replay that did not succeed can be attempted again.
Task ReleaseReplayClaimAsync(string messageId, CancellationToken cancellationToken)
Parameters
messageIdstringThe ID of the message whose claim is being released.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task
A task representing the asynchronous operation.
Remarks
Without this, claiming before the replay would silently remove a behaviour consumers have. A replay whose dispatch fails must stay replayable; a claim that is never released would mark it replayed although nothing was delivered, and the row would then be indistinguishable from a replay that succeeded.
The residual exposure is a process ending between a failed replay and this release, which leaves one message marked replayed that was never delivered. That is bounded at one and the state converges; the ordering it replaces was unbounded, re-delivering on every subsequent attempt. No claim identity is needed to make the release safe, because the caller releasing it is the only one that holds it.
Releasing a message that is not marked, or that does not exist, is a no-op rather than an error.
StoreAsync(DeadLetterMessage, CancellationToken)
Stores a message in the dead letter queue.
Task StoreAsync(DeadLetterMessage message, CancellationToken cancellationToken)
Parameters
messageDeadLetterMessageThe dead letter message to store.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task
A task representing the asynchronous operation.