Table of Contents

Class SqlServerSagaTimeoutStore

Namespace
Excalibur.Saga.SqlServer
Assembly
Excalibur.Saga.SqlServer.dll

SQL Server implementation of ISagaTimeoutStore for persistent saga timeout storage.

public sealed class SqlServerSagaTimeoutStore : ISagaTimeoutStore, IServiceProvider, ISagaTimeoutFailureStore, ISagaTimerRecoveryStore
Inheritance
SqlServerSagaTimeoutStore
Implements
Inherited Members

Remarks

This implementation uses Dapper for all database operations and provides:

  • Durable timeout storage that survives process restarts
  • Efficient polling via indexed DueAt column
  • OpenTelemetry activity spans for observability

This class supports two constructor patterns:

  • Simple: Connection string for most users
  • Advanced: Connection factory for multi-database, pooling, or IDb integration

Constructors

SqlServerSagaTimeoutStore(Func<SqlConnection>, ILogger<SqlServerSagaTimeoutStore>, ITenantContext)

Initializes a new instance of the SqlServerSagaTimeoutStore class with a connection factory.

public SqlServerSagaTimeoutStore(Func<SqlConnection> connectionFactory, ILogger<SqlServerSagaTimeoutStore> logger, ITenantContext tenantContext)

Parameters

connectionFactory Func<SqlConnection>

A factory function that creates SqlConnection instances. The caller is responsible for ensuring the factory returns properly configured connections.

logger ILogger<SqlServerSagaTimeoutStore>

The logger instance.

tenantContext ITenantContext

The tenant context. Required: this store partitions timeouts by tenant and resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.

Remarks

This is the advanced constructor for scenarios that need custom connection management:

  • Multi-database setups with marker interfaces (e.g., IDomainDb, ISagaDb)
  • Custom connection pooling
  • Integration with IDb abstraction

SqlServerSagaTimeoutStore(Func<SqlConnection>, IOptions<SqlServerSagaTimeoutStoreOptions>, ILogger<SqlServerSagaTimeoutStore>, ITenantContext)

Initializes a new instance of the SqlServerSagaTimeoutStore class with a connection factory and options.

public SqlServerSagaTimeoutStore(Func<SqlConnection> connectionFactory, IOptions<SqlServerSagaTimeoutStoreOptions> options, ILogger<SqlServerSagaTimeoutStore> logger, ITenantContext tenantContext)

Parameters

connectionFactory Func<SqlConnection>

The connection factory.

options IOptions<SqlServerSagaTimeoutStoreOptions>

The saga timeout store options.

logger ILogger<SqlServerSagaTimeoutStore>

The logger instance.

tenantContext ITenantContext

The tenant context. Required: this store partitions timeouts by tenant and resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.

SqlServerSagaTimeoutStore(string, ILogger<SqlServerSagaTimeoutStore>, ITenantContext)

Initializes a new instance of the SqlServerSagaTimeoutStore class.

public SqlServerSagaTimeoutStore(string connectionString, ILogger<SqlServerSagaTimeoutStore> logger, ITenantContext tenantContext)

Parameters

connectionString string

The SQL Server connection string.

logger ILogger<SqlServerSagaTimeoutStore>

The logger instance.

tenantContext ITenantContext

The tenant context. Required: this store partitions timeouts by tenant and resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.

Remarks

This is the simple constructor for most users. Use SqlServerSagaTimeoutStore(Func<SqlConnection>, ILogger<SqlServerSagaTimeoutStore>, ITenantContext) for advanced scenarios like multi-database setups or custom connection pooling.

SqlServerSagaTimeoutStore(string, IOptions<SqlServerSagaTimeoutStoreOptions>, ILogger<SqlServerSagaTimeoutStore>, ITenantContext)

Initializes a new instance of the SqlServerSagaTimeoutStore class with options.

public SqlServerSagaTimeoutStore(string connectionString, IOptions<SqlServerSagaTimeoutStoreOptions> options, ILogger<SqlServerSagaTimeoutStore> logger, ITenantContext tenantContext)

Parameters

connectionString string

The SQL Server connection string.

options IOptions<SqlServerSagaTimeoutStoreOptions>

The saga timeout store options.

logger ILogger<SqlServerSagaTimeoutStore>

The logger instance.

tenantContext ITenantContext

The tenant context. Required: this store partitions timeouts by tenant and resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.

Methods

CancelAllTimeoutsAsync(string, CancellationToken)

Cancels all pending timeouts for a saga instance.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.