Table of Contents

Interface IOutboxPublisher

Namespace
Excalibur.Dispatch
Assembly
Excalibur.Dispatch.Abstractions.dll

Provides background publishing of outbound messages from the outbox store.

public interface IOutboxPublisher
Extension Methods

Remarks

The outbox publisher runs out-of-band from request processing to publish messages that were staged during business operations. This ensures:

  • Reliable delivery - messages are retried until successfully sent
  • Performance isolation - message publishing doesn't block request processing
  • Scalability - publishing can be scaled independently from business logic
  • Fault tolerance - publishing failures don't affect business operations

Publishers can be run as background services, scheduled jobs, or triggered by events.

Methods

GetStatistics()

Gets statistics about the outbox publisher performance.

PublisherStatistics GetStatistics()

Returns

PublisherStatistics

Publishing statistics including throughput and error rates.

PublishAsync(object, string, DateTimeOffset?, CancellationToken)

Stages a message in the outbox for later delivery.

Task<OutboundMessage> PublishAsync(object message, string destination, DateTimeOffset? scheduledAt, CancellationToken cancellationToken)

Parameters

message object

The message to publish.

destination string

The target destination (queue, topic, or endpoint).

scheduledAt DateTimeOffset?

Optional time when the message should be processed. If null, process immediately.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<OutboundMessage>

The staged outbound message for tracking.

PublishPendingMessagesAsync(CancellationToken)

Claims a batch of due messages from the outbox store and publishes it.

Task<PublishingResult> PublishPendingMessagesAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

Task<PublishingResult>

The result of the publishing operation including success/failure counts.

Remarks

Implementations MUST win a lease before handing any message to a transport. The store's claim is an atomic read-decide-write, so concurrent drains receive disjoint batches. Selecting rows with a plain read and publishing them is check-then-act and admits double delivery, however narrow the read's filter.

The claim also decides which rows are due. It admits a message that is unclaimed (or whose lease has expired), whose scheduled time has arrived, and whose next-attempt floor has elapsed — so one drain covers immediate, scheduled and retry-eligible messages alike.

Exceptions

OperationCanceledException

Thrown when the operation is cancelled.

PublishScheduledMessagesAsync(CancellationToken)

Runs a drain pass that delivers scheduled messages whose time has arrived.

Task<PublishingResult> PublishScheduledMessagesAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

Task<PublishingResult>

The result of the publishing operation including success/failure counts.

Remarks

A scheduled message is delivered by the same claim as every other message — the claim admits it once its scheduled time has passed — so this is a further pass of the drain described on PublishPendingMessagesAsync(CancellationToken) and carries the same lease requirement. It is not a second, unleased path: implementations MUST NOT satisfy it with a plain read of scheduled rows. A batch drained here may therefore also contain immediate or retry-eligible messages, which is deliberate — the claim is not category-selective, and filtering a claimed batch would strand the rows it discarded under a live lease.

Exceptions

OperationCanceledException

Thrown when the operation is cancelled.

RetryFailedMessagesAsync(int, CancellationToken)

Runs a drain pass that redelivers failed messages whose backoff floor has elapsed.

Task<PublishingResult> RetryFailedMessagesAsync(int maxRetries, CancellationToken cancellationToken)

Parameters

maxRetries int

Maximum number of retry attempts per message. Must not be negative.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

Task<PublishingResult>

The result of the retry operation including success/failure counts.

Remarks

A failed message becomes deliverable again only once the next-attempt floor written by the failure path has elapsed, and the claim is what enforces that. Implementations MUST NOT select failed rows with a read that ignores the floor: doing so republishes a message the same drain has just deferred, on every poll cycle, which is the zero-backoff retry loop the floor exists to prevent.

As with PublishScheduledMessagesAsync(CancellationToken), this is a further pass of the same claim-backed drain and may deliver messages of any category. maxRetries is validated but does not narrow the batch; the retry ceiling is enforced by the dead-letter transition, not by the drain.

Exceptions

ArgumentOutOfRangeException

Thrown when maxRetries is less than 0.

OperationCanceledException

Thrown when the operation is cancelled.