Class NullDeadLetterQueue
- Namespace
- Excalibur.Dispatch.ErrorHandling
- Assembly
- Excalibur.Dispatch.dll
A no-op implementation of IDeadLetterQueue that discards every message handed to it.
[SuppressMessage("Naming", "CA1711:Identifiers should not have incorrect suffix", Justification = "Represents a dead letter queue implementation.")]
public sealed class NullDeadLetterQueue : IDeadLetterQueue, IDeadLetterQueueAdmin
- Inheritance
-
NullDeadLetterQueue
- Implements
- Inherited Members
- Extension Methods
Remarks
This is not a default. Nothing registers it on your behalf; a host that enables
dead-letter routing without a store is refused at composition rather than given this type. Register it
explicitly — services.AddSingleton<IDeadLetterQueue>(NullDeadLetterQueue.Instance) — to state
that exhausted messages should be dropped.
Every caller in the framework checks for this type and reports a discard rather than a dead-letter routing, so EnqueueAsync<T>(T, DeadLetterReason, CancellationToken, Exception?, IDictionary<string, string>?) is never invoked on it and its Empty return is never handed to a caller as an entry id. Preserve that discipline in your own code: an entry id from this type names no entry, and a log line claiming a message was dead-lettered through it would be false.
Properties
Instance
Gets the singleton instance of the null dead letter queue.
public static NullDeadLetterQueue Instance { get; }
Property Value
Methods
EnqueueAsync<T>(T, DeadLetterReason, CancellationToken, Exception?, IDictionary<string, string>?)
Enqueues a message to the dead letter queue.
public Task<Guid> EnqueueAsync<T>(T message, DeadLetterReason reason, CancellationToken cancellationToken, Exception? exception = null, IDictionary<string, string>? metadata = null)
Parameters
messageTThe message that failed processing.
reasonDeadLetterReasonThe reason for dead lettering.
cancellationTokenCancellationTokenCancellation token.
exceptionExceptionOptional exception that caused the failure.
metadataIDictionary<string, string>Optional additional metadata. A nonblank
MessageTypesupplies the original identity; otherwise the runtime type's declared name is used, or an empty identity when unknown.
Returns
Type Parameters
TThe 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.
public Task<long> GetCountAsync(CancellationToken cancellationToken, DeadLetterQueryFilter? filter = null)
Parameters
cancellationTokenCancellationTokenCancellation token.
filterDeadLetterQueryFilterOptional filter to count specific entries.
Returns
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.
public Task<IReadOnlyList<DeadLetterEntry>> GetEntriesAsync(CancellationToken cancellationToken, DeadLetterQueryFilter? filter = null, int limit = 100)
Parameters
cancellationTokenCancellationTokenCancellation token.
filterDeadLetterQueryFilterOptional filter for querying entries. If null, returns all entries up to the limit.
limitintMaximum 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.
public Task<DeadLetterEntry?> GetEntryAsync(Guid entryId, CancellationToken cancellationToken)
Parameters
entryIdGuidThe unique identifier of the entry.
cancellationTokenCancellationTokenCancellation 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.
public Task<bool> ReplayAsync(Guid entryId, CancellationToken cancellationToken)
Parameters
entryIdGuidThe unique identifier of the entry to replay.
cancellationTokenCancellationTokenCancellation token.
Returns
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.