Table of Contents

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

sagaId string

The saga identifier whose timeouts should be cancelled.

cancellationToken CancellationToken

Token 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

sagaId string

The saga identifier that owns the timeout.

timeoutId string

The unique timeout identifier to cancel.

cancellationToken CancellationToken

Token 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

asOf DateTimeOffset

The reference time for determining which timeouts are due.

batchSize int

The maximum number of timeouts to claim in this call.

cancellationToken CancellationToken

Token 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

asOf DateTimeOffset

The reference time for determining which timeouts are due.

cancellationToken CancellationToken

Token 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

claim ClaimedSagaTimeout

The claim obtained from ClaimDueTimeoutsAsync(DateTimeOffset, int, CancellationToken) for the timeout that was delivered.

cancellationToken CancellationToken

Token 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

timeout SagaTimeout

The timeout to schedule.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

Task

A task representing the asynchronous scheduling operation.