Interface IAsiBackboneGovernanceOutboxStore
- Namespace
- AsiBackbone.Core.Outbox
- Assembly
- AsiBackbone.Core.dll
Defines a provider-neutral durable outbox store for governance emission envelopes.
public interface IAsiBackboneGovernanceOutboxStoreRemarks
Outbox entries are durable local state records keyed by OutboxEntryId. They are not an append-only event stream and they do not imply cross-process row claiming, leasing, skip-locked selection, or exactly-once provider delivery. Hosts that run multiple drain workers against the same durable store must add host-owned claiming, partitioning, or provider-side idempotency.
Methods
EnqueueAsync(GovernanceEmissionEnvelope, CancellationToken)
Enqueues a provider-neutral governance emission envelope before optional downstream provider delivery is attempted.
ValueTask<GovernanceOutboxEntry> EnqueueAsync(GovernanceEmissionEnvelope envelope, CancellationToken cancellationToken = default)Parameters
envelopeGovernanceEmissionEnvelopecancellationTokenCancellationToken
Returns
Remarks
Implementations should persist a new pending state record with a stable outbox entry identifier. Provider emission remains downstream and should be treated as at-least-once unless the host and provider supply stronger guarantees.
FindByOutboxEntryIdAsync(string, CancellationToken)
Finds an outbox entry by its stable identifier.
ValueTask<GovernanceOutboxEntry?> FindByOutboxEntryIdAsync(string outboxEntryId, CancellationToken cancellationToken = default)Parameters
outboxEntryIdstringcancellationTokenCancellationToken
Returns
FindPendingAsync(int, CancellationToken)
Finds pending outbox entries ordered for delivery.
ValueTask<IReadOnlyList<GovernanceOutboxEntry>> FindPendingAsync(int maxCount = 100, CancellationToken cancellationToken = default)Parameters
maxCountintcancellationTokenCancellationToken
Returns
Remarks
Returned entries are candidates, not claimed work items. A multi-worker host should use a storage adapter or deployment pattern that claims or partitions work before provider emission.
FindRetryReadyAsync(DateTimeOffset, int, CancellationToken)
Finds retry-ready outbox entries ordered for delivery.
ValueTask<IReadOnlyList<GovernanceOutboxEntry>> FindRetryReadyAsync(DateTimeOffset utcNow, int maxCount = 100, CancellationToken cancellationToken = default)Parameters
utcNowDateTimeOffsetmaxCountintcancellationTokenCancellationToken
Returns
Remarks
Returned entries are candidates, not claimed work items. A multi-worker host should use a storage adapter or deployment pattern that claims or partitions work before provider emission.
MarkDeadLetteredAsync(string, GovernanceEmissionError, string?, CancellationToken)
Marks an outbox entry as dead-lettered.
ValueTask<GovernanceOutboxEntry> MarkDeadLetteredAsync(string outboxEntryId, GovernanceEmissionError governanceEmissionError, string? deadLetterReason = null, CancellationToken cancellationToken = default)Parameters
outboxEntryIdstringgovernanceEmissionErrorGovernanceEmissionErrordeadLetterReasonstringcancellationTokenCancellationToken
Returns
Remarks
This is a non-claim mutation. Implementations may propagate a storage-provider optimistic-concurrency exception when another writer changes the same durable entry before this transition commits. No hidden retry or winner-state recovery is implied; the caller owns reload and conflict resolution. Competing workers should prefer a claim-capable store.
MarkDeliveredAsync(string, GovernanceEmissionResult, CancellationToken)
Marks an outbox entry as delivered using a provider-neutral emission result.
ValueTask<GovernanceOutboxEntry> MarkDeliveredAsync(string outboxEntryId, GovernanceEmissionResult result, CancellationToken cancellationToken = default)Parameters
outboxEntryIdstringresultGovernanceEmissionResultcancellationTokenCancellationToken
Returns
Remarks
This is a non-claim mutation. Implementations may propagate a storage-provider optimistic-concurrency exception when another writer changes the same durable entry before this transition commits. No hidden retry or winner-state recovery is implied; the caller owns reload and conflict resolution. Competing workers should prefer a claim-capable store.
MarkFailedAsync(string, GovernanceEmissionError, DateTimeOffset?, CancellationToken)
Marks an outbox entry as failed or retryable failed using provider-neutral error information.
ValueTask<GovernanceOutboxEntry> MarkFailedAsync(string outboxEntryId, GovernanceEmissionError governanceEmissionError, DateTimeOffset? nextRetryUtc = null, CancellationToken cancellationToken = default)Parameters
outboxEntryIdstringgovernanceEmissionErrorGovernanceEmissionErrornextRetryUtcDateTimeOffset?cancellationTokenCancellationToken
Returns
Remarks
This is a non-claim mutation. Implementations may propagate a storage-provider optimistic-concurrency exception when another writer changes the same durable entry before this transition commits. No hidden retry or winner-state recovery is implied; the caller owns reload and conflict resolution. Competing workers should prefer a claim-capable store.
SaveAsync(GovernanceOutboxEntry, CancellationToken)
Saves an updated outbox entry state.
ValueTask<GovernanceOutboxEntry> SaveAsync(GovernanceOutboxEntry entry, CancellationToken cancellationToken = default)Parameters
entryGovernanceOutboxEntrycancellationTokenCancellationToken
Returns
Remarks
Implementations should store the latest state for the entry's stable identifier. For durable providers that support it, saving an already-known OutboxEntryId should update the existing row rather than append a second logical outbox entry. Concurrent duplicate inserts may still surface provider-specific duplicate-key or concurrency exceptions that the host must reconcile.
This is a non-claim mutation. Implementations may propagate storage-provider optimistic-concurrency exceptions without retrying or translating another writer's state into caller success. The caller owns conflict detection, reload, retry, merge, or abandonment according to its idempotency and transaction model.