Table of Contents

Interface IDeadLetterQueue

Namespace
Excalibur.Dispatch.ErrorHandling
Assembly
Excalibur.Dispatch.dll

Defines the contract for a dead letter queue that stores failed messages for later inspection and replay.

[SuppressMessage("Naming", "CA1711:Identifiers should not have incorrect suffix", Justification = "DeadLetterQueue is a standard industry term in messaging systems")]
public interface IDeadLetterQueue
Extension Methods

Remarks

The dead letter queue is used to capture messages that cannot be processed after exhausting all retry attempts. It provides capabilities for:

  • Storing failed messages with full exception context
  • Retrieving entries for inspection and debugging
  • Replaying messages for reprocessing
  • Purging old or resolved entries

Tenancy — this interface is tenant-scoped. Its operations address only entries belonging to the ambient tenant; an entry stored under a different tenant is not visible through it. That guarantee matters here more than on most contracts because the entries returned include the failed message body, so an estate-wide result would disclose one tenant's message content to another.

A host that establishes no tenant operates on the untenanted partition, which is a real partition holding the entries that carry no tenant — not a wildcard. Forgetting to establish a tenant therefore narrows what a caller can see rather than widening it.

Estate-wide inspection, replay, and purge are the operator capability and live on IDeadLetterQueueAdmin, where each one says so in its name. Note that a separate interface is not by itself a separate capability: the shipped provider registers both interfaces against one instance, so a host that resolves the admin interface has granted estate-wide reach to whatever holds it.

The originating tenant is retained in storage and used to scope these operations and to restore the correct tenant when an entry is replayed. It is not projected onto DeadLetterEntry, so callers cannot read an entry's tenant from the returned value and must not rely on doing so.

Two properties, not one: tenant scope governs which entries a caller may address; the tenant a replayed message re-enters is always the tenant it was stored under. An entry stored without a tenant re-enters untenanted — never as the caller's ambient tenant.

Effects — a value the caller supplies is the value a reader gets back. Whatever a caller hands to EnqueueAsync<T>(T, DeadLetterReason, CancellationToken, Exception?, IDictionary<string, string>?) is what a subsequent read of that entry reports. This is stated as an effect and not as a schema: how an implementation stores a value is its own business, and what it owes is that a read agrees with the write.

Two consequences follow, and both are correct outcomes rather than loopholes. The clause binds only what the caller supplies, so an implementation is never obliged to invent provenance it was not given. And it says nothing about retention, so a discarding implementation satisfies it vacuously because nothing is ever read back from it.

Every filter axis this contract exposes is a promise that the underlying value varies. An implementation that pins a filtered value to a constant turns a caller's query into a confident wrong answer with nothing to show for it, because an empty result is indistinguishable from "there are none". Two entries that must fall on opposite sides of any exposed filter are required to be separated by it.

Failure — the operation may fail with an implementation-specific exception, and a caller must treat any failure as "not enqueued". This contract deliberately does not enumerate an exception set. Enumerating one would oblige an implementation whose backing technology raises something unlisted either to lie by wrapping it or to break the contract by throwing, so the honest clause is the weaker one. A caller that wraps the call in a catch-all over every failure is therefore correct rather than merely defensive.

Not supported. Two tenants holding the same entry identifier is outside this contract. Identifiers are allocated per entry and are not reused across tenants; a store that admits the same identifier under two tenants fails the addressing operations rather than choosing between the rows.

Methods

EnqueueAsync<T>(T, DeadLetterReason, CancellationToken, Exception?, IDictionary<string, string>?)

Enqueues a message to the dead letter queue.

Task<Guid> EnqueueAsync<T>(T message, DeadLetterReason reason, CancellationToken cancellationToken, Exception? exception = null, IDictionary<string, string>? metadata = null)

Parameters

message T

The message that failed processing.

reason DeadLetterReason

The reason for dead lettering.

cancellationToken CancellationToken

Cancellation token.

exception Exception

Optional exception that caused the failure.

metadata IDictionary<string, string>

Optional additional metadata. A nonblank MessageType supplies the original identity; otherwise the runtime type's declared name is used, or an empty identity when unknown.

Returns

Task<Guid>

The ID of the created dead letter entry.

Type Parameters

T

The type of message being dead lettered.

Remarks

Tenant-scoped: the entry is stored under the ambient tenant. When there is no ambient tenant the entry is stored untenanted and remains addressable only through IDeadLetterQueueAdmin. Missing message-name declarations do not prevent failure capture. An unknown identity is not reconstructed from a CLR type name; replay remains the configured handler's responsibility.

