Innovabit.DotNet.Interceptors.Coordination.Abstractions 2.0.117

Innovabit.DotNet.Interceptors.Coordination.Abstractions

Three answers to "this must not happen twice" for Innovabit.DotNet.Interceptors, in one package because they share one question — which calls are the same call? Pick a provider for the two that need somewhere to keep state:

• Innovabit.DotNet.Interceptors.Coordination.Memory — in this process.
• Innovabit.DotNet.Interceptors.Coordination.Redis — shared across instances.

Which one do you want

They compose: [SingleFlight] collapses the local stampede, [DistributedLock] serialises what is left across instances, [Idempotent] makes the whole thing safe to retry.

Usage

services
    .AddInterceptors()
    .AddRedisCoordination();          // or .AddInMemoryCoordination()

services.AddScopedWithInterception<IPaymentService, PaymentService>();

public class PaymentService : IPaymentService
{
    // Runs once per idempotency key; a replay gets the original receipt back.
    [Idempotent(KeyFrom = nameof(idempotencyKey))]
    public Task<Receipt> ChargeAsync(string idempotencyKey, Order order) { ... }

    // One run per tenant at a time, across every instance.
    [DistributedLock(KeyFrom = nameof(tenantId), LeaseSeconds = 300)]
    public Task RebuildAsync(string tenantId) { ... }

    // A hundred simultaneous misses become one call.
    [SingleFlight(KeyFrom = nameof(symbol))]
    [Cache(DurationSeconds = 30)]
    public Task<Quote> QuoteAsync(string symbol) { ... }
}

[Idempotent]

KeyFrom is required on purpose: an idempotency key identifies the request, and there is nothing in a method signature a library could safely invent one from. Omitting it throws.

A result is only remembered once the call succeeds. A failure leaves no trace and the next attempt runs normally — retrying a failure has to be allowed, which is the other half of retrying a success being free.

Retention is how long you are protected for: a retry arriving after it runs again. Match it to how long the caller might keep retrying, not to the smallest number that seems to work.

This is not caching. A cache is an optimisation you could switch off; this is a guarantee about a side effect happening once, which is why it runs outside both the cache and the transaction.

[SingleFlight]

A cache stops repeated work after the first call finishes. It does nothing about the callers that all miss at the same instant — exactly what happens when a hot entry expires. [SingleFlight] makes them share one call.

Coalescing is per process: sharing an in-flight call across a network is not something a lock can do, so behind four instances a stampede of four remains. That is the difference between a manageable spike and an outage.

A failure is shared too — everyone waiting on the one call that ran sees its exception — and is never remembered: the next call starts fresh. Synchronous methods pass straight through, since a thread that is blocked has nothing to join.

[DistributedLock]

A caller that cannot take the lock in time gets DistributedLockNotAcquiredException and never reaches the method.

The lease is also the limit of the promise. It exists so a holder that dies does not block everyone forever, which means a method that outlives its lease loses the lock while still running and two copies can overlap. No lease-based lock avoids this. Size the lease above the method's worst case, and treat the lock as protection against the common case rather than a guarantee of mutual exclusion under arbitrary pauses.

Ordering

… Idempotency 180 → Caching 200 → SingleFlight 250 → DistributedLock 270 → … Retry 500 … Transaction 700

• Idempotency outside caching, so a replay answers without even a cache lookup, and outside the transaction, so a result is only remembered once the work it describes has committed.
• SingleFlight inside caching, because what it collapses is concurrent cache misses, and outside the lock, because coalescing locally is free and taking a remote lock is not.
• DistributedLock inside caching so a cache hit takes no lock, and outside retry and transaction so one holder owns the whole unit of work, attempts included.

Keys

All three resolve a key the same way: the operation's Name (or Type.Method), optionally narrowed by the value of the KeyFrom parameter. Values are rendered with the invariant culture, so the same request cannot resolve to two keys depending on the thread that served it. A KeyFrom matching no parameter throws and names the parameters that do exist — silently widening the scope is the kind of mistake that only shows up once it is already doing the wrong thing.

License

MIT