Table of Contents

Interface ISagaStoreAdmin

Namespace
Excalibur.Dispatch.Messaging
Assembly
Excalibur.Dispatch.Abstractions.dll

Administrative and query operations over a saga store: enumerate and filter saga instances, fetch a single instance summary, and compute aggregate statistics.

public interface ISagaStoreAdmin
Extension Methods

Remarks

These operations back health checks, operational tooling, and the operations dashboard. They are NOT needed for the normal saga load/save flow, so this is a separate interface following the same ISP pattern as IOutboxStoreAdmin / IInboxStoreAdmin. Implementations register this sub-interface in DI so consumers can resolve it independently.

The MVP providers are the in-memory, SQL Server, and PostgreSQL saga stores. A store that cannot support these queries need not implement this interface; the dashboard fails open when it is absent.

Methods

GetAllTenantsStatisticsAsync(CancellationToken)

Gets aggregate statistics about the sagas of every tenant (running / completed / total counts).

ValueTask<SagaStoreStatistics> GetAllTenantsStatisticsAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<SagaStoreStatistics>

The saga store statistics across all tenant partitions.

Remarks

This is the operator diagnostic: no tenant discriminator is applied, so every tenant's sagas are counted. It is the only statistics read that runs without a resolved tenant, because it is the only one that does not need to name one.

The name is the safety control. Estate-wide counts are reachable only by writing "AllTenants" at the call site, never by omitting a scope or by passing a value that happens to mean "everything" — the same discipline as PurgeAllTenantsCompletedBeforeAsync(DateTimeOffset, CancellationToken). A caller cannot arrive here by forgetting something, and a reviewer reading the call site sees the intent without tracing where a scope came from.

Aggregate counts disclose no saga identifiers, types, or tenant names — only totals — so this is a weaker disclosure than QuerySagasAsync(SagaQueryFilter, CancellationToken), which stays tenant-scoped and has no estate-wide counterpart.

Like the estate-wide purge this is an optional capability whose default implementation throws. A store that supports it overrides this method; a decorator must override it to forward to its inner store — a decorator that does not override inherits this throwing default, so a decorated store would report the capability as missing even though the store underneath supports it.

Exceptions

NotSupportedException

Thrown by stores that do not support estate-wide statistics.

GetStatisticsAsync(CancellationToken)

Gets aggregate statistics about the calling tenant's sagas (running / completed / total counts).

ValueTask<SagaStoreStatistics> GetStatisticsAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<SagaStoreStatistics>

The saga store statistics for the ambient tenant partition.

Remarks

The counts are tenant-scoped: they cover the ambient partition and no other. A host that established no tenant operates on the untenanted partition, which is a real partition holding the rows that carry no tenant — not a wildcard, and not every tenant's rows. Estate-wide counts are a deliberately separate operation, GetAllTenantsStatisticsAsync(CancellationToken).

GetSummaryAsync(Guid, CancellationToken)

Gets the summary of a single saga instance by its identifier.

ValueTask<SagaInstanceSummary?> GetSummaryAsync(Guid sagaId, CancellationToken cancellationToken)

Parameters

sagaId Guid

The unique identifier of the saga instance.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<SagaInstanceSummary>

The saga instance summary, or null when no such saga exists.

QuerySagasAsync(SagaQueryFilter, CancellationToken)

Queries saga instance summaries matching the supplied filter, ordered by store-defined ordering, with pagination.

ValueTask<IReadOnlyList<SagaInstanceSummary>> QuerySagasAsync(SagaQueryFilter filter, CancellationToken cancellationToken)

Parameters

filter SagaQueryFilter

The filter criteria (completion state, tenant, pagination).

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<IReadOnlyList<SagaInstanceSummary>>

The matching saga instance summaries.

Exceptions

ArgumentNullException

Thrown when filter is null.