Table of Contents

Class MartenOutboxStore

Namespace
Excalibur.Outbox.Marten
Assembly
Excalibur.Outbox.Marten.dll

Marten (PostgreSQL document store) implementation of IOutboxStore and IOutboxStoreAdmin.

[RequiresUnreferencedCode("Marten outbox document mapping and queries depend on runtime metadata. This provider is not compatible with trimming.")]
[RequiresDynamicCode("Marten outbox document mapping uses runtime type metadata and may require native generic instantiations unavailable under NativeAOT. The current internal document path has not been validated for NativeAOT.")]
public sealed class MartenOutboxStore : IOutboxStore, IServiceProvider, IOutboxPayloadTransformStore, IOutboxStoreAdmin, ITenantPartitionedStore, IClaimScopedOutboxStore, IDisposable
Inheritance
MartenOutboxStore
Implements
Inherited Members

Remarks

Each operation composes a Marten Marten.IDocumentSession from the injected Marten.IDocumentStore and commits it with SaveChangesAsync, so staging rides Marten's own unit-of-work transaction.

Staging uses IDocumentSession.Insert — a real conditional write that fails when a message with the same id already exists — rather than an upsert, so a concurrent duplicate is rejected rather than silently overwriting the original (the exactly-once staging invariant).

Tenancy: the discriminator is carried on the document, never applied as a filter. Each staged document records the tenant of the message it projects, and every drained message hands that value back, so the owning tenant is re-established from the document rather than inferred from ambient state. This store reads no ambient tenant on any path, and its declaration of ITenantPartitionedStore states that mechanism explicitly.

The drain is deliberately estate-wide, and that is a requirement rather than an omission: one dispatcher serves every tenant, so a drain narrowed to an ambient tenant would read it as absent, claim the empty set, and stall delivery for all of them. The remaining statements load, update, and delete a document by its identity, where a tenant term could not exclude a foreign document — the identity already addresses at most one — and could only turn the correct document into none.

Constructors

MartenOutboxStore(IDocumentStore, IOptions<MartenOutboxStoreOptions>, ILogger<MartenOutboxStore>, TimeProvider?)

Initializes a new instance of the MartenOutboxStore class.

public MartenOutboxStore(IDocumentStore store, IOptions<MartenOutboxStoreOptions> options, ILogger<MartenOutboxStore> logger, TimeProvider? timeProvider = null)

Parameters

store IDocumentStore

The Marten document store.

options IOptions<MartenOutboxStoreOptions>

The outbox store options.

logger ILogger<MartenOutboxStore>

The logger instance.

timeProvider TimeProvider

The clock used for the instants this store records rather than compares — a send time, an attempt time, the moment a statistics snapshot was taken. Defaults to System.

It is deliberately NOT the clock that decides claim eligibility. A lease is written by one machine and judged by another, so any predicate reading this clock would compare two unsynchronised ones; those instants come from clock_timestamp() inside the claim statement instead. Injecting the clock here is what lets a test drive this store's clock arbitrarily far from the database's and observe that the claim does not move — which is the property, stated as a test.

Methods

CleanupAllTenantsSentMessagesAsync(DateTimeOffset, int, CancellationToken)

Removes sent messages older than the specified age across every tenant.

public ValueTask<int> CleanupAllTenantsSentMessagesAsync(DateTimeOffset olderThan, int batchSize, CancellationToken cancellationToken)

Parameters

olderThan DateTimeOffset

Remove messages sent before this timestamp.

batchSize int

Maximum number of messages to remove in one operation.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<int>

The number of messages removed, across all tenants.

Remarks

This is an estate-wide retention sweep and is deliberately unscoped: it matches rows by age, not by tenant, so it removes the qualifying messages of every tenant in the store. The name declares that scope so it cannot be reached by a caller who meant a single tenant.

An outbox store reads no ambient tenant context, so it cannot honor a tenant it never sees. Should tenant-scoped retention ever be required, it arrives as an explicit parameter — never by inferring a scope from ambient state.

Dispose()

Releases the lock guarding one-time creation of the claim table.

public void Dispose()

Remarks

