Table of Contents

Class OutboxDeliveryOptions

Namespace
Excalibur.Dispatch.Options.Delivery
Assembly
Excalibur.Dispatch.dll

Configuration options for outbox pattern implementation, controlling message processing behavior, performance characteristics, and reliability settings. These options enable fine-tuning of batch processing, message lifecycle, retry policies, and throughput optimization.

public class OutboxDeliveryOptions
Inheritance
OutboxDeliveryOptions
Inherited Members
Extension Methods

Remarks

Performance presets are available for common scenarios:

  • HighThroughput()Maximum throughput (10K+ msg/s) with larger batches and parallel processing.
  • Balanced()Good throughput (3-5K msg/s) with moderate batches for general use.
  • HighReliability()Lower throughput (1-2K msg/s) with smallest failure window for critical messages.

Presets can be customized using fluent With*() methods:

var options = OutboxDeliveryOptions.HighThroughput()
    .WithBatchSize(500)
    .WithParallelDegree(4);

Properties

BatchProcessing

Gets or sets the batch processing configuration including parallelism and dynamic sizing.

public OutboxBatchProcessingOptions BatchProcessing { get; set; }

Property Value

OutboxBatchProcessingOptions

The batch processing options.

ConsumerBatchSize

Gets or sets the batch size for message consumption operations when processing outbox messages. This setting balances throughput, memory usage, and message processing latency.

[Range(1, 2147483647)]
public int ConsumerBatchSize { get; set; }

Property Value

int

The current ConsumerBatchSize value.

DefaultMessageTimeToLive

Gets or sets the intended default time-to-live for outbox messages. NOT ENFORCED TODAY — setting it has no effect, and no outbox message expires.

public TimeSpan? DefaultMessageTimeToLive { get; set; }

Property Value

TimeSpan?

The current DefaultMessageTimeToLive value.

Remarks

Do not rely on this to bound how long a message can sit undelivered. It is stamped onto the message at staging and then dropped: the type the stores persist and return carries no expiry member, so nothing durable records it, no provider has a column for it, and the drain never compares anything against it. DeadLetterReason.MessageExpired exists but has no producer — it appears only in the text that maps the enum to a string.

It is documented rather than deleted because the option is shipped, and because an unenforced setting that SAYS it is unenforced is recoverable while one that reads as working is not: a consumer who set it to bound a retention or compliance window currently has no bound at all and no way to discover that.

Until it is enforced, bound the age elsewhere — the dead-letter path on attempt exhaustion (MaxAttempts) still applies, and provider-level retention or a scheduled cleanup over the outbox table is what actually removes old rows.

Enforcing it is a contract change on the persisted message plus a schema change in every outbox provider, and the read side must land AFTER the storage side: a drain taught to compare an expiry today would read the not-before timestamp as the expiry and dead-letter every scheduled message the moment it became due.

DeliveryGuarantee

Gets or sets the delivery guarantee level for outbox message processing.

public OutboxDeliveryGuarantee DeliveryGuarantee { get; set; }

Property Value

OutboxDeliveryGuarantee

The delivery guarantee level. Default is AtLeastOnce for highest throughput with batch completion.

Remarks

This setting controls the trade-off between throughput and failure window:

  • AtLeastOnceHighest throughput with batch completion. Larger failure window where all messages in a batch may be redelivered on failure.
  • MinimizedWindowLower throughput with individual completion. Smaller failure window where only one message may be redelivered.

EnableBatchDatabaseOperations

Gets or sets a value indicating whether to enable batch database operations.

public bool EnableBatchDatabaseOperations { get; set; }

Property Value

bool

The current EnableBatchDatabaseOperations value.

MaxAttempts

Gets or sets the maximum number of processing attempts for a message before marking it as permanently failed. This setting implements retry policies and determines message reliability characteristics.

[Range(1, 2147483647)]
public int MaxAttempts { get; set; }

Property Value

int

The current MaxAttempts value.

MaxPayloadBytes

Gets or sets the maximum stored-payload length, in bytes, enforced when the outbox re-reads a staged message for publication — before the payload is handed to the transport (defense-in-depth DoS hardening at the outbox-read ingress). An over-limit stored payload is rejected before dispatch.

[Range(1, 2147483647)]
public int? MaxPayloadBytes { get; set; }

Property Value

int?

The maximum payload length in bytes. Default is 4 MiB (bounded by default so the guard is never inert). Set to null to opt out (unbounded) for larger legitimate payloads.

MessageTypes

