Table of Contents

Interface IInboxStoreAdmin

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

Provides administrative and query operations for inbox store management.

public interface IInboxStoreAdmin
Extension Methods

Remarks

These operations are used by background services, health checks, retry processors, and administrative tooling. They are NOT needed for normal inbox message flow (create, check, mark processed/failed).

This follows the same ISP pattern as IOutboxStoreAdmin for the base IOutboxStore. Implementations should register this sub-interface separately in DI so consumers can resolve it independently.

Interface split:

  • IInboxStore -- Core: create, check, mark processed/failed, get entry (6 methods, hot path)
  • IInboxStoreAdmin -- Admin: bulk queries, statistics, cleanup, retry-processor mark-failed (5 methods, operational)

Methods

CleanupAllTenantsProcessedEntriesAsync(DateTimeOffset, CancellationToken)

Removes processed entries older than the specified timestamp across every tenant.

ValueTask<int> CleanupAllTenantsProcessedEntriesAsync(DateTimeOffset olderThan, CancellationToken cancellationToken)

Parameters

olderThan DateTimeOffset

Remove entries processed before this timestamp.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<int>

The number of entries removed, across all tenants.

Remarks

Scope: estate-wide, and destructive. This is a retention sweep that matches rows by status and age, not by tenant, so it deletes the qualifying entries of every tenant in the store. It observes and modifies all partitions.

The name is the safety control. An unbounded delete is reachable only by writing "AllTenants" at the call site — never by omitting a scope, and never by passing a value that happens to mean "everything". A reviewer reading the call site sees the blast radius without tracing where a scope came from.

An inbox store reads no ambient tenant context, so it cannot honor a tenant it never sees. Should tenant-scoped retention ever be required, it arrives as an explicit parameter on a distinct operation — never by inferring a scope from ambient state.

GetAllTenantsEntriesAsync(CancellationToken)

Retrieves every inbox entry, across every tenant, for testing and diagnostics.

ValueTask<IEnumerable<InboxEntry>> GetAllTenantsEntriesAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<IEnumerable<InboxEntry>>

Collection of all inbox entries, across all tenants.

Remarks

Scope: estate-wide, and the widest disclosure on this interface. No predicate of any kind is applied — the read returns the whole store, and each InboxEntry carries its payload and metadata. It observes all partitions and modifies none.

The name is the safety control. "GetAll" alone was ambiguous — it read as either "all of this tenant's entries" or "all entries everywhere" — so the scope is now stated in the name and cannot be reached by a caller who meant one tenant.

An inbox store reads no ambient tenant context, so it cannot honor a tenant it never sees. Should a tenant-scoped enumeration ever be required, it arrives as an explicit parameter on a distinct operation — never by inferring a scope from ambient state.

GetAllTenantsFailedEntriesAsync(int, DateTimeOffset?, int, CancellationToken)

Retrieves message entries eligible for retry, across every tenant.

ValueTask<IEnumerable<InboxEntry>> GetAllTenantsFailedEntriesAsync(int maxRetries, DateTimeOffset? olderThan, int batchSize, CancellationToken cancellationToken)

Parameters

maxRetries int

Maximum number of retry attempts to consider.

olderThan DateTimeOffset?

Only return entries older than this timestamp.

batchSize int

Maximum number of entries to return.

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<IEnumerable<InboxEntry>>

Collection of failed inbox entries eligible for retry, from every tenant.

Remarks

Scope: estate-wide. The status, retry-count and age filters below are the only predicates applied; no tenant term is applied and none can be. This is the retry sweeper's read, and the sweeper runs on a background loop with no ambient tenant to scope it by — a tenant-confined variant could only drain the one partition that happened to be current, leaving every other tenant's failed entries to accumulate unattended.

This read takes no ownership term. It is a plain query: it writes nothing, and two callers issuing it concurrently receive the same entries. It therefore does not, and cannot, prevent two processors from dispatching the same entry. A caller that needs that exclusion must take it itself, through TryAcquireLeaseAsync(string, string, TimeSpan, CancellationToken) on a store that offers it.

Which statuses are eligible depends on whether the store declares the lease protocol, and this is a required behaviour, not an implementation liberty. A store that implements ILeasedInboxStore MUST return, in addition to Failed entries, any Processing entry whose lease has expired — compared against the store's own clock, as everywhere else in the lease protocol. A store that does not implement the lease protocol returns Failed entries only.

