Table of Contents

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

string

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

MessageFailureKind?

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

bool

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

long?

The stream's current version after the append, or null when unavailable.

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

double

SessionToken

Gets the session token for session consistency.

public string? SessionToken { get; }

Property Value

string

Success

Gets a value indicating whether the append operation succeeded.

public bool Success { get; }

Property Value

bool

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

nextExpectedVersion long

The version the recognised events reached.

requestCharge double

The request charge consumed.

sessionToken string

The 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

expectedVersion long

The version the append required the stream to be at.

actualVersion long?

The stream's current version as the store read it, or null when the store detected the conflict without being able to read one.

requestCharge double

The 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

errorMessage string

The error message.

requestCharge double

The request charge consumed.

failureKind MessageFailureKind

The 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

nextExpectedVersion long

The next expected version.

requestCharge double

The request charge consumed.

sessionToken string

The 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

errorMessage string

The diagnostic reason.

requestCharge double

The observed request charge.

failureKind MessageFailureKind

Operational 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.