Class OutboxStore

Namespace

Xapi.Client.Outbox

Assembly

Xapi.Client.Outbox.dll

Where an outbox keeps its Statements: an ordered queue of pending entries, keyed by Statement id, and a set of dead letters.

public abstract class OutboxStore

Inheritance

object

OutboxStore

Derived

FileOutboxStore

InMemoryOutboxStore

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Implementations must be safe to call from several threads at once: EnqueueAsync(Statement, CancellationToken) adds entries while a flush reads and removes others. Every method that changes the store must have made the change durable when its task completes, because the outbox reports success to its callers at that point.

Built in: FileOutboxStore (durable, for applications) and InMemoryOutboxStore (for tests, and for cases where losing queued Statements on exit is acceptable).

Members added to this class in later versions will be virtual, with a default implementation built on the existing members, so stores derived from it keep compiling and working.

Constructors

OutboxStore()

Initializes the store.

protected OutboxStore()

Methods

AddAsync(OutboxEntry, CancellationToken)

Adds an entry at the end of the queue, unless an entry with the same Statement id is pending.

public abstract ValueTask<bool> AddAsync(OutboxEntry entry, CancellationToken cancellationToken)

Parameters

entry OutboxEntry

The entry.

cancellationToken CancellationToken

Cancels the operation.

Returns

ValueTask<bool>

true when the entry was added; false when its id was already pending.

GetDeadLetterCountAsync(CancellationToken)

Returns the number of dead letters.

public abstract ValueTask<int> GetDeadLetterCountAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancels the operation.

Returns

ValueTask<int>

The number of dead letters.

GetDeadLettersAsync(CancellationToken)

Returns the dead letters, oldest first.

public abstract ValueTask<IReadOnlyList<OutboxDeadLetter>> GetDeadLettersAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancels the operation.

Returns

ValueTask<IReadOnlyList<OutboxDeadLetter>>

The dead letters.

GetPendingAsync(int, CancellationToken)

Returns the oldest pending entries, in queue order, without removing them.

public abstract ValueTask<IReadOnlyList<OutboxEntry>> GetPendingAsync(int maxCount, CancellationToken cancellationToken)

Parameters

maxCount int

The largest number of entries to return.

cancellationToken CancellationToken

Cancels the operation.

Returns

ValueTask<IReadOnlyList<OutboxEntry>>

Up to maxCount entries; empty when nothing is pending.

GetPendingCountAsync(CancellationToken)

Returns the number of pending entries.

public abstract ValueTask<int> GetPendingCountAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancels the operation.

Returns

ValueTask<int>

The number of pending entries.

MoveToDeadLettersAsync(OutboxDeadLetter, CancellationToken)

Removes the pending entry with the dead letter's Statement id, if there is one, and stores the dead letter, replacing any dead letter with the same id.

public abstract ValueTask MoveToDeadLettersAsync(OutboxDeadLetter deadLetter, CancellationToken cancellationToken)

Parameters

deadLetter OutboxDeadLetter

The dead letter.

cancellationToken CancellationToken

Cancels the operation.

Returns

ValueTask

A task that completes when the change is durable.

RecordFailedAttemptAsync(IReadOnlyCollection<Guid>, string, CancellationToken)

Records a failed send of pending entries: increments Attempts and sets LastError. Ids that are not pending are ignored.

public abstract ValueTask RecordFailedAttemptAsync(IReadOnlyCollection<Guid> statementIds, string error, CancellationToken cancellationToken)

Parameters

statementIds IReadOnlyCollection<Guid>

The Statement ids.

error string

A description of the error.

cancellationToken CancellationToken

Cancels the operation.

Returns

ValueTask

A task that completes when the change is durable.

RemoveAsync(IReadOnlyCollection<Guid>, CancellationToken)

Removes delivered entries. Ids that are not pending are ignored.

public abstract ValueTask RemoveAsync(IReadOnlyCollection<Guid> statementIds, CancellationToken cancellationToken)

Parameters

statementIds IReadOnlyCollection<Guid>

The Statement ids.

cancellationToken CancellationToken

Cancels the operation.

Returns

ValueTask

A task that completes when the removal is durable.

RemoveDeadLetterAsync(Guid, CancellationToken)

Deletes a dead letter.

public abstract ValueTask<bool> RemoveDeadLetterAsync(Guid statementId, CancellationToken cancellationToken)

Parameters

statementId Guid

The Statement id.

cancellationToken CancellationToken

Cancels the operation.

Returns

ValueTask<bool>

false when there is no dead letter with that id.

RequeueAsync(Guid, CancellationToken)

Moves a dead letter back to the end of the queue as a pending entry with no failed attempts. If an entry with the same id is already pending, the dead letter is only removed.

public abstract ValueTask<bool> RequeueAsync(Guid statementId, CancellationToken cancellationToken)

Parameters

statementId Guid

The Statement id.

cancellationToken CancellationToken

Cancels the operation.

Returns

ValueTask<bool>

false when there is no dead letter with that id.