Class OracleSagaTimeoutStore
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
connectionFactoryFunc<OracleConnection>A factory that creates Oracle.ManagedDataAccess.Client.OracleConnection instances.
loggerILogger<OracleSagaTimeoutStore>The logger instance.
tenantContextITenantContextThe 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
connectionFactoryFunc<OracleConnection>The connection factory.
optionsIOptions<OracleSagaTimeoutStoreOptions>The saga timeout store options.
loggerILogger<OracleSagaTimeoutStore>The logger instance.
tenantContextITenantContextThe 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
connectionStringstringThe Oracle connection string.
loggerILogger<OracleSagaTimeoutStore>The logger instance.
tenantContextITenantContextThe 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
connectionStringstringThe Oracle connection string.
optionsIOptions<OracleSagaTimeoutStoreOptions>The saga timeout store options.
loggerILogger<OracleSagaTimeoutStore>The logger instance.
tenantContextITenantContextThe 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
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.
public 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.
public 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.
public 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.
public 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.
public 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.