The Marten IDocumentStore is supplied by the consumer and stays theirs to dispose; the only thing this store owns is the lock.

EnqueueAsync(IDispatchMessage, IMessageContext, CancellationToken)

Enqueues a message in the outbox for later delivery with context.

[RequiresUnreferencedCode("Outbox stores serialize the message payload reflectively; supply JsonSerializerOptions with a source-generated resolver for trimming and AOT.")]
[RequiresDynamicCode("Outbox stores serialize the message payload reflectively; supply JsonSerializerOptions with a source-generated resolver for trimming and AOT.")]
public ValueTask EnqueueAsync(IDispatchMessage message, IMessageContext context, CancellationToken cancellationToken)

Parameters

message IDispatchMessage

The message to enqueue.

context IMessageContext

The message context.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask

A task representing the asynchronous enqueue operation.

Remarks

Postcondition on what is staged. The staged message's headers contain exactly the values marked on context with SetPropagatedItem(IMessageContext, string, string), plus whatever envelope keys this store supplies as its own framing. No other context state reaches them — in particular not Items, which is request-local.

This is stated here, on the interface, because it is the specification and not an implementation detail: while it lived only in the implementations, one store staged the whole Items collection, two staged their envelope keys and nothing else, and six staged neither — all three behaviours legal, none a subtyping violation, and a consumer unable to predict which they would get. Staging MORE than this is now as wrong as staging less, and a conformance derivation can check both directions.

Build the staged message with FromContext(string, byte[], string, IMessageContext, IDictionary<string, object>?), which satisfies the postcondition by construction. A store that assembles an OutboundMessage by hand is responsible for satisfying it itself.

Exceptions

ArgumentNullException

Thrown when message or context is null.

GetAllTenantsFailedMessagesAsync(int, DateTimeOffset?, int, CancellationToken)

Retrieves failed messages that are eligible for retry, across every tenant.

public ValueTask<IEnumerable<OutboundMessage>> GetAllTenantsFailedMessagesAsync(int maxRetries, DateTimeOffset? olderThan, int batchSize, CancellationToken cancellationToken)

Parameters

maxRetries int

Maximum number of retry attempts to consider.

olderThan DateTimeOffset?

Only return messages that failed before this timestamp.

batchSize int

Maximum number of messages to retrieve.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<IEnumerable<OutboundMessage>>

Collection of failed messages eligible for retry, across all tenants.

Remarks

Observation only — the result MUST NOT be handed to a transport. This is a plain read: it matches rows without conditionally taking them, so two callers observe the same message and neither holds it. Publishing from this set is check-then-act and delivers the message twice. A drain claims through IOutboxStore.GetUnsentMessagesAsync, whose claim already admits a failed message once its next-attempt floor has elapsed; this read consults no floor, so a message deferred moments ago still appears here. Use it to report and diagnose, never to dispatch.

Scope: estate-wide. This read matches rows by status and age, not by tenant, so it observes the messages of every tenant in the store. It modifies nothing. Each returned OutboundMessage carries its own TenantId, so a caller can re-establish the owning tenant for each message it handles.

The name is the safety control. An unscoped read is reachable only by writing "AllTenants" at the call site — never by omitting a scope, and never by passing a value that happens to mean "everything". This discloses full message bodies, so a reviewer reading the call site sees the disclosure without tracing where a scope came from.

The outbox drain is cross-tenant by design: one dispatcher serves every tenant, so scoping this read to an ambient tenant would stall delivery for all the others. An outbox store reads no ambient tenant context; should a tenant-scoped read ever be required, it arrives as an explicit parameter on a distinct operation — never by inferring a scope from ambient state.

GetAllTenantsScheduledMessagesAsync(DateTimeOffset, int, CancellationToken)

Retrieves messages scheduled for future delivery, across every tenant.

public ValueTask<IEnumerable<OutboundMessage>> GetAllTenantsScheduledMessagesAsync(DateTimeOffset scheduledBefore, int batchSize, CancellationToken cancellationToken)

Parameters

scheduledBefore DateTimeOffset

Only return messages scheduled before this timestamp.

batchSize int

Maximum number of messages to retrieve.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<IEnumerable<OutboundMessage>>

