Table of Contents

Class OutboxProcessor

Namespace
Excalibur.Dispatch.Delivery
Assembly
Excalibur.Outbox.dll

High-performance outbox processor implementation that manages message queuing, batching, and dispatch operations. This component implements the outbox pattern with advanced features including dynamic batch sizing, parallel processing, telemetry integration, and comprehensive error handling for reliable message delivery.

[SuppressMessage("Maintainability", "CA1506:Avoid excessive class coupling", Justification = "Core coordinator that legitimately orchestrates dispatch through multiple subsystems")]
public sealed class OutboxProcessor : IOutboxProcessor, IAsyncDisposable
Inheritance
OutboxProcessor
Implements
Inherited Members

Remarks

CA1506 suppressed: OutboxProcessor is a core coordinator that legitimately orchestrates message dispatch through multiple subsystems (batching, telemetry, persistence, scheduling, error handling). High coupling is inherent to its coordination responsibilities and cannot be reduced without fragmenting cohesive functionality.

Constructors

OutboxProcessor(IOptions<OutboxDeliveryOptions>, IOutboxStore, DispatchJsonSerializer, IServiceProvider, ILogger<OutboxProcessor>, ITransportCircuitBreakerRegistry, IBinaryEnvelopeDeserializer?, IDeadLetterQueue?, IBackoffCalculator?, IOptions<DeliveryGuaranteeOptions>?, ILeaderProcessingGate?)

Initializes a new instance of the OutboxProcessor class. Initializes a new instance of the OutboxProcessor with required dependencies and configuration. This constructor sets up the message queue, batch processing metrics, dynamic batch sizing, and validates configuration parameters for optimal performance and reliability.

public OutboxProcessor(IOptions<OutboxDeliveryOptions> options, IOutboxStore outboxStore, DispatchJsonSerializer serializer, IServiceProvider serviceProvider, ILogger<OutboxProcessor> logger, ITransportCircuitBreakerRegistry circuitBreakerRegistry, IBinaryEnvelopeDeserializer? envelopeDeserializer = null, IDeadLetterQueue? deadLetterQueue = null, IBackoffCalculator? backoffCalculator = null, IOptions<DeliveryGuaranteeOptions>? deliveryGuaranteeOptions = null, ILeaderProcessingGate? leaderGate = null)

Parameters

options IOptions<OutboxDeliveryOptions>

Configuration options for outbox processing behavior and performance tuning.

outboxStore IOutboxStore

Persistent store for outbox message management and retrieval operations.

serializer DispatchJsonSerializer

JSON serializer for message and metadata serialization/deserialization.

serviceProvider IServiceProvider

Service provider for dependency injection and message bus resolution.

logger ILogger<OutboxProcessor>

Logger for outbox processing activities, errors, and performance monitoring.

circuitBreakerRegistry ITransportCircuitBreakerRegistry

Required circuit breaker registry for transport resilience. It is required rather than optional because a drain that silently ran without a circuit breaker was indistinguishable from one that had a working breaker, and the difference only became visible under a failing transport.

envelopeDeserializer IBinaryEnvelopeDeserializer

Optional binary envelope deserializer for high-performance binary envelope support.

deadLetterQueue IDeadLetterQueue

Explicit dead letter queue for failed messages. Null is rejected; pass NullDeadLetterQueue.Instance to intentionally discard.

backoffCalculator IBackoffCalculator

Optional backoff calculator for retry delays. Uses ExponentialBackoffCalculator.Default if not provided.

deliveryGuaranteeOptions IOptions<DeliveryGuaranteeOptions>

Optional delivery guarantee options. Uses default at-least-once semantics if not provided.

leaderGate ILeaderProcessingGate

Optional leader-election processing gate. When provided, its fencing token is stamped on every claim/mark-sent call so a superseded leader's mutations are rejected by the store. Null when no leader election is configured (plain, unfenced claim).

Exceptions

ArgumentNullException

Thrown when any required parameter is null.

InvalidOperationException

Thrown when configuration validation fails.

Methods

DispatchPendingMessagesAsync(CancellationToken)

Processes and dispatches all pending messages from the outbox using producer-consumer pattern with batch processing. This method implements the core outbox functionality with parallel message processing, dynamic batch sizing, comprehensive error handling, and telemetry integration for reliable message delivery.

public Task<int> DispatchPendingMessagesAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancellation token to support graceful shutdown and timeout scenarios.

Returns

Task<int>

Task containing the total number of messages successfully dispatched from the outbox.

Exceptions

ObjectDisposedException

Thrown when the processor has been disposed.

InvalidOperationException

Thrown when processor is not properly initialized via Init method.

MessagingException

Thrown when message processing fails due to broker or serialization issues.

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

Init(string)

Sets the processor identity. Repeating the same identity is allowed; replacing an established identity is rejected. Processing starts when DispatchPendingMessagesAsync is called. Sequential drains are supported; overlapping drains are rejected.

public void Init(string dispatcherId)

Parameters

dispatcherId string

Unique identifier for this dispatcher instance, used for message ownership and coordination.

Exceptions

ArgumentException

Thrown when dispatcherId is null, empty, or whitespace.

InvalidOperationException

Thrown when processor is already initialized or in invalid state.