Class EfCoreGovernanceOutboxOutcomeStore

Namespace

AsiBackbone.EntityFrameworkCore.Outbox

Assembly

AsiBackbone.EntityFrameworkCore.dll

EF Core outbox store that exposes explicit caller-owned claim transition outcomes.

public sealed class EfCoreGovernanceOutboxOutcomeStore : IGovernanceOutboxClaimOutcomeStore, IGovernanceOutboxClaimStore, IGovernanceOutboxStore

Inheritance

object

EfCoreGovernanceOutboxOutcomeStore

Implements

IGovernanceOutboxClaimOutcomeStore

IGovernanceOutboxClaimStore

IGovernanceOutboxStore

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This store preserves the existing convenience API while adding an outcome-aware contract that distinguishes applied transitions from stale claims, terminal no-ops, concurrency losses, and missing rows. It delegates persistence to EfCoreGovernanceOutboxStore and observes the scoped DbContext save boundary so callers do not infer write ownership from the returned durable status alone.

Constructors

EfCoreGovernanceOutboxOutcomeStore(DbContext, ILogger<EfCoreGovernanceOutboxOutcomeStore>?)

Initializes a new instance of the EfCoreGovernanceOutboxOutcomeStore class.

public EfCoreGovernanceOutboxOutcomeStore(DbContext dbContext, ILogger<EfCoreGovernanceOutboxOutcomeStore>? logger = null)

Parameters

dbContext DbContext

The host-owned scoped database context.

logger ILogger<EfCoreGovernanceOutboxOutcomeStore>

The logger used for non-applied claimed-transition diagnostics.

Methods

ClaimPendingAsync(GovernanceOutboxClaimRequest, CancellationToken)

Claims pending entries ordered for delivery.

public ValueTask<IReadOnlyList<GovernanceOutboxClaim>> ClaimPendingAsync(GovernanceOutboxClaimRequest request, CancellationToken cancellationToken = default)

Parameters

request GovernanceOutboxClaimRequest

cancellationToken CancellationToken

Returns

ValueTask<IReadOnlyList<GovernanceOutboxClaim>>

ClaimRetryReadyAsync(GovernanceOutboxClaimRequest, CancellationToken)

Claims retry-ready entries ordered for delivery.

public ValueTask<IReadOnlyList<GovernanceOutboxClaim>> ClaimRetryReadyAsync(GovernanceOutboxClaimRequest request, CancellationToken cancellationToken = default)

Parameters

request GovernanceOutboxClaimRequest

cancellationToken CancellationToken

Returns

ValueTask<IReadOnlyList<GovernanceOutboxClaim>>

EnqueueAsync(GovernanceEmissionEnvelope, CancellationToken)

Enqueues a provider-neutral governance emission envelope before optional downstream provider delivery is attempted.

public ValueTask<GovernanceOutboxEntry> EnqueueAsync(GovernanceEmissionEnvelope envelope, CancellationToken cancellationToken = default)

Parameters

envelope GovernanceEmissionEnvelope

cancellationToken CancellationToken

Returns

ValueTask<GovernanceOutboxEntry>

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.

public ValueTask<GovernanceOutboxEntry?> FindByOutboxEntryIdAsync(string outboxEntryId, CancellationToken cancellationToken = default)

Parameters

outboxEntryId string

cancellationToken CancellationToken

Returns

ValueTask<GovernanceOutboxEntry>

FindPendingAsync(int, CancellationToken)

Finds pending outbox entries ordered for delivery.

public ValueTask<IReadOnlyList<GovernanceOutboxEntry>> FindPendingAsync(int maxCount = 100, CancellationToken cancellationToken = default)

Parameters

maxCount int

cancellationToken CancellationToken

Returns

ValueTask<IReadOnlyList<GovernanceOutboxEntry>>

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.