Gets the message types the outbox may materialise from a stored message-type name.

public IList<Type> MessageTypes { get; set; }

Property Value

IList<Type>

The types this host stages and reads back. Empty by default, which resolves nothing.

Remarks

A staged row's message-type name is data read back out of the outbox table, and in any deployment where something other than this host can write that table it is attacker-influenced data. Resolving it by searching the loaded assemblies lets the stored string select a type the host never intended to deserialize, whose constructors and property setters then run during deserialization — the deserialization gadget shape. Constraining the search by an interface narrows the reachable set but does not bound it: the set is still "whatever happens to be loaded".

This list is the bound. Resolution consults it and nothing else, so the reachable set is fixed at composition time by the host rather than discovered at runtime from the value being resolved. A name that is not on it does not resolve, however plausible it looks and whatever assembly defines it.

The default is empty, and empty means nothing resolves. That is deliberate: a default that fell back to a search would leave every host that never configured the list exactly as exposed as before, while reading as though the setting had addressed it.

PerRunTotal

Gets or sets the maximum number of messages to process in a single outbox processing run. This setting controls the overall throughput and memory usage during batch processing operations.

[Range(1, 2147483647)]
public int PerRunTotal { get; set; }

Property Value

int

The current PerRunTotal value.

ProducerBatchSize

Gets or sets the batch size for message production operations when saving messages to the outbox. Larger batch sizes improve throughput but increase memory usage and transaction scope.

[Range(1, 2147483647)]
public int ProducerBatchSize { get; set; }

Property Value

int

The current ProducerBatchSize value.

QueueCapacity

Gets or sets the maximum capacity of the message queue for buffering pending outbox messages. This setting affects memory usage and the ability to handle message processing bursts.

[Range(1, 2147483647)]
public int QueueCapacity { get; set; }

Property Value

int

The current QueueCapacity value.

SingleActiveWriter

Gets or sets a value indicating whether this instance is the single active writer of the outbox and therefore takes responsibility for the exactly-once guarantee itself, opting out of leadership fencing.

public bool SingleActiveWriter { get; set; }

Property Value

bool

false (the safe default). When a leader election is registered, the outbox is fenced by default; on stores that record the fencing high-water durably (PostgreSQL, Oracle, MongoDB) a superseded leader cannot claim and complete messages it no longer owns. The SQL Server store derives its high-water from the outbox rows, so a cleanup that purges sent rows resets it and the advance overwrites rather than taking the maximum — treat its leadership fence as best-effort; the per-message lease still prevents two processors claiming the same message. Set to true — via the outbox builder's AsSingleWriter() — to assert that exactly one process drains this outbox (a topology the caller owns), which runs the drain unfenced even when a leader election is registered for other resources. The opt-out is logged at startup so the downgrade is observable, never silent.

Remarks

This is a positive topology assertion ("I am the single active writer"), not a switch that disables a safety check. It only affects the outbox drain; a registered leader election still governs any other resources (leases, scheduled jobs). Enabling it in a genuinely multi-writer deployment reopens the split-brain window fencing exists to close, so it must reflect a real single-active-writer topology.

Methods

Balanced()

Creates options balanced between throughput and reliability.

public static OutboxDeliveryOptions Balanced()

Returns

OutboxDeliveryOptions

A new OutboxDeliveryOptions instance with balanced settings.

Remarks

Settings:

  • PerRunTotal: 1,000
  • BatchSize: 100 (producer and consumer)
  • ParallelProcessingDegree: 4
  • EnableDynamicBatchSizing: false
  • DeliveryGuarantee: AtLeastOnce

Trade-offs:

  • Good throughput (3-5K messages/second)
  • Moderate failure window (batch redelivery ~100 messages)
  • Reasonable memory usage

Best for: General purpose workloads, most applications.

HighReliability()

Creates options optimized for maximum reliability.

public static OutboxDeliveryOptions HighReliability()

Returns

OutboxDeliveryOptions

A new OutboxDeliveryOptions instance configured for high reliability.

Remarks

Settings:

  • PerRunTotal: 100
  • BatchSize: 10 (producer and consumer)
  • ParallelProcessingDegree: 1 (sequential)
  • EnableDynamicBatchSizing: false
  • DeliveryGuarantee: MinimizedWindow

Trade-offs:

  • Lower throughput (1-2K messages/second)
  • Smallest failure window (individual message redelivery)
  • Sequential processing preserves ordering

Best for: Financial transactions, critical notifications, ordered processing.

HighThroughput()

Creates options optimized for maximum throughput.

