Class CloudAppendResult
- Namespace
- Excalibur.Data.CloudNative
- Assembly
- Excalibur.Data.Abstractions.dll
Represents the result of appending events to a cloud-native event store.
public sealed class CloudAppendResult
- Inheritance
-
CloudAppendResult
- Inherited Members
Properties
ErrorMessage
Gets the error message if the operation failed.
public string? ErrorMessage { get; }
Property Value
FailureKind
Gets the failure's classification (transient vs. permanent vs. poison), or null for success or concurrency conflict. Both CreateFailure(string, double, MessageFailureKind) and CreateUnknown(string, double, MessageFailureKind) supply this operational classification.
public MessageFailureKind? FailureKind { get; }
Property Value
Remarks
Required on every failed or unknown result so an unclassified failure is a compile error, not a silently-defaulted retry-forever or a silently-discarded piece of recoverable work — the resilience pipeline consuming this result needs to know which one it is looking at. This does not establish commit certainty: an Unknown result requires reconciliation even when transient.
IsConcurrencyConflict
Gets a value indicating whether the failure was due to a concurrency conflict.
public bool IsConcurrencyConflict { get; }
Property Value
NextExpectedVersion
Gets the next expected version for the aggregate after this append — or null when this result cannot state one.
public long? NextExpectedVersion { get; }
Property Value
Remarks
A failed append reports null rather than a number, because it has no version to
report and -1 is not free to borrow as a sentinel: under this store's version base -1
is the ordinary value meaning this stream does not exist. Reporting it after a failure
would hand a caller a number asserting the opposite of the truth, which they could pass straight
back as an expected version and create a stream that already holds events.
A concurrency conflict is the one failure that can state a version, and it states one only
when it measured one: where the store read the stream's actual version in order to detect the
conflict it reports that measured value here — including a genuine -1 when the conflict is
that the stream does not exist at all. Where the store detected the conflict by another route and
the version read did not succeed, it reports null.
Every value this property carries is one the store measured. It is never the caller's own
expected version echoed back, never a bound, and never derived from anything but a read. That is
what makes the two meanings of -1 separable: a -1 here is always "the stream
measurably does not exist", and "not measured" is null instead. A caller may pass
a measured version into a subsequent operation after applying its concurrency policy. For
Unknown, reconcile the original operation before rebasing or
regenerating events; a null version is not permission to retry as a new operation.
Outcome
Gets what the append actually did.
public CloudAppendOutcome Outcome { get; }
Property Value
- CloudAppendOutcome
The single outcome that holds for this result.
Remarks
Success and IsConcurrencyConflict are derived from this. Existing success handling remains compatible, but false does not prove rejection: callers must handle Unknown before retrying. Read this when the difference between an append written by this call and one recognised as already durable matters — see AlreadyCommitted.
RequestCharge
Gets the request charge (RUs for Cosmos DB, WCUs for DynamoDB).
public double RequestCharge { get; }
Property Value
SessionToken
Gets the session token for session consistency.
public string? SessionToken { get; }
Property Value
Success
Gets a value indicating whether the append operation succeeded.
public bool Success { get; }
Property Value
Remarks
True for Committed and for AlreadyCommitted alike: in both the events the caller asked to append are durable. False does not prove rollback: Unknown may represent a committed append.
Methods
CreateAlreadyCommitted(long, double, string?)
Creates a successful append result for events that were already durably present, which the store recognised as its own by identity rather than writing again.
public static CloudAppendResult CreateAlreadyCommitted(long nextExpectedVersion, double requestCharge, string? sessionToken = null)
Parameters
nextExpectedVersionlongThe version the recognised events reached.
requestChargedoubleThe request charge consumed.
sessionTokenstringThe session token for consistency.
Returns
- CloudAppendResult
A successful append result carrying AlreadyCommitted.
Remarks
Every committed-append identity probe reports through here rather than through CreateSuccess(long, double, string?), so the distinction survives the hop to the provider-neutral append result the repository reads.
CreateConcurrencyConflict(long, long?, double)
Creates a failed append result due to version mismatch.
public static CloudAppendResult CreateConcurrencyConflict(long expectedVersion, long? actualVersion, double requestCharge)
Parameters
expectedVersionlongThe version the append required the stream to be at.
actualVersionlong?The stream's current version as the store read it, or null when the store detected the conflict without being able to read one.
requestChargedoubleThe request charge consumed.
Returns
- CloudAppendResult
A failed append result indicating concurrency conflict.
Remarks
actualVersion takes only what a read returned. Pass the read's own result
straight through — never expectedVersion, never a bound, never a value derived
from anything but a read. The parameter is long? precisely so that a store which did
not measure has no way to type a number here: the violation is inexpressible rather than
merely discouraged.
A proven bound is not a measurement and does not belong here either, however soundly it was derived. This value is the version the stream is now at, and the value the next append must pass; a lower bound sent back in its place makes the caller reload to a point that may still be behind the tail, conflict again, and loop. Report null and let the caller reload.
When actualVersion is null the message states that the version
could not be determined rather than naming one, so the string a consumer reads never claims a
measurement that was not taken.
CreateFailure(string, double, MessageFailureKind)
Creates a failed append result with custom error.
public static CloudAppendResult CreateFailure(string errorMessage, double requestCharge, MessageFailureKind failureKind)
Parameters
errorMessagestringThe error message.
requestChargedoubleThe request charge consumed.
failureKindMessageFailureKindThe failure's classification (transient vs. permanent vs. poison), from Classify(Exception) (narrowed first against the provider's own known-transient signals, e.g. Cosmos 429, DynamoDB ProvisionedThroughputExceeded, Firestore RESOURCE_EXHAUSTED, since the shared classifier does not itself recognise provider-specific SDK exceptions). Required, not optional: an unclassified failure must be a compile error, not a silently-invented default — defaulting to transient invents infinite retry, defaulting to fatal discards recoverable work.
Returns
- CloudAppendResult
A failed append result, reporting no version.
Remarks
Nothing was appended, so the result states no version: NextExpectedVersion is null. Use CreateConcurrencyConflict(long, long?, double) for the one failure that has a version to report.
CreateSuccess(long, double, string?)
Creates a successful append result for events this call wrote.
public static CloudAppendResult CreateSuccess(long nextExpectedVersion, double requestCharge, string? sessionToken = null)
Parameters
nextExpectedVersionlongThe next expected version.
requestChargedoubleThe request charge consumed.
sessionTokenstringThe session token for consistency.
Returns
- CloudAppendResult
A successful append result.
CreateUnknown(string, double, MessageFailureKind)
Reports an atomic append whose commit outcome could not be established.
public static CloudAppendResult CreateUnknown(string errorMessage, double requestCharge, MessageFailureKind failureKind)
Parameters
errorMessagestringThe diagnostic reason.
requestChargedoubleThe observed request charge.
failureKindMessageFailureKindOperational classification; it does not establish commit certainty.
Returns
- CloudAppendResult
An unknown outcome without an asserted stream version.
Remarks
Preserve original identities and payloads for reconciliation; absence alone does not prove rollback.