Table of Contents

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

NullDeadLetterQueue

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

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.

public 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.

public 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.

public 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.

public 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.