public static OutboxDeliveryOptions HighThroughput()

Returns

OutboxDeliveryOptions

A new OutboxDeliveryOptions instance configured for high throughput.

Remarks

Settings:

  • PerRunTotal: 10,000
  • BatchSize: 1,000 (producer and consumer)
  • ParallelProcessingDegree: 8
  • EnableDynamicBatchSizing: true
  • DeliveryGuarantee: AtLeastOnce

Trade-offs:

  • Highest throughput (10K+ messages/second)
  • Larger failure window (batch redelivery ~1,000 messages)
  • Higher memory usage

Best for: Event sourcing, analytics, high-volume notifications.

Validate(OutboxDeliveryOptions)

Validates the configured option values.

public static string? Validate(OutboxDeliveryOptions options)

Parameters

options OutboxDeliveryOptions

The options instance to validate.

Returns

string

An error message if validation fails; otherwise null .

WithBatchSize(int, int?)

Creates a copy with the specified batch sizes.

public OutboxDeliveryOptions WithBatchSize(int producerBatchSize, int? consumerBatchSize = null)

Parameters

producerBatchSize int

The producer batch size.

consumerBatchSize int?

The consumer batch size. If null, uses the producerBatchSize value.

Returns

OutboxDeliveryOptions

A new OutboxDeliveryOptions instance with the updated batch sizes.

Remarks

This method creates a shallow clone and modifies only the batch size properties. Use this to customize a preset without modifying the original:

var options = OutboxDeliveryOptions.HighThroughput().WithBatchSize(500);

WithDeliveryGuarantee(OutboxDeliveryGuarantee)

Creates a copy with the specified delivery guarantee.

public OutboxDeliveryOptions WithDeliveryGuarantee(OutboxDeliveryGuarantee guarantee)

Parameters

guarantee OutboxDeliveryGuarantee

The delivery guarantee level.

Returns

OutboxDeliveryOptions

A new OutboxDeliveryOptions instance with the updated guarantee.

Remarks

This method creates a shallow clone and modifies only the delivery guarantee. Use this to customize a preset without modifying the original:

var options = OutboxDeliveryOptions.Balanced().WithDeliveryGuarantee(OutboxDeliveryGuarantee.MinimizedWindow);

WithMaxAttempts(int)

Creates a copy with the specified maximum retry attempts.

public OutboxDeliveryOptions WithMaxAttempts(int maxAttempts)

Parameters

maxAttempts int

The maximum number of processing attempts.

Returns

OutboxDeliveryOptions

A new OutboxDeliveryOptions instance with the updated retry count.

Remarks

This method creates a shallow clone and modifies only the max attempts setting. Use this to customize a preset without modifying the original:

var options = OutboxDeliveryOptions.Balanced().WithMaxAttempts(7);

WithMessageTypes(params Type[])

Creates a copy that also permits the specified message types to be resolved from a stored message-type name.

public OutboxDeliveryOptions WithMessageTypes(params Type[] messageTypes)

Parameters

messageTypes Type[]

The message types this host stages and reads back.

Returns

OutboxDeliveryOptions

A new OutboxDeliveryOptions instance including the supplied types.

Examples

var options = OutboxDeliveryOptions.Balanced()
    .WithMessageTypes(typeof(OrderPlaced), typeof(OrderShipped));

Exceptions

ArgumentNullException

messageTypes is null.

ArgumentException

One of the supplied types is null.

WithParallelDegree(int)

Creates a copy with the specified parallel processing degree.

public OutboxDeliveryOptions WithParallelDegree(int degree)

Parameters

degree int

The degree of parallelism for batch processing.

Returns

OutboxDeliveryOptions

A new OutboxDeliveryOptions instance with the updated parallelism.

Remarks

This method creates a shallow clone and modifies only the parallelism setting. Use this to customize a preset without modifying the original:

var options = OutboxDeliveryOptions.HighThroughput().WithParallelDegree(4);

WithTimeout(TimeSpan)

Creates a copy with the specified batch processing timeout.

public OutboxDeliveryOptions WithTimeout(TimeSpan timeout)

Parameters

timeout TimeSpan

The timeout for processing a batch of messages.

Returns

OutboxDeliveryOptions

A new OutboxDeliveryOptions instance with the updated timeout.

Remarks

This method creates a shallow clone and modifies only the timeout setting. Use this to customize a preset without modifying the original:

var options = OutboxDeliveryOptions.HighThroughput().WithTimeout(TimeSpan.FromMinutes(15));