Table of Contents

Class InMemoryDeadLetterStore

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

In-memory implementation of the dead letter store for development and testing.

public sealed class InMemoryDeadLetterStore : IDeadLetterStore, IServiceProvider, IDeadLetterStoreAdmin
Inheritance
InMemoryDeadLetterStore
Implements
Inherited Members
Extension Methods

Constructors

InMemoryDeadLetterStore(ITenantContext, ILogger<InMemoryDeadLetterStore>)

Initializes a new instance of the InMemoryDeadLetterStore class.

public InMemoryDeadLetterStore(ITenantContext tenantContext, ILogger<InMemoryDeadLetterStore> logger)

Parameters

tenantContext ITenantContext

The ambient tenant context. Required: this store partitions rows by tenant, and it resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.

logger ILogger<InMemoryDeadLetterStore>

The logger for diagnostic output.

Methods

CleanupOldMessagesAsync(int, CancellationToken)

Cleans up old dead letter messages for the ambient tenant, by retention policy.

public Task<int> CleanupOldMessagesAsync(int retentionDays, CancellationToken cancellationToken)

Parameters

retentionDays int

Entries dead-lettered longer ago than this are removed.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

Task<int>

The number of entries removed, all of them owned by the ambient tenant.

Remarks

Confined to the ambient tenant, and this is the operation where that matters most on this interface. A retention sweep matches rows by age, so an implementation that omits the tenant term deletes every tenant's aged entries whenever any one tenant's retention runs -- silent data loss rather than a disclosure, and unrecoverable, since a dead-lettered message is the only remaining copy. Scoping only the read paths does not remove that problem, it relocates it.

DeleteAsync(string, CancellationToken)

Deletes a dead letter message.

public Task<bool> DeleteAsync(string messageId, CancellationToken cancellationToken)

Parameters

messageId string

The ID of the message to delete.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<bool>

A task representing the asynchronous operation with a boolean indicating success.

GetByIdAsync(string, CancellationToken)

Retrieves a dead letter message by its ID.

public Task<DeadLetterMessage?> GetByIdAsync(string messageId, CancellationToken cancellationToken)

Parameters

messageId string

The ID of the message to retrieve.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<DeadLetterMessage>

A task containing the dead letter message, or null if not found.

GetCountAsync(CancellationToken)

Gets the count of messages in the dead letter queue, for the ambient tenant.

public Task<long> GetCountAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

Task<long>

The number of entries the ambient tenant owns.

Remarks

Confined to the ambient tenant, on the same terms as every read on IDeadLetterStore. The confinement is restated here rather than inherited, because this is a separate interface and an implementer writing it does not necessarily read the one above. An estate-wide total is a disclosure even though it returns no message content: it tells one tenant how many failures every other tenant has.

GetMessagesAsync(DeadLetterFilter, CancellationToken)

Retrieves dead letter messages based on filter criteria.

public Task<IEnumerable<DeadLetterMessage>> GetMessagesAsync(DeadLetterFilter filter, CancellationToken cancellationToken)

Parameters

filter DeadLetterFilter

The filter criteria for retrieving messages.

cancellationToken CancellationToken

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

public Task<DeadLetterReplayOutcome> MarkAsReplayedAsync(string messageId, CancellationToken cancellationToken)

Parameters

messageId string

The ID of the message to claim.

cancellationToken CancellationToken

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

public Task ReleaseReplayClaimAsync(string messageId, CancellationToken cancellationToken)

Parameters

messageId string

The ID of the message whose claim is being released.

cancellationToken CancellationToken

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

public Task StoreAsync(DeadLetterMessage message, CancellationToken cancellationToken)

Parameters

message DeadLetterMessage

The dead letter message to store.

cancellationToken CancellationToken

The cancellation token.

Returns

Task

A task representing the asynchronous operation.