Table of Contents

Interface IBackoffSchedulableOutboxStore

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

An optional capability for polling IOutboxStore implementations that durably record a per-message next-attempt time, so a failed message's computed backoff delay actually throttles when it is re-claimed for retry.

public interface IBackoffSchedulableOutboxStore
Extension Methods

Remarks

This is a segregated capability interface (composition, NOT inheritance of IOutboxStore) so that IOutboxStore stays within the Interface Segregation threshold, mirroring how IOutboxStoreAdmin, IOutboxStoreBatch, and IDeadLetterableOutboxStore segregate optional outbox capabilities.

Without it, a failed message is marked Failed via MarkFailedAsync(string, string, int, CancellationToken), which records the failure but cannot carry the next-attempt time -- so the polling claim re-delivers the message as soon as its lease expires and the advertised exponential backoff never throttles re-delivery. The processor computes now + backoffCalculator.CalculateDelay(attempt) and passes the absolute next-attempt time here. The store does NOT persist it verbatim: it persists the LATER of that instant and its own configured failure-backoff floor F (see the method contract below). The claim predicate then excludes the message until that time has elapsed (WHERE NextAttemptAt IS NULL OR NextAttemptAt <= @now).

Stores that do not implement this capability degrade gracefully: the processor falls back to MarkFailedAsync(string, string, int, CancellationToken) (today's behavior), so no existing store is broken (the fail-open pattern, matching IDeadLetterableOutboxStore).

Methods

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

Marks a message as failed and records the time before which it must NOT be re-claimed for retry, applying the per-message backoff schedule.

ValueTask MarkFailedWithBackoffAsync(string messageId, string errorMessage, int retryCount, DateTimeOffset nextAttemptAt, 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.

nextAttemptAt DateTimeOffset

The caller-computed earliest next attempt, typically now + IBackoffCalculator.CalculateDelay(attempt). A LOWER bound requested by the caller, not the final schedule: the store composes it with its own floor F and persists whichever is later, so this value can defer the next attempt beyond F but can never bring it inside F.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask

A task that represents the asynchronous mark-failed-with-backoff operation.

Remarks

After this call, the message MUST NOT be returned by the claim predicate (GetUnsentMessagesAsync(int, CancellationToken)) until nextAttemptAt has elapsed, so the computed backoff delay genuinely throttles re-delivery.

Implementors: compose, do not substitute. The persisted next-attempt time MUST be the LATER of nextAttemptAt and the store's own configured failure-backoff floor F — the same floor the plain MarkFailedAsync(string, string, int, CancellationToken) path applies. Binding the caller's instant verbatim is a defect, not a permitted simplification: the default backoff calculator yields on the order of a second at the first attempt, so a store that substitutes rather than composes makes this capability WEAKEN the guarantee it exists to strengthen — the identical failure waits F without the capability and about a second with it.

Compose with a maximum rather than a conditional, so relaxing the floor below F is not something ordinary use can express. Compute the floor term on whichever clock the store's own claim predicate compares against — the database server's where the store has one, the injected TimeProvider where the store is deliberately client-clocked — so the composition introduces no clock the provider was not already trusting.

Exceptions

ArgumentException

Thrown when messageId is null or empty.

ArgumentNullException

Thrown when errorMessage is null.