public ValueTask<IReadOnlyList<GovernanceOutboxEntry>> FindRetryReadyAsync(DateTimeOffset utcNow, int maxCount = 100, CancellationToken cancellationToken = default)

Parameters

utcNow DateTimeOffset

maxCount int

cancellationToken CancellationToken

Returns

ValueTask<IReadOnlyList<GovernanceOutboxEntry>>

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.

MarkClaimDeadLetteredAsync(GovernanceOutboxClaim, GovernanceEmissionError, string?, CancellationToken)

Completes a claimed entry as dead-lettered when the claim token still matches.

public ValueTask<GovernanceOutboxEntry> MarkClaimDeadLetteredAsync(GovernanceOutboxClaim claim, GovernanceEmissionError governanceEmissionError, string? deadLetterReason = null, CancellationToken cancellationToken = default)

Parameters

claim GovernanceOutboxClaim

governanceEmissionError GovernanceEmissionError

deadLetterReason string

cancellationToken CancellationToken

Returns

ValueTask<GovernanceOutboxEntry>

MarkClaimDeliveredAsync(GovernanceOutboxClaim, GovernanceEmissionResult, CancellationToken)

Completes a claimed entry as delivered when the claim token still matches.

public ValueTask<GovernanceOutboxEntry> MarkClaimDeliveredAsync(GovernanceOutboxClaim claim, GovernanceEmissionResult result, CancellationToken cancellationToken = default)

Parameters

claim GovernanceOutboxClaim

result GovernanceEmissionResult

cancellationToken CancellationToken

Returns

ValueTask<GovernanceOutboxEntry>

MarkClaimFailedAsync(GovernanceOutboxClaim, GovernanceEmissionError, DateTimeOffset?, CancellationToken)

Completes a claimed entry as failed or retryable failed when the claim token still matches.

public ValueTask<GovernanceOutboxEntry> MarkClaimFailedAsync(GovernanceOutboxClaim claim, GovernanceEmissionError governanceEmissionError, DateTimeOffset? nextRetryUtc = null, CancellationToken cancellationToken = default)

Parameters

claim GovernanceOutboxClaim

governanceEmissionError GovernanceEmissionError

nextRetryUtc DateTimeOffset?

cancellationToken CancellationToken

Returns

ValueTask<GovernanceOutboxEntry>

MarkDeadLetteredAsync(string, GovernanceEmissionError, string?, CancellationToken)

Marks an outbox entry as dead-lettered.

public ValueTask<GovernanceOutboxEntry> MarkDeadLetteredAsync(string outboxEntryId, GovernanceEmissionError governanceEmissionError, string? deadLetterReason = null, CancellationToken cancellationToken = default)

Parameters

outboxEntryId string

governanceEmissionError GovernanceEmissionError

deadLetterReason string

cancellationToken CancellationToken

Returns

ValueTask<GovernanceOutboxEntry>

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.

public ValueTask<GovernanceOutboxEntry> MarkDeliveredAsync(string outboxEntryId, GovernanceEmissionResult result, CancellationToken cancellationToken = default)

Parameters

outboxEntryId string

result GovernanceEmissionResult

cancellationToken CancellationToken

Returns

ValueTask<GovernanceOutboxEntry>

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.

public ValueTask<GovernanceOutboxEntry> MarkFailedAsync(string outboxEntryId, GovernanceEmissionError governanceEmissionError, DateTimeOffset? nextRetryUtc = null, CancellationToken cancellationToken = default)

Parameters

outboxEntryId string

governanceEmissionError GovernanceEmissionError

nextRetryUtc DateTimeOffset?

cancellationToken CancellationToken

Returns

ValueTask<GovernanceOutboxEntry>

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.

ReleaseClaimAsync(GovernanceOutboxClaim, string?, CancellationToken)

Releases a claim without changing provider emission state when the claim token still matches.

public ValueTask<GovernanceOutboxEntry?> ReleaseClaimAsync(GovernanceOutboxClaim claim, string? reason = null, CancellationToken cancellationToken = default)