Collection of scheduled messages ready for delivery, across all tenants.

Remarks

Observation only — the result MUST NOT be handed to a transport. This is a plain read: it matches rows without conditionally taking them, so two callers observe the same message and neither holds it. Publishing from this set is check-then-act and delivers the message twice — a filter on an unset dispatcher column does not make it a claim, because the value it tests is never conditionally written. A drain claims through IOutboxStore.GetUnsentMessagesAsync, whose claim already admits a scheduled message once its time has arrived. Use it to report and diagnose, never to dispatch.

Scope: estate-wide. This read matches rows by status and age, not by tenant, so it observes the messages of every tenant in the store. It modifies nothing. Each returned OutboundMessage carries its own TenantId, so a caller can re-establish the owning tenant for each message it handles.

The name is the safety control. An unscoped read is reachable only by writing "AllTenants" at the call site — never by omitting a scope, and never by passing a value that happens to mean "everything". This discloses full message bodies, so a reviewer reading the call site sees the disclosure without tracing where a scope came from.

The outbox drain is cross-tenant by design: one dispatcher serves every tenant, so scoping this read to an ambient tenant would stall delivery for all the others. An outbox store reads no ambient tenant context; should a tenant-scoped read ever be required, it arrives as an explicit parameter on a distinct operation — never by inferring a scope from ambient state.

GetAllTenantsStatisticsAsync(CancellationToken)

Gets statistics about the outbox store, across every tenant.

public ValueTask<OutboxStatistics> GetAllTenantsStatisticsAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<OutboxStatistics>

Statistics including message counts by status and oldest unsent message age, across all tenants.

Remarks

Scope: estate-wide. The name is the safety control: estate-wide counters are reachable only by writing "AllTenants" at the call site, never by omitting a scope. Aggregate counts disclose no message identifiers, bodies, or tenant names — only totals — so this is a weaker disclosure than GetAllTenantsFailedMessagesAsync(int, DateTimeOffset?, int, CancellationToken), which returns whole messages.

These are estate-wide counters reported to an operator, not to a tenant. The figures describe the whole table: the call takes no tenant argument, and OutboxStatistics carries no tenant field, so a confined result could not say which partition it described even if one were produced.

An outbox store reads no ambient tenant context, so it cannot honor a tenant it never sees. Should per-tenant counters ever be required, they arrive as an explicit parameter on a distinct operation — never by inferring a scope from ambient state.

GetUnsentMessagesAsync(int, CancellationToken)

Retrieves unsent messages from the outbox for publishing.

public ValueTask<IEnumerable<OutboundMessage>> GetUnsentMessagesAsync(int batchSize, CancellationToken cancellationToken)

Parameters

batchSize int

Maximum number of messages to retrieve.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<IEnumerable<OutboundMessage>>

Collection of unsent messages ready for delivery.

Remarks

This operation returns persisted payload bytes and closed routing/header data; it does not discover or deserialize consumer payload types. Payload decoding belongs to the configured worker codec and its explicit metadata. Provider construction may impose separate runtime requirements. This claim is unfenced. A store that can enforce leadership fencing implements IFencedOutboxStore, whose overloads take the leadership token; a store that cannot is never handed one.

Exceptions

ArgumentOutOfRangeException

Thrown when batchSize is less than 1.

MarkFailedAsync(string, string, int, string, CancellationToken)

Records a delivery failure reported by the claim identified by claimIdentity.

public ValueTask<OutboxCompletionOutcome> MarkFailedAsync(string messageId, string errorMessage, int retryCount, string claimIdentity, CancellationToken cancellationToken)

Parameters

messageId string

The unique identifier of the message that failed.

errorMessage string

The error describing the failure.

retryCount int

The absolute attempt count for this message.

claimIdentity string

The claim under which the caller received this message, from DispatcherId.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<OutboxCompletionOutcome>

What the store did, decided by the same atomic action that performed the mutation.

Remarks

Implementations MUST evaluate the claim and the mutation in ONE atomic action, and MUST decide whether to refuse from that same action. A store that reconstructs the decision from a separate read compares a value captured before the window it must describe, which is false exactly when the refusal is real.

