Class AppendCommitBoundary
- Namespace
- Excalibur.EventSourcing
- Assembly
- Excalibur.EventSourcing.Abstractions.dll
Preserves commit certainty across a complete append, including its cleanup, so that Failed cannot be reported for an append that may have committed.
public sealed class AppendCommitBoundary
- Inheritance
-
AppendCommitBoundary
- Inherited Members
Remarks
AppendAsync(string, string, IEnumerable<IDomainEvent>, long, CancellationToken) permits Failed — which states that nothing was written — only where non-commit is established. The difficulty is that the place a store learns it failed is usually a single exception handler spanning the whole operation, with no record of whether the commit was ever dispatched. A handler in that position cannot tell a fault that preceded the commit from a commit that landed and lost its acknowledgement, so it cannot support the claim — and a caller told "nothing was written" does not reconcile, which is how a durable write becomes invisible to everything downstream.
This type closes that by construction rather than by discipline. Wrap the append in
ExecuteAsync(Func<AppendCommitBoundary, ValueTask<AppendResult>>), call MarkDispatched() immediately before the commit is sent
and MarkAcknowledged(AppendResult) once it is known durable, then filter the store's own failure
handler on !Dispatched:
catch (Exception ex) when (!state.Dispatched && ex is MyProviderException)
{
return AppendResult.CreateFailure(ex.Message);
}
With that filter the Failed arm is only reachable when the commit was never dispatched, so non-commit is established wherever it is returned and no author has to remember the rule. Anything that escapes after dispatch is converted here to Unknown, which is the outcome defined for a commit whose fate cannot be determined. A store that can probe for its own committed events — reading them back by identity — is strictly better off doing so first, because a probe can distinguish landed from taken from indeterminate; this boundary is the floor beneath that, for the paths a probe cannot reach and for stores that have none.
The state transitions are deliberately one-way. There is no setter that can un-dispatch an append, because the only use for one would be to re-open the hole this type exists to close.
Properties
Acknowledged
Gets the result of a commit already known to be durable, if one has been acknowledged.
public AppendResult? Acknowledged { get; }
Property Value
- AppendResult
The acknowledged result, or null while no commit is known durable.
Dispatched
Gets a value indicating whether the commit has been dispatched to the provider.
public bool Dispatched { get; }
Property Value
- bool
true once MarkDispatched() or MarkAcknowledged(AppendResult) has been called; otherwise false. Filter a failure handler that reports Failed on this being false.
Methods
ExecuteAsync(Func<AppendCommitBoundary, ValueTask<AppendResult>>)
Runs an append inside the boundary, converting any post-dispatch fault into Unknown rather than letting it be reported as a failure.
public static ValueTask<AppendResult> ExecuteAsync(Func<AppendCommitBoundary, ValueTask<AppendResult>> operation)
Parameters
operationFunc<AppendCommitBoundary, ValueTask<AppendResult>>The append, which receives the boundary state to mark.
Returns
- ValueTask<AppendResult>
The operation's own result; the acknowledged result if a durable commit was followed by a fault in cleanup; or Unknown if a fault followed dispatch.
Exceptions
- ArgumentNullException
operationis null.- InvalidOperationException
An ambient transaction is in scope.
MarkAcknowledged(AppendResult)
Records a commit now known to be durable, so no later fault can downgrade it.
public void MarkAcknowledged(AppendResult result)
Parameters
resultAppendResultThe successful append result to preserve.
Remarks
Implies Dispatched: a commit cannot be acknowledged without having been sent. Refusing a non-success result is deliberate — "acknowledged" names a durable commit, and admitting a failure here would let a later fault return that failure as though it had been established.
Exceptions
- ArgumentNullException
resultis null.- ArgumentException
resultdoes not report success.
MarkDispatched()
Records that the commit has been sent to the provider. Call immediately before dispatching it.
public void MarkDispatched()
Remarks
Idempotent and one-way. From this point a fault can no longer establish non-commit, which is
exactly what the !Dispatched filter on the store's failure handler relies on.