Interface ISagaTimeoutStore
- Namespace
- Excalibur.Saga.Abstractions
- Assembly
- Excalibur.Saga.dll
Provides persistent storage for saga timeout requests. Implementations enable sagas to schedule timeout messages that are delivered after a specified delay.
public interface ISagaTimeoutStore : IServiceProvider
- Inherited Members
Remarks
Timeout stores must be reliable across process restarts. When a process restarts, previously scheduled timeouts must still be delivered. This is achieved by persisting timeout metadata to durable storage (e.g., SQL Server, Redis, MongoDB).
The ClaimDueTimeoutsAsync(DateTimeOffset, int, CancellationToken) method is called periodically by a background service to poll for timeouts ready for delivery. It atomically leases due timeouts to the calling processor so that, under a multi-instance deployment, each due timeout is claimed and delivered by exactly one processor at a time.
GetDueTimeoutsAsync(DateTimeOffset, CancellationToken) and ClaimDueTimeoutsAsync(DateTimeOffset, int, CancellationToken) are deliberately
distinct operations. GetDueTimeoutsAsync(DateTimeOffset, CancellationToken) is a read-only diagnostic query used
by monitoring and dashboard tooling to observe due timeouts without side effects; it never
leases or mutates state. ClaimDueTimeoutsAsync(DateTimeOffset, int, CancellationToken) is the delivery-path operation
that atomically leases timeouts so exactly one processor delivers each one. Callers driving
delivery must use ClaimDueTimeoutsAsync(DateTimeOffset, int, CancellationToken), never GetDueTimeoutsAsync(DateTimeOffset, CancellationToken).
A future ISagaTimeoutStoreAdmin split could separate the diagnostic surface from the
delivery surface if the interface grows further.
Methods
CancelAllTimeoutsAsync(string, CancellationToken)
Cancels all pending timeouts for a saga instance.
Task CancelAllTimeoutsAsync(string sagaId, CancellationToken cancellationToken)
Parameters
sagaIdstringThe saga identifier whose timeouts should be cancelled.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- Task
A task representing the asynchronous cancellation operation.
Remarks
This method is called when a saga completes or is terminated to clean up any pending timeouts that are no longer needed.
CancelTimeoutAsync(string, string, CancellationToken)
Cancels a specific timeout by its identifier.
Task CancelTimeoutAsync(string sagaId, string timeoutId, CancellationToken cancellationToken)
Parameters
sagaIdstringThe saga identifier that owns the timeout.
timeoutIdstringThe unique timeout identifier to cancel.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- Task
A task representing the asynchronous cancellation operation.
Remarks
Cancellation is idempotent. Cancelling a non-existent or already-delivered timeout completes without error.
ClaimDueTimeoutsAsync(DateTimeOffset, int, CancellationToken)
Atomically claims up to batchSize timeouts that are due for delivery
as of the specified time, leasing them to this processor so that no other processor can
claim the same timeout while the lease is held.
Task<IReadOnlyList<ClaimedSagaTimeout>> ClaimDueTimeoutsAsync(DateTimeOffset asOf, int batchSize, CancellationToken cancellationToken)
Parameters
asOfDateTimeOffsetThe reference time for determining which timeouts are due.
batchSizeintThe maximum number of timeouts to claim in this call.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- Task<IReadOnlyList<ClaimedSagaTimeout>>
A read-only list of newly claimed timeouts where DueAt is less than or equal to
asOf, ordered by DueAt ascending. Only timeouts that were unclaimed, or whose previous lease has expired, are returned.
Remarks
A claimed timeout is leased to the calling processor for an implementation-defined lease duration. Two concurrent calls to this method, from the same or different processor instances, never return the same timeout while its lease is active -- this is what makes delivery exactly-once-at-a-time under a multi-instance deployment.
If the processor crashes (or otherwise fails to call MarkDeliveredAsync(ClaimedSagaTimeout, CancellationToken)) after claiming a timeout, the lease expires and another processor may re-claim and re-deliver it. This preserves the store's documented at-least-once delivery guarantee -- consumers of delivered timeouts must remain idempotent.
GetDueTimeoutsAsync(DateTimeOffset, CancellationToken)
Returns the timeouts that are due for delivery as of the specified time, without leasing or claiming them.
Task<IReadOnlyList<SagaTimeout>> GetDueTimeoutsAsync(DateTimeOffset asOf, CancellationToken cancellationToken)
Parameters
asOfDateTimeOffsetThe reference time for determining which timeouts are due.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- Task<IReadOnlyList<SagaTimeout>>
A read-only list of timeouts where DueAt is less than or equal to
asOf, ordered by DueAt ascending.
Remarks
This is a read-only diagnostic query intended for monitoring and dashboard tooling to observe stuck or overdue timeouts. It does not lease or mutate any state, and repeated calls may return the same timeouts. Callers driving delivery must use ClaimDueTimeoutsAsync(DateTimeOffset, int, CancellationToken) instead.
MarkDeliveredAsync(ClaimedSagaTimeout, CancellationToken)
Retires a delivered timeout, removing it from the pending timeout list, provided the caller still holds the claim it is completing.
Task<SagaTimeoutRetirementOutcome> MarkDeliveredAsync(ClaimedSagaTimeout claim, CancellationToken cancellationToken)
Parameters
claimClaimedSagaTimeoutThe claim obtained from ClaimDueTimeoutsAsync(DateTimeOffset, int, CancellationToken) for the timeout that was delivered.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- Task<SagaTimeoutRetirementOutcome>
Retired when the caller held the current claim and the row was removed; Superseded when it did not, in which case nothing was removed and the caller must not report the timeout as delivered.
Remarks
Retirement is claim-conditional, and that is the whole point of taking a claim. A processor that stalls past its lease loses the timeout to another processor, which re-claims and re-delivers it. When the stalled processor resumes it must not remove a row it no longer owns: doing so destroys the live claimant's ability to retry, and the saga then waits forever for a timeout that no longer exists. Implementations MUST make the ownership test and the removal one atomic step, not a read followed by a delete.
This call is NOT unconditional and must not be treated as a formality. It retires the row on the strength of a claim, so a caller that has not actually delivered the timeout must not call it. An earlier contract described marking delivery as idempotent, which was true — a repeat removed nothing — but it answered the wrong question and was read as licence to call it on paths where nothing had been delivered.
ScheduleTimeoutAsync(SagaTimeout, CancellationToken)
Schedules a timeout for delivery at the specified due time.
Task ScheduleTimeoutAsync(SagaTimeout timeout, CancellationToken cancellationToken)
Parameters
timeoutSagaTimeoutThe timeout to schedule.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- Task
A task representing the asynchronous scheduling operation.