A refusal is REPORTED, not thrown, and the reason is the caller's control flow rather than style. The drain reports a delivery failure from inside its own exception handler; an exception raised there is not caught by a sibling catch on the same try, so it escapes the whole cycle and abandons every message the caller still holds. The refusal must cost one message, so it travels in the return value where the caller reads it without unwinding.

A refusal here is ROW-LEVEL, and the distinction decides how much work is abandoned. A fence refusal means a NEWER TENURE exists and the whole drain cycle must stop, whereas ClaimLost means only that this message was re-claimed — the caller stops writing for THIS message and continues with the others it still holds. A caller that aborts its cycle on a lost claim abandons messages a live tenure owns.

Exceptions

ArgumentException

Thrown when messageId is null or empty.

MarkFailedAsync(string, string, int, CancellationToken)

Marks a message as failed during delivery.

public ValueTask MarkFailedAsync(string messageId, string errorMessage, int retryCount, CancellationToken cancellationToken)

Parameters

messageId string

The unique identifier of the message that failed.

errorMessage string

The error description or exception message.

retryCount int

The current retry attempt count.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask

A task representing the asynchronous mark-failed operation.

Remarks

A failure is a delay, not an ending. The message stays owed delivery, and three conditions hold together to keep that true without turning it into a retry loop. Each is stated because a store can satisfy the other two and still be wrong.

The message is withheld, then returned. It does not become claimable again immediately -- an immediate re-claim is a zero-backoff loop that saturates the transport against a destination that is failing anyway -- and it does become claimable once the store's failure-backoff floor has elapsed. The floor is measured from the recorded failure, not from a claim lease: a message that failed without ever being claimed has no lease, and a floor derived from one would yield nothing for it. Withholding it permanently satisfies the first half and silently drops the message, so both halves are required.

A report from a dispatcher that no longer holds the claim is a no-op rather than an error -- it is stale, not invalid. Honouring it would release a claim its successor is still delivering under, and both would then send the same message. A message that was never claimed has no owner and is reported freely. The guard must not be satisfied by refusing everybody -- the owner's own report still has to land, or the store cannot record failures at all.

HOW FINELY "no longer holds the claim" IS JUDGED VARIES BY STORE, AND THIS MEMBER DOES NOT PROMISE PER-CLAIM PRECISION. An earlier wording here said only the claim's owner may report against it, which reads as a per-claim guarantee that no shipped store keeps through this member. What the shipped stores actually compare is a per-PROCESS identity, so two successive claims by the same process are indistinguishable to it: a report from an expired claim of a still-running dispatcher is accepted, and it releases a reservation a live successor of that same process still holds.

THE FLOOR A CALLER MAY RELY ON, stated because "varies by store" is not a contract. Every shipped store that offers this member refuses a report against a message currently held by a DIFFERENT dispatcher process, and admits one against a message nobody holds. That is the floor, and it is uniform: what varies above it is only whether a store can also distinguish two claim cycles of the SAME process, and none of them can through this member. An implementor of this interface is required to meet the floor; a store that matches on the message identifier alone does not implement this member's contract, however well it records the identity elsewhere.

The floor is expressed differently by different data models -- a prefix of a stored claim token, an equality against a configured processor identity, a conditional script, an in-process comparison -- and the obligation is the property, not the mechanism. Note what the floor deliberately does NOT require: an "ownership term" a caller can satisfy by omitting the value it guards is not a guard, so a store whose only option would be such a predicate must instead offer the claim-scoped member below and refuse here, rather than carry a predicate with a hole in it.

For a completion judged against the specific claim the caller holds, use IClaimScopedOutboxStore. It takes the claim identity as an argument and returns an outcome saying whether the store applied the completion or refused it, so a caller whose claim has lapsed is told rather than silently succeeding. Discover it with GetService(Type) rather than a cast: a cast sees only the outermost type and is lossy through any decorator. Not every store implements it; a caller that needs the guarantee should check, because the fallback to this member is the weaker comparison described above.

The recorded attempt count never decreases. Implementations record the greater of the stored count and retryCount. The ceiling that eventually gives up on a message is driven by that count, so a late report carrying a lower number would push the ceiling further away each time one arrived, and the message would be retried without end.