Parameters

claim GovernanceOutboxClaim

reason string

cancellationToken CancellationToken

Returns

ValueTask<GovernanceOutboxEntry>

SaveAsync(GovernanceOutboxEntry, CancellationToken)

Saves an updated outbox entry state.

public ValueTask<GovernanceOutboxEntry> SaveAsync(GovernanceOutboxEntry entry, CancellationToken cancellationToken = default)

Parameters

entry GovernanceOutboxEntry

cancellationToken CancellationToken

Returns

ValueTask<GovernanceOutboxEntry>

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.

SaveClaimAsync(GovernanceOutboxClaim, GovernanceOutboxEntry, CancellationToken)

Saves a claimed entry transition, such as provider-directed deferred state, when the claim token still matches.

public ValueTask<GovernanceOutboxEntry> SaveClaimAsync(GovernanceOutboxClaim claim, GovernanceOutboxEntry entry, CancellationToken cancellationToken = default)

Parameters

claim GovernanceOutboxClaim

entry GovernanceOutboxEntry

cancellationToken CancellationToken

Returns

ValueTask<GovernanceOutboxEntry>

TryMarkClaimDeadLetteredAsync(GovernanceOutboxClaim, GovernanceEmissionError, string?, CancellationToken)

Attempts to complete a claimed entry as dead-lettered and reports whether this invocation applied the transition.

public ValueTask<GovernanceOutboxClaimTransitionResult> TryMarkClaimDeadLetteredAsync(GovernanceOutboxClaim claim, GovernanceEmissionError governanceEmissionError, string? deadLetterReason = null, CancellationToken cancellationToken = default)

Parameters

claim GovernanceOutboxClaim

governanceEmissionError GovernanceEmissionError

deadLetterReason string

cancellationToken CancellationToken

Returns

ValueTask<GovernanceOutboxClaimTransitionResult>

TryMarkClaimDeliveredAsync(GovernanceOutboxClaim, GovernanceEmissionResult, CancellationToken)

Attempts to complete a claimed entry as delivered and reports whether this invocation applied the transition.

public ValueTask<GovernanceOutboxClaimTransitionResult> TryMarkClaimDeliveredAsync(GovernanceOutboxClaim claim, GovernanceEmissionResult result, CancellationToken cancellationToken = default)

Parameters

claim GovernanceOutboxClaim

result GovernanceEmissionResult

cancellationToken CancellationToken

Returns

ValueTask<GovernanceOutboxClaimTransitionResult>

TryMarkClaimFailedAsync(GovernanceOutboxClaim, GovernanceEmissionError, DateTimeOffset?, CancellationToken)

Attempts to complete a claimed entry as failed or retryable failed and reports whether this invocation applied the transition.

public ValueTask<GovernanceOutboxClaimTransitionResult> TryMarkClaimFailedAsync(GovernanceOutboxClaim claim, GovernanceEmissionError governanceEmissionError, DateTimeOffset? nextRetryUtc = null, CancellationToken cancellationToken = default)

Parameters

claim GovernanceOutboxClaim

governanceEmissionError GovernanceEmissionError

nextRetryUtc DateTimeOffset?

cancellationToken CancellationToken

Returns

ValueTask<GovernanceOutboxClaimTransitionResult>

TrySaveClaimAsync(GovernanceOutboxClaim, GovernanceOutboxEntry, CancellationToken)

Attempts to save a caller-produced claimed transition and reports whether this invocation applied the transition.

public ValueTask<GovernanceOutboxClaimTransitionResult> TrySaveClaimAsync(GovernanceOutboxClaim claim, GovernanceOutboxEntry entry, CancellationToken cancellationToken = default)

Parameters

claim GovernanceOutboxClaim

entry GovernanceOutboxEntry

cancellationToken CancellationToken

Returns

ValueTask<GovernanceOutboxClaimTransitionResult>