Interface ISqlServerOperationExecutor
- Namespace
- Excalibur.EventSourcing.SqlServer
- Assembly
- Excalibur.EventSourcing.SqlServer.dll
Runs an operation at most once per stable identity, returning the original durable receipt on a retry.
public interface ISqlServerOperationExecutor
Remarks
Why this interface exists. The implementation is constructed by the consumer, in their own command pipeline, and called on their request path — so without a seam there is nothing to substitute in a test and nothing to wrap. A consumer wanting to assert "a retry with the same key did not append twice" had to reach a real SQL Server to do it, which is the wrong cost for a unit test of their own handler. It also lets a consumer decorate the call (logging, metrics, a tenant guard) without reimplementing the receipt protocol.
What it guarantees, in falsifiable terms. For a stable scope plus operationKey
and an immutable fingerprint, SQL commits at most one event append together with one durable
receipt. A replay returns the original aggregate identity, version and global positions WITHOUT
executing the action again. This is one committed append per operation identity — it is NOT
exactly-once execution of arbitrary side effects, and an operation that appends no events has no
receipt.
What it does not cover. Independent business commits, multiple aggregate saves in one operation, and effects outside the SQL transaction are all outside this contract. A caller that invents a fresh operation key for a retry gets a second execution, correctly: the key is the identity.
Methods
BindSourceAsync(string, ReadOnlyMemory<byte>, CancellationToken)
Binds this target to a source incarnation, refusing a source whose history was replaced.
Task BindSourceAsync(string source, ReadOnlyMemory<byte> sourceIdentity, CancellationToken cancellationToken)
Parameters
sourcestringThe configured source identity.
sourceIdentityReadOnlyMemory<byte>The source's database and capture identity, excluding values that advance normally.
cancellationTokenCancellationTokenCancels this attempt.
Returns
- Task
A task that completes when the binding is established or confirmed unchanged.
Exceptions
- SqlServerSourceChangedException
The bound source database, recovery fork or capture generation changed. Reconcile or rebuild target state before rebinding; restarting does not accept the new history.
ExecuteAsync(string, string, ReadOnlyMemory<byte>, Func<CancellationToken, Task>, CancellationToken)
Runs a single-append operation, or returns its original durable receipt without running it.
Task<SqlServerOperationResult> ExecuteAsync(string scope, string operationKey, ReadOnlyMemory<byte> fingerprint, Func<CancellationToken, Task> action, CancellationToken cancellationToken)
Parameters
scopestringA stable authenticated caller and operation namespace, or CDC source incarnation.
operationKeystringThe caller's stable retry key. Compared ordinally.
fingerprintReadOnlyMemory<byte>SHA-256 of immutable input, including target and original preconditions.
actionFunc<CancellationToken, Task>The handler. At most one nonempty event append is supported.
cancellationTokenCancellationTokenCancels this attempt; cancellation does not prove rollback.
Returns
- Task<SqlServerOperationResult>
The outcome, carrying the receipt when the operation appended events.