Interface IBackoffSchedulableOutboxStore
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
messageIdstringThe unique identifier of the message that failed.
errorMessagestringThe error description or exception message.
retryCountintThe current retry attempt count.
nextAttemptAtDateTimeOffsetThe 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.cancellationTokenCancellationTokenToken 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
messageIdis null or empty.- ArgumentNullException
Thrown when
errorMessageis null.