The expired-lease arm is what keeps the two properties from trading against each other. A leasing caller moves an entry to Processing before invoking its handler; if that caller then dies, a read admitting only Failed would never select the entry again, and it would be reachable solely by a redelivery that a message already consumed off the transport never receives. Omitting this arm therefore converts a bounded duplicate dispatch into permanent silent loss, which is the worse failure of the two.

An entry that is Processing with no lease recorded was claimed through the term-less claim protocol, which is held until its own caller finalizes or releases it. Absent is "no expiry", never "expired": such an entry MUST NOT be returned.

The name is the safety control. The returned entries span partitions, so a caller must re-establish each entry's own tenant from TenantId before acting on it, rather than processing the batch under whatever scope happened to be ambient at the call site.

GetAllTenantsStatisticsAsync(CancellationToken)

Gets statistics about inbox entries, across every tenant.

ValueTask<InboxStatistics> GetAllTenantsStatisticsAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<InboxStatistics>

Statistics including counts of entries by status, across all tenants.

Remarks

Scope: estate-wide. The counters describe the whole store: no tenant discriminator is applied, and InboxStatistics carries no tenant field, so a confined result could not say which partition it described even if one were produced. It observes all partitions and modifies none.

The name is the safety control: estate-wide counters are reachable only by writing "AllTenants" at the call site. Aggregate counts disclose no message identifiers, payloads, or tenant names — only totals — so this is a weaker disclosure than GetAllTenantsEntriesAsync(CancellationToken), which returns whole entries.

An inbox store reads no ambient tenant context, so it cannot honor a tenant it never sees. Should per-tenant counters ever be required, they arrive as an explicit parameter on a distinct operation — never by inferring a scope from ambient state.

MarkFailedAsync(KeyedTenantPartition, string, string, string, int, CancellationToken)

Marks an existing inbox entry in tenant as failed/retryable, setting its retry count exactly to retryCount without auto-incrementing, and reports which of the three possible things actually happened.

ValueTask<InboxMarkFailedOutcome> MarkFailedAsync(KeyedTenantPartition tenant, string messageId, string handlerType, string errorMessage, int retryCount, CancellationToken cancellationToken)

Parameters

tenant KeyedTenantPartition

The tenant partition the entry lives in. Required; there is no ambient fallback.

messageId string

The unique identifier of the message that failed.

handlerType string

The handler type the entry is keyed to.

errorMessage string

The error description to record.

retryCount int

The retry count to set on the entry, exactly (not incremented).

cancellationToken CancellationToken

Token to monitor for cancellation requests.

Returns

ValueTask<InboxMarkFailedOutcome>

Applied when the entry was mutated; EntryNotFound when no such entry exists in tenant; AlreadyProcessed when the entry is present but terminal and the transition was refused.

Remarks

This is a retry-processor operation for the transient-failure case: a short-circuit (e.g. an open circuit breaker) is not a delivery attempt, so it must leave the message re-admittable for retry without consuming an attempt. Unlike the core MarkFailedAsync(string, string, string, CancellationToken) (which increments the retry count), this overload sets the count exactly — symmetric with MarkFailedAsync(string, string, int, CancellationToken).

Scope: exactly one tenant, and the caller names it. This is the only member on this interface that writes, and it is therefore the only one whose scope is a parameter rather than a word in its name. The estate-wide readers above announce their breadth by being called "AllTenants"; this one announces its narrowness by making the caller construct the partition it means. There is no inhabitant of KeyedTenantPartition that means "whatever tenant happens to be ambient", so a caller cannot reach a partition it did not choose — which is what an operator listing failed entries estate-wide and then marking one needs, because the two calls would otherwise address different populations with nothing in either signature to say so. Take the partition from the entry's own TenantId via FromStoredValue(string?), never from whatever scope happened to be current at the call site.

The store decides the outcome inside the statement that performs the write, and reports it rather than throwing. All three results are ordinary returns: an absent entry is EntryNotFound, not an exception, because this call is issued from inside a drain's failure handling where an exception abandons every other entry the caller still holds. A store must not classify by reading the entry back after the write — that reads a value from outside the window it claims to describe, and is wrong exactly when a concurrent finalize makes the refusal real.

No insert or upsert is performed: this is a retry-only path over already-persisted entries.

Exceptions

ArgumentNullException

tenant is null.