Interface IInboxStoreAdmin
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
olderThanDateTimeOffsetRemove entries processed before this timestamp.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
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
cancellationTokenCancellationTokenToken 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
maxRetriesintMaximum number of retry attempts to consider.
olderThanDateTimeOffset?Only return entries older than this timestamp.
batchSizeintMaximum number of entries to return.
cancellationTokenCancellationTokenToken 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
cancellationTokenCancellationTokenToken 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
tenantKeyedTenantPartitionThe tenant partition the entry lives in. Required; there is no ambient fallback.
messageIdstringThe unique identifier of the message that failed.
handlerTypestringThe handler type the entry is keyed to.
errorMessagestringThe error description to record.
retryCountintThe retry count to set on the entry, exactly (not incremented).
cancellationTokenCancellationTokenToken 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
tenantis null.