Class GovernanceOutboxOptions

Namespace

AsiBackbone.Core.Outbox

Assembly

AsiBackbone.Core.dll

Provides provider-neutral retry timing, poison-message, and optional claim/lease options for outbox drain processing.

public sealed class GovernanceOutboxOptions

Inheritance

object

GovernanceOutboxOptions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

These options control default retry timestamps when a downstream emitter does not provide its own retry-after value. Claim leasing is enabled by default and requires a claim-capable outbox store; hosts supplying a store that does not implement IGovernanceOutboxClaimStore must set UseClaimLeases to false and accept the duplicate-emission behavior that follows from it.

Fields

DefaultClaimPageSize

Gets the default number of claimed entries drained under a single lease before the drain claims again.

public const int DefaultClaimPageSize = 10

Field Value

int

DefaultDeadLetterReasonCode

Gets the stable default reason code used when the drain dead-letters an entry after the configured retry threshold is reached.

public const string DefaultDeadLetterReasonCode = "outbox.max_retry_attempts_exceeded"

Field Value

string

DefaultDeadLetterReasonMessage

Gets the stable default reason message used when the drain dead-letters an entry after the configured retry threshold is reached.

public const string DefaultDeadLetterReasonMessage = "Governance outbox entry exceeded the configured maximum retry attempts."

Field Value

string

DefaultMaxClaimAttempts

Gets the default number of claims permitted before the drain dead-letters an entry that never reaches a terminal state.

public const int DefaultMaxClaimAttempts = 5

Field Value

int

DefaultMaxClaimAttemptsReasonCode

Gets the stable default reason code used when the drain dead-letters an entry after the configured claim threshold is reached.

public const string DefaultMaxClaimAttemptsReasonCode = "outbox.max_claim_attempts_exceeded"

Field Value

string

DefaultMaxClaimAttemptsReasonMessage

Gets the stable default reason message used when the drain dead-letters an entry after the configured claim threshold is reached.

public const string DefaultMaxClaimAttemptsReasonMessage = "Governance outbox entry exceeded the configured maximum claim attempts without reaching a terminal state."

Field Value

string

Properties

ClaimLeaseDuration

Gets or sets the lease duration used when UseClaimLeases is enabled.

public TimeSpan ClaimLeaseDuration { get; set; }

Property Value

TimeSpan

ClaimPageSize

Gets or sets the maximum number of claimed entries drained under a single lease before the drain claims again.

public int ClaimPageSize { get; set; }

Property Value

int

Remarks

A drain pass claims entries in pages of this size rather than leasing an entire batch at once, so a slow emitter cannot exhaust one lease across the whole batch and leave later entries reclaimable by a peer while they are still in flight. Each page is leased from the clock reading taken when that page is claimed.

ClaimWorkerId

Gets or sets the worker, process, node, or partition identifier used when UseClaimLeases is enabled.

public string? ClaimWorkerId { get; set; }

Property Value

string

Remarks

Defaults to DefaultClaimWorkerId. Setting this to null or whitespace while UseClaimLeases is enabled fails validation.

DeadLetterOnMaxClaimAttempts

Gets or sets a value indicating whether entries are dead-lettered when MaxClaimAttempts is reached.

public bool DeadLetterOnMaxClaimAttempts { get; set; }

Property Value

bool

Remarks

When disabled, an entry that exceeds the claim threshold is still drained normally, which restores the unbounded reclaim behavior this threshold exists to bound.

DeadLetterOnMaxRetryAttempts

Gets or sets a value indicating whether entries are dead-lettered when MaxRetryAttempts is reached.

public bool DeadLetterOnMaxRetryAttempts { get; set; }

Property Value

bool

DeadLetterReasonCode

Gets or sets the provider-neutral reason code recorded when the configured retry threshold is reached.

public string DeadLetterReasonCode { get; set; }

Property Value

string

DeadLetterReasonMessage

Gets or sets the provider-neutral reason message recorded when the configured retry threshold is reached.

public string DeadLetterReasonMessage { get; set; }

Property Value

string

DefaultClaimWorkerId

Gets the default worker identifier used when claim leases are enabled and the host does not supply one.

public static string DefaultClaimWorkerId { get; }

Property Value

string

Remarks

The value combines the machine name and the current process identifier so that replicas of the same deployment do not share a claim owner by default. Hosts that run several drain workers in one process, or that need a stable identifier across restarts, should set ClaimWorkerId explicitly.

DeferredDelay

Gets or sets the default delay applied when an emitter returns a pending or deferred result without a retry-after timestamp.

public TimeSpan DeferredDelay { get; set; }

Property Value

TimeSpan

MaxClaimAttempts

Gets or sets the number of claims permitted before the drain dead-letters an entry that has never reached a terminal state.

public int MaxClaimAttempts { get; set; }

Property Value

int

Remarks

An emitter that hangs or is killed mid-emission leaves the entry claimed but not failed, so its retry count never advances and the retry-based poison-message policy never applies. This threshold bounds that loop. The check runs before emission, using the claim count recorded by the store, and dead-lettering is gated by DeadLetterOnMaxClaimAttempts.

MaxClaimAttemptsReasonCode

Gets or sets the provider-neutral reason code recorded when the configured claim threshold is reached.

public string MaxClaimAttemptsReasonCode { get; set; }

Property Value

string

MaxClaimAttemptsReasonMessage

Gets or sets the provider-neutral reason message recorded when the configured claim threshold is reached.

public string MaxClaimAttemptsReasonMessage { get; set; }

Property Value

string

MaxRetryAttempts

Gets or sets the maximum number of failed emission attempts permitted before the drain applies its poison-message policy.

public int MaxRetryAttempts { get; set; }

Property Value

int

Remarks

The threshold counts the failure currently being processed. A value of 1 dead-letters the first failed attempt when DeadLetterOnMaxRetryAttempts is enabled.

RetryDelay

Gets or sets the default delay applied after a transient emission failure or unexpected emitter exception.

public TimeSpan RetryDelay { get; set; }

Property Value

TimeSpan

UseClaimLeases

Gets or sets a value indicating whether the drain should claim outbox entries before provider emission when the store supports claim leases.

public bool UseClaimLeases { get; set; }

Property Value

bool

Remarks

This is enabled by default because the alternative path allows two hosts draining the same durable outbox to emit the same envelope twice. The drain throws when this is enabled and the configured store does not implement IGovernanceOutboxClaimStore; a host supplying such a store must opt out explicitly. Claiming coordinates workers before emission and does not by itself create an exactly-once delivery guarantee.

Methods

Validate()

Validates the configured outbox retry, poison-message, timing, and claim options.

public void Validate()

Exceptions

InvalidOperationException

Thrown when a retry threshold, reason, delay, or claim lease option is invalid.