Table of Contents

Class OracleSagaTimeoutStore

Namespace
Excalibur.Saga.Oracle
Assembly
Excalibur.Saga.Oracle.dll

Oracle implementation of ISagaTimeoutStore for persistent saga timeout storage.

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

Remarks

Uses Dapper with colon-prefixed Oracle bind variables (bound by name) and provides durable timeout storage that survives process restarts, efficient polling via the indexed DueAt column, and OpenTelemetry activity spans.

Constructors

OracleSagaTimeoutStore(Func<OracleConnection>, ILogger<OracleSagaTimeoutStore>, ITenantContext)

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

public OracleSagaTimeoutStore(Func<OracleConnection> connectionFactory, ILogger<OracleSagaTimeoutStore> logger, ITenantContext tenantContext)

Parameters

connectionFactory Func<OracleConnection>

A factory that creates Oracle.ManagedDataAccess.Client.OracleConnection instances.

logger ILogger<OracleSagaTimeoutStore>

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.

OracleSagaTimeoutStore(Func<OracleConnection>, IOptions<OracleSagaTimeoutStoreOptions>, ILogger<OracleSagaTimeoutStore>, ITenantContext)

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

public OracleSagaTimeoutStore(Func<OracleConnection> connectionFactory, IOptions<OracleSagaTimeoutStoreOptions> options, ILogger<OracleSagaTimeoutStore> logger, ITenantContext tenantContext)

Parameters

connectionFactory Func<OracleConnection>

The connection factory.

options IOptions<OracleSagaTimeoutStoreOptions>

The saga timeout store options.

logger ILogger<OracleSagaTimeoutStore>

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.

OracleSagaTimeoutStore(string, ILogger<OracleSagaTimeoutStore>, ITenantContext)

Initializes a new instance of the OracleSagaTimeoutStore class.

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

Parameters

connectionString string

The Oracle connection string.

logger ILogger<OracleSagaTimeoutStore>

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.

OracleSagaTimeoutStore(string, IOptions<OracleSagaTimeoutStoreOptions>, ILogger<OracleSagaTimeoutStore>, ITenantContext)

Initializes a new instance of the OracleSagaTimeoutStore class with options.

public OracleSagaTimeoutStore(string connectionString, IOptions<OracleSagaTimeoutStoreOptions> options, ILogger<OracleSagaTimeoutStore> logger, ITenantContext tenantContext)

Parameters

connectionString string

The Oracle connection string.

options IOptions<OracleSagaTimeoutStoreOptions>

The saga timeout store options.

logger ILogger<OracleSagaTimeoutStore>

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.