Marking a message that does not exist is a silent no-op. A message in a terminal state is never reopened by a late failure report, and terminal means delivered or dead-lettered -- in both, the decision to stop delivering has already been taken and recorded. Guarding only the delivered state is the error this wording exists to prevent: a reopened dead-lettered message re-enters the retry population it was deliberately removed from. A message merely in flight is not terminal, and a failure report against one must land -- that is the ordinary path this method exists to serve.

The ownership condition above cannot carry this guarantee, and a store that relies on it will be wrong. Dead-lettering releases the delivery lease, so a dead-lettered message presents as never-claimed and is therefore reported freely by that rule. The terminal-state check is required in its own right and applies unconditionally.

The obligation is the property, not the mechanism. A store satisfies it however its data model allows: a status term in the mutation's own predicate, a terminal transition that removes the row so no later report can match it, a claim record stamped with an identity no caller can present, or a claimable predicate keyed on a field the failure path never writes. What is required is that a late report cannot reopen a terminal message -- not that any particular column be tested.

Exceptions

ArgumentException

Thrown when messageId is null or empty.

ArgumentNullException

Thrown when errorMessage is null.

MarkFailedWithBackoffAsync(string, string, int, DateTimeOffset, string, CancellationToken)

Records a delivery failure reported by the claim identified by claimIdentity, applying the per-message backoff schedule.

public ValueTask<OutboxCompletionOutcome> MarkFailedWithBackoffAsync(string messageId, string errorMessage, int retryCount, DateTimeOffset nextAttemptAt, string claimIdentity, CancellationToken cancellationToken)

Parameters

messageId string

The unique identifier of the message that failed.

errorMessage string

The error describing the failure.

retryCount int

The absolute attempt count for this message.

nextAttemptAt DateTimeOffset

The time before which the message must NOT be re-claimed.

claimIdentity string

The claim under which the caller received this message, from DispatcherId.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<OutboxCompletionOutcome>

What the store did, decided by the same atomic action that performed the mutation.

Remarks

This member exists because the backoff route is the one a genuine delivery failure takes when automatic retry is enabled. Scoping only the plain completion would leave the dominant failure path unscoped while the capability appeared to close it. The same atomicity and reported-refusal requirements as MarkFailedAsync(string, string, int, string, CancellationToken) apply here in full.

Exceptions

ArgumentException

Thrown when messageId is null or empty.

MarkSentAsync(string, string, CancellationToken)

Marks a message sent only while the caller holds the current claim.

public ValueTask<OutboxCompletionOutcome> MarkSentAsync(string messageId, string claimIdentity, CancellationToken cancellationToken)

Parameters

messageId string

The persisted message identifier captured at acquisition.

claimIdentity string

The immutable acquisition evidence captured before delivery.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<OutboxCompletionOutcome>

The outcome decided atomically with the guarded terminal transition.

Remarks

Missing or released leases return ClaimLost. Validate nonblank identifiers before mutation. A fenced authority additionally requires a positive tenure; evaluate its fence before row-level outcomes. Retained terminal rows return AlreadyTerminal. Never infer the outcome from a later read.

MarkSentAsync(string, CancellationToken)

Marks a message as successfully sent.

public ValueTask MarkSentAsync(string messageId, CancellationToken cancellationToken)

Parameters

messageId string

The unique identifier of the message to mark as sent.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask

A task representing the asynchronous mark-sent operation.

Remarks

This mutation is unfenced. A store that can enforce leadership fencing implements IFencedOutboxStore.

Exceptions

ArgumentException

Thrown when messageId is null or empty.

InvalidOperationException

Thrown when the message does not exist or is already marked as sent.

StageMessageAsync(OutboundMessage, CancellationToken)

Stages a message in the outbox for later delivery.

public ValueTask StageMessageAsync(OutboundMessage message, CancellationToken cancellationToken)

Parameters

message OutboundMessage

The outbound message to stage.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask

A task representing the asynchronous stage operation.

Exceptions

ArgumentNullException

Thrown when message is null.

InvalidOperationException

Thrown when a message with the same ID already exists.