Table of Contents

Interface IDeadLetterQueueAdmin

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

Provides batch and purge operations for the dead letter queue.

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

Remarks

Tenancy. This interface is estate-wide: a platform operator inspects, replays, and purges failed messages across every tenant, and these operations are deliberately not filtered by the ambient tenant. It is the privileged counterpart to IDeadLetterQueue and is registered separately, so a host that does not need operator capabilities need not expose it at all.

Entries returned here carry no tenant discriminator — DeadLetterEntry does not expose the originating tenant — so results from different tenants cannot be told apart by the caller, and they include the failed message body. Treat anything obtained through this interface as privileged: do not surface it to a tenant-facing view.

Replay always restores the tenant an entry was stored under, never the caller's. Scope governs which entries an operation may address; it does not change the tenant a replayed message re-enters, so replaying another tenant's entry cannot inject it into the operator's own tenant.

Methods

GetAllTenantsEntriesAsync(DeadLetterQueryFilter?, CancellationToken)

Retrieves dead letter entries belonging to every tenant.

Task<IReadOnlyList<DeadLetterEntry>> GetAllTenantsEntriesAsync(DeadLetterQueryFilter? filter, CancellationToken cancellationToken)

Parameters

filter DeadLetterQueryFilter

Selects the entries to return, and carries the page size through Take. The selection is not narrowed by the ambient tenant. Pass null for the defaults.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyList<DeadLetterEntry>>

The matching entries, drawn from every tenant partition.

Remarks

The operator counterpart to GetEntriesAsync(CancellationToken, DeadLetterQueryFilter?, int), which is confined to the caller's own partition. Entries carry the failed message body and DeadLetterEntry exposes no tenant discriminator, so results from different tenants cannot be told apart by the caller: treat anything obtained here as privileged and never surface it to a tenant-facing view.

The name is the safety control. Estate-wide reach is spelled at the call site, never inferred from a scope nobody established — the same discipline as PurgeAllTenantsEntriesOlderThanAsync(TimeSpan, CancellationToken). A caller cannot arrive here by forgetting to set a tenant, which is the shape that fails open.

An optional capability whose default implementation throws. A store that supports it overrides this method; a decorator must override it to forward to its inner store, or a decorated store reports the capability as missing even though the store underneath supports it.

Exceptions

NotSupportedException

Thrown by stores that do not support estate-wide inspection.

GetAllTenantsEntryAsync(Guid, CancellationToken)

Retrieves a single dead letter entry from whichever tenant holds it.

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

Parameters

entryId Guid

The unique identifier of the entry.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DeadLetterEntry>

The entry, or null when no tenant holds one with that identifier.

Remarks

The operator counterpart to GetEntryAsync(Guid, CancellationToken), which resolves the entry only within the caller's own partition and reports not-found for another tenant's. Identifiers are allocated per entry and are not reused across tenants, so at most one row can match.

The same privilege and naming notes as GetAllTenantsEntriesAsync(DeadLetterQueryFilter?, CancellationToken) apply, and this is likewise an optional capability whose default implementation throws.

Exceptions

NotSupportedException

Thrown by stores that do not support estate-wide inspection.

PurgeAllTenantsEntriesOlderThanAsync(TimeSpan, CancellationToken)

Purges all dead letter entries older than the specified age.

Task<int> PurgeAllTenantsEntriesOlderThanAsync(TimeSpan olderThan, CancellationToken cancellationToken)

Parameters

olderThan TimeSpan

The minimum age an entry must have reached to be purged.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<int>

The number of entries purged.

Remarks

Estate-wide and irreversible: deletes matching entries in every tenant on an age predicate alone. There is no tenant term in the selection, so a host that exposes this operation to a tenant-facing caller lets one tenant delete another's failed messages.

PurgeAsync(Guid, CancellationToken)

Purges a dead letter entry.

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

Parameters

entryId Guid

The unique identifier of the entry to purge.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<bool>

True if an entry was purged; false if no entry matched.

Remarks

Estate-wide: addresses the entry in whichever tenant holds it, not only the ambient tenant.

ReplayAllTenantsEntryAsync(Guid, CancellationToken)

Replays a single dead letter entry held by any tenant.

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

Parameters

entryId Guid

The unique identifier of the entry to replay.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<bool>

true when an entry was replayed; false when none matched.

Remarks

The single-entry counterpart to ReplayBatchAsync(DeadLetterQueryFilter, int, CancellationToken), which is already estate-wide, and the operator counterpart to ReplayAsync(Guid, CancellationToken).

Scope governs which entry may be addressed; it never governs where the message lands. A replayed message re-enters the tenant its entry was stored under, never the operator's own, so replaying another tenant's entry cannot inject it into the caller's tenant. An entry stored without a tenant re-enters untenanted.

Likewise an optional capability whose default implementation throws.

Exceptions

NotSupportedException

Thrown by stores that do not support estate-wide replay.

ReplayBatchAsync(DeadLetterQueryFilter, int, CancellationToken)

Replays multiple dead letter entries matching the filter.

Task<ReplayBatchResult> ReplayBatchAsync(DeadLetterQueryFilter filter, int limit, CancellationToken cancellationToken)

Parameters

filter DeadLetterQueryFilter

Selects the entries to replay. The selection is not narrowed by the ambient tenant.

limit int

The maximum number of entries this call may take. Required: the batch size governs how much work a single operator action performs, so it is the caller's to state rather than an implementation's to assume.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<ReplayBatchResult>

A ReplayBatchResult reporting how many entries were enumerated, how many were replayed, and whether limit cut the selection short.

Remarks

Estate-wide: selects across every tenant. Each replayed message re-enters the tenant its entry was stored under, so a batch spanning several tenants restores each message to its own.

A partial batch is reported, never silent: when the limit is reached, Truncated is true and the caller must re-run to drain the remainder. The result is not a bare count, so "this many were replayed" can no longer be mistaken for "every entry matching the filter was replayed".