GetCountAsync(CancellationToken, DeadLetterQueryFilter?)

Gets the current count of entries in the dead letter queue.

Task<long> GetCountAsync(CancellationToken cancellationToken, DeadLetterQueryFilter? filter = null)

Parameters

cancellationToken CancellationToken

Cancellation token.

filter DeadLetterQueryFilter

Optional filter to count specific entries.

Returns

Task<long>

The number of entries matching the filter criteria.

Remarks

Tenant-scoped: counts none of another tenant's entries, and every one of the caller's own that matches filter, so the number does not disclose another tenant's failure volume nor undercount the caller's own. The tenant term is taken from the registered tenant context, never from filter.

Fails closed: when multi-tenancy is registered but resolves no tenant, this raises TenantRequiredException rather than counting across tenants. With no tenant context registered at all, the count binds the reserved untenanted partition.

GetEntriesAsync(CancellationToken, DeadLetterQueryFilter?, int)

Retrieves dead letter entries based on filter criteria.

Task<IReadOnlyList<DeadLetterEntry>> GetEntriesAsync(CancellationToken cancellationToken, DeadLetterQueryFilter? filter = null, int limit = 100)

Parameters

cancellationToken CancellationToken

Cancellation token.

filter DeadLetterQueryFilter

Optional filter for querying entries. If null, returns all entries up to the limit.

limit int

Maximum number of entries to return.

Returns

Task<IReadOnlyList<DeadLetterEntry>>

A read-only list of dead letter entries matching the criteria.

Remarks

Tenant-scoped: returns none of another tenant's entries, and every one of the caller's own that matches filter. The tenant term is taken from the registered tenant context, never from filter, so a caller cannot widen this read by omitting a tenant nor redirect it by naming another one.

Fails closed: when multi-tenancy is registered but resolves no tenant, this raises TenantRequiredException rather than returning entries across tenants. With no tenant context registered at all, the read binds the reserved untenanted partition.

GetEntryAsync(Guid, CancellationToken)

Retrieves a specific dead letter entry by its ID.

Task<DeadLetterEntry?> GetEntryAsync(Guid entryId, CancellationToken cancellationToken)

Parameters

entryId Guid

The unique identifier of the entry.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DeadLetterEntry>

The dead letter entry if found, null otherwise.

Remarks

Tenant-scoped: resolves the caller's own entry for entryId when one exists, and an entry stored under another tenant is reported as not found. An identifier alone does not address an entry — it is addressed by identifier within the ambient tenant, so holding an entry id obtained from a log line, an export, or a correlation trail does not grant access to it.

Fails closed: when multi-tenancy is registered but resolves no tenant, this raises TenantRequiredException rather than resolving the entry unscoped. With no tenant context registered at all, the lookup binds the reserved untenanted partition.

ReplayAsync(Guid, CancellationToken)

Replays a dead letter entry, re-submitting it for processing.

Task<bool> ReplayAsync(Guid entryId, CancellationToken cancellationToken)

Parameters

entryId Guid

The unique identifier of the entry to replay.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<bool>

true when this call replayed the entry; false when it did not.

Remarks

A replay happens at most once per entry, and the return says whether it was THIS call that performed it. An implementation claims the entry before invoking the handler, so of several concurrent callers exactly one replays and the others return false. A false therefore carries three distinct situations and does not separate them: no such entry; the entry was already replayed; or another caller claimed it first. Treat it as "not replayed by me" rather than as "not found".

A handler that throws propagates, and the claim is released so the entry can be replayed again — a transient downstream failure does not consume the entry.

Known gap. If the process stops between claiming an entry and delivering it, or if releasing the claim after a failed handler does not succeed, the entry is left marked replayed without having been delivered — and that state cannot be told apart from a replay that succeeded, because the entry carries the same flag either way. The lost replay is bounded: it affects the one entry, and no later batch re-delivers it. The remaining signal is a logged warning, so treat a replay that reported an error as needing confirmation from your own handler's effects rather than from the entry's state.

Tenant-scoped: only an entry stored under the ambient tenant is replayable, and another tenant's entry is reported as not found. Fails closed: when multi-tenancy is registered but resolves no tenant, this raises TenantRequiredException rather than replaying unscoped.

The replay target is enforced and is a separate property: a replayed message always re-enters the tenant its entry was stored under, never the caller's, so a replay cannot inject another tenant's message into the caller's own tenant.