Table of Contents

Class ClaimedSagaTimeout

Namespace
Excalibur.Saga.Abstractions
Assembly
Excalibur.Saga.dll

A saga timeout together with the claim the caller holds on it.

public sealed record ClaimedSagaTimeout : IEquatable<ClaimedSagaTimeout>
Inheritance
ClaimedSagaTimeout
Implements
Inherited Members

Remarks

This type exists so that retiring a timeout you do not hold is not expressible. MarkDeliveredAsync(ClaimedSagaTimeout, CancellationToken) takes a claim rather than an identifier, and only ClaimDueTimeoutsAsync(DateTimeOffset, int, CancellationToken) produces one. The diagnostic read, GetDueTimeoutsAsync(DateTimeOffset, CancellationToken), returns bare timeouts and claims nothing, so a caller cannot hand a monitoring result to the retirement call even by mistake — it does not compile.

The token is per claim, not per processor. Two claims of the same timeout by the same process, one after a lease expiry, carry different tokens; that is the distinction the retirement predicate turns on, and a token that merely identified the process could not express it.

This follows the shape a message broker uses for a leased message — the received message carries the lock that settles it, and a peeked message cannot be settled at all.

Constructors

ClaimedSagaTimeout(SagaTimeout, string)

A saga timeout together with the claim the caller holds on it.

public ClaimedSagaTimeout(SagaTimeout Timeout, string ClaimToken)

Parameters

Timeout SagaTimeout

The timeout that was claimed.

ClaimToken string

The token identifying this particular claim. Opaque to the caller: only the store that issued it interprets it, and callers must not construct, parse or reuse one.

Remarks

This type exists so that retiring a timeout you do not hold is not expressible. MarkDeliveredAsync(ClaimedSagaTimeout, CancellationToken) takes a claim rather than an identifier, and only ClaimDueTimeoutsAsync(DateTimeOffset, int, CancellationToken) produces one. The diagnostic read, GetDueTimeoutsAsync(DateTimeOffset, CancellationToken), returns bare timeouts and claims nothing, so a caller cannot hand a monitoring result to the retirement call even by mistake — it does not compile.

The token is per claim, not per processor. Two claims of the same timeout by the same process, one after a lease expiry, carry different tokens; that is the distinction the retirement predicate turns on, and a token that merely identified the process could not express it.

This follows the shape a message broker uses for a leased message — the received message carries the lock that settles it, and a peeked message cannot be settled at all.

ClaimedSagaTimeout(SagaTimeout, string, SagaTimeoutDeliveryIdentity)

Initializes a claim carrying original immutable owned-timeout authority captured by the claim statement.

public ClaimedSagaTimeout(SagaTimeout timeout, string claimToken, SagaTimeoutDeliveryIdentity ownedDelivery)

Parameters

timeout SagaTimeout

The actual claimed payload row.

claimToken string

The actual opaque acquisition token.

ownedDelivery SagaTimeoutDeliveryIdentity

The original authority projected from that same row.

Properties

ClaimToken

The token identifying this particular claim. Opaque to the caller: only the store that issued it interprets it, and callers must not construct, parse or reuse one.

public string ClaimToken { get; init; }

Property Value

string

DeliveryEpoch

Gets the opaque persisted delivery/disposition cycle projected by the SAME atomic claim statement.

public string? DeliveryEpoch { get; init; }

Property Value

string

Remarks

Assign on source creation and atomically advance on EVERY successful resume; reclaims without resume preserve it. SourceEpoch remains the independent source-row lifetime. The failed observation binds BOTH. Same-command resume replay must not advance this cycle twice. Old observations and fresh operation IDs cannot hold a later delivery cycle, even after earlier receipts have been evicted. Null is unsupported for hosted preserving delivery. This is expected-state metadata, not an authentication credential.

OwnedDelivery

Gets original owned authority, or null for an explicitly nonowned ordinary-store row.

public SagaTimeoutDeliveryIdentity? OwnedDelivery { get; }

Property Value

SagaTimeoutDeliveryIdentity

Remarks

Null never grants manual admission to a durable receiver.

SourceEpoch

Gets the opaque source-row lifetime epoch projected by the same atomic claim statement.

public string? SourceEpoch { get; init; }

Property Value

string

Remarks

Null means the claim lacks preserving hold capability; hosted validation must reject that path. The selected store assigns a fresh epoch to every newly scheduled/replaced source lifetime, including unowned ordinary timers and equal-ID/equal-payload replacements. Reclaims of that SAME source retain it. Never derive it solely from ID, payload hash, due date or process identity. This is expected-state metadata, not a credential; store validation remains mandatory. Existing owned incarnation is also checked.

Timeout

The timeout that was claimed.

public SagaTimeout Timeout { get; init; }

Property Value

SagaTimeout