Interface IBackoffSchedulableInboxStore
An optional capability for IInboxStore implementations that durably record a per-entry next-attempt time, so a failed message's computed backoff delay actually throttles when it is re-claimed for retry.
public interface IBackoffSchedulableInboxStore
- Extension Methods
Remarks
This is a segregated capability interface (composition, NOT inheritance of IInboxStore) so that IInboxStore stays within the Interface Segregation threshold, mirroring how IBackoffSchedulableOutboxStore segregates the equivalent outbox capability.
Unlike the outbox (keyed by message id alone), the inbox is keyed by the composite
(messageId, handlerType) -- the same message can be processed independently by multiple
handlers -- so the backoff schedule is recorded per (messageId, handlerType) entry and carries
the current retryCount the processor used to compute the delay.
Without it, a failed entry is marked Failed via
MarkFailedAsync(string, string, string, CancellationToken),
which records the failure but cannot carry the next-attempt time -- so the re-admission claim
re-delivers the entry on a fixed window and the advertised exponential backoff never throttles
re-delivery. The processor computes now + IBackoffCalculator.CalculateDelay(attempt) and passes
the absolute next-attempt time here; the store only persists it. The claim predicate then excludes the
entry 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, string, CancellationToken) and its existing fixed re-admission window (today's behavior), so no existing store is broken (the fail-open pattern, matching IBackoffSchedulableOutboxStore).
Methods
MarkFailedWithBackoffAsync(string, string, string, int, DateTimeOffset, CancellationToken)
Marks an inbox entry as failed for a specific handler and records the time before which it must NOT be re-claimed for retry, applying the per-entry backoff schedule.
ValueTask<InboxMarkFailedOutcome> MarkFailedWithBackoffAsync(string messageId, string handlerType, string errorMessage, int retryCount, DateTimeOffset nextAttemptAt, CancellationToken cancellationToken)
Parameters
messageIdstringThe unique identifier of the message that failed.
handlerTypestringThe fully qualified type name of the handler that failed.
errorMessagestringThe error description or exception message.
retryCountintThe current retry attempt count.
nextAttemptAtDateTimeOffsetThe absolute (computed) time before which the entry must not be re-claimed. Typically
now + IBackoffCalculator.CalculateDelay(attempt), computed by the caller.cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- ValueTask<InboxMarkFailedOutcome>
Applied when the entry was mutated and the backoff was scheduled — scheduling is part of applying, so it has no separate outcome; EntryNotFound when no such entry exists in the caller's tenant scope; AlreadyProcessed when the entry is present but terminal and the transition was refused, in which case no backoff is scheduled either.
Remarks
After this call, the entry MUST NOT be returned by the re-admission claim
(GetAllTenantsFailedEntriesAsync(int, DateTimeOffset?, int, CancellationToken)) until nextAttemptAt has
elapsed, so the computed backoff delay genuinely throttles re-delivery.
Carries the same three obligations as MarkFailedAsync(string, string, string, CancellationToken) about the state of an entry: an absent entry returns EntryNotFound rather than throwing, a refused terminal entry is reported rather than silently ignored, and the outcome is decided by the statement that performs the write rather than by a read taken after it.
Those obligations are about the ENTRY. They do not cover the capability itself being absent. A decorator may implement this interface in order to FORWARD it and still wrap an inner store that cannot schedule. Such a decorator reports SupportsBackoffScheduling as false, and calling this member anyway is a programming error — the caller ignored the documented probe — so it throws NotSupportedException rather than degrading to a plain mark-failed. Scheduling is part of applying here, so a silent degrade would return Applied while asserting a schedule that does not exist, and nothing downstream would ever learn otherwise.
Consumer obligation: probe SupportsBackoffScheduling before calling this member. A bare type test is not sufficient — it is satisfied by a forwarding decorator whose inner store lacks the capability.
Exceptions
- ArgumentException
Thrown when
messageIdorhandlerTypeis null or empty.- ArgumentNullException
Thrown when
errorMessageis null.- NotSupportedException
Thrown when the implementation declares this capability in order to forward it but the store behind it cannot schedule a backoff — that is, when SupportsBackoffScheduling is false.