LockingKit 0.4.0

LockingKit

Distributed locks for .NET 10 behind one contract. Code written against IDistributedLock runs unchanged on Azure blob leases, PostgreSQL advisory locks and an in-memory provider. One engine does the hard parts for every backend: waiting, renewal, loss detection, release and telemetry. A single contract suite and a chaos suite hold all three to the same behaviour against real containers.

builder.Services.AddLocking().UseAzureBlobLeases(builder.Configuration);   // or .UsePostgres(...), .UseInMemory()

var acquired = await locks.TryAcquireAsync($"orders/{id}", ct);
if (acquired.IsFailure) return acquired.Error;          // locking.busy: someone else has it. Not an exception.

await using var handle = acquired.Value;
using var work = CancellationTokenSource.CreateLinkedTokenSource(ct, handle.LostToken);

await ShipAsync(order, handle.FencingToken, work.Token);  // stops if the lock is lost

Packages

dotnet add package LockingKit.Azure     # or LockingKit.Postgres

A module that only takes locks references LockingKit alone, and the host picks the backend. Tests use UseInMemory(), which has the same expiry, renewal and fencing behaviour as a real lease backend.

Quick start

{
  "Locking": {
    "Default": {
      "ConnectionString": "<from a secret store>",
      "ContainerName": "locks"
    }
  }
}

builder.Services.AddLocking().UseAzureBlobLeases(builder.Configuration);   // Locking:Default

public sealed class NightlyExport(IDistributedLock locks)
{
    public async Task RunAsync(CancellationToken ct)
    {
        // Wait up to 30 s for the lock, then give up with locking.timeout.
        var acquired = await locks.AcquireAsync("jobs/nightly-export", TimeSpan.FromSeconds(30), ct);
        if (acquired.IsFailure) return;

        await using var handle = acquired.Value;

        foreach (var batch in Batches())
        {
            if (handle.EnsureHeld().IsFailure) return;   // locking.lost: stop instead of working unprotected
            await ExportAsync(batch, handle.LostToken);
        }
    }
}

The contract

The handle:

A handle renews itself in the background. The ct you pass to acquire only cancels the acquisition, never the handle.

Results and errors

A wait that never reached the backend ends in locking.unavailable, not locking.timeout, so an outage is not mistaken for contention. Every outcome is a result, never an exception: misconfiguration and unexpected backend failures included, and a waiter stops at the first failure no retry can fix. The one exception is cancellation: cancelling your ct throws OperationCanceledException, as it does throughout .NET. Locks are not reentrant: acquiring a key your own process holds is locking.busy.

Keys

A key is any string of 1–512 characters, compared ordinally (case-sensitive). Each provider maps keys safely, and two different keys never share a lock:

• Azure: letters, digits, -, _, . and / pass through, so orders/42 is the blob locks/orders/42. Every other character, and ~, becomes ~XX per UTF-8 byte. So do / and . in places Azure would rewrite: a leading, trailing or doubled /, and a . that starts a segment or ends the key. A name over Azure's 1024 characters or 254 segments becomes locks/~sha256~{hex}.
• PostgreSQL: the advisory key is the first 8 bytes of the SHA-256 of the UTF-8 key, read as a big-endian bigint. The mapping is stable and documented, so SQL can take the same lock: pg_try_advisory_lock(('x' || left(encode(sha256(convert_to($1, 'UTF8')), 'hex'), 16))::bit(64)::bigint), available as PostgresLockKeys.SqlExpression. Two keys collide with negligible probability, and a collision only makes them exclude each other.

Waiting

AcquireAsync retries with capped exponential backoff and equal jitter: 50 ms doubling to 1 s by default (MinRetryDelay, MaxRetryDelay). The cap makes waiting fair across processes, because a caller that has waited a minute polls as often as one that just arrived. Within one process, waiters for a key queue first come, first served. Only the front one polls, so twenty local callers make one stream of requests, and a local release wakes the next one at once.

Guarantees

A lease lock gives mutual exclusion among holders that are running. It cannot stop a process that has paused (GC, VM suspension, a stalled thread) from waking up and carrying on as if it still held the lock, because no client-side check can run while the process is paused. This is the well-known limitation of every lease-based lock, not a gap in this one. LockingKit narrows the window as far as a client can and gives you the tool to close it:

• The handle gives up early. The deadline is measured on a monotonic clock from when the last successful renewal was sent. The backend started its lease no earlier than that, so the handle declares loss a safety margin (10% of the lease) before the backend could expire it. That holds as long as the client's clock rate stays within 10% of the backend's. Wall clocks do not need to agree.
• A hung renewal cannot postpone the loss. A separate timer enforces the deadline and fires LostToken on time even if the renewal request never returns.
• Work stops instead of continuing unprotected, provided you pass LostToken into it or call ThrowIfLost() between steps.
• Fencing tokens close the remaining window. Send FencingToken with every write to the protected resource, and have the resource refuse a token lower than the highest it has seen. A former holder that wakes from a pause is then turned away whatever the timing. Without fencing, a lock is good for efficiency (not doing work twice) and not for correctness.
• A lease never protects writes to other resources by itself. Holding the lock does not make writes to unrelated objects transactional. Use fencing, or the resource's own conditional writes, as StoringKit's IfMatch does for blobs.

Per provider:

PostgreSQL advisory locks are not replicated. After a failover every lock is gone, and every holder sees ConnectionLost. They need session pooling: PgBouncer in transaction or statement mode breaks them.

Providers

Azure

Each key is a guard blob. A missing guard is created empty and create-only, and an existing guard's content and metadata are never touched (fencing adds one metadata entry). Writes to the guard itself can be fenced by Azure:

var lease = handle.GetAzureBlobLease()!;                 // the guard BlobClient and lease id
await lease.Blob.UploadAsync(state, new BlobUploadOptions { Conditions = lease.Conditions }, ct);

PostgreSQL

Every held lock keeps one connection open, so size Maximum Pool Size for the locks a process holds at once. A connection whose unlock could not be confirmed is never returned to the pool. It is closed instead, which ends the session and frees the lock.

Several backends

Each provider has a name. The one called Default is also a plain IDistributedLock, and the rest are keyed services, like StoringKit's named stores. Options bind from Locking:{name} and are validated at startup.

builder.Services.AddLocking().UseAzureBlobLeases(builder.Configuration);          // Locking:Default
builder.Services.AddLocking("Jobs").UsePostgres(builder.Configuration);           // Locking:Jobs

public sealed class Scheduler(IDistributedLock locks, [FromKeyedServices("Jobs")] IDistributedLock jobLocks) { … }

Your own backend

Implement ILockBackend: one attempt that returns an ILockLease or null when busy, plus RenewAsync and ReleaseAsync on the lease. Pick its LeaseTiming (Expiring(duration) or ConnectionHeld(interval)) and register it with AddLocking(name).UseBackend<TOptions>("myprovider", (sp, options) => new MyBackend(...)). The engine adds waiting, renewal, loss detection, release, results and telemetry exactly as for the built-in backends.

Testing

LockingKit.IntegrationTests runs every provider against a real backend: Azurite via TestingKit.Azurite, PostgreSQL via TestingKit.Postgres, and the in-memory provider. Each "process" in a test is a separate engine with its own client and pool.

Contract suite, the same for all three providers: busy and non-reentrant; release lets the next holder in at once; idempotent dispose; waiting and timeouts; 80 acquisitions by 20 contenders across 4 processes, checked for overlap by an interval checker; distinct look-alike keys (a/b, a~2Fb, a%2Fb, .., Unicode, 512 characters); cancellation before, during and after an attempt; renewal over three or more lease periods; growing fencing tokens; FIFO order of local waiters.

Chaos suite:

LockingKit.UnitTests drives the renewal scheduler, backoff, waiting room and disposal on a FakeTimeProvider. Every timing decision goes through TimeProvider, so tests can check, for example, that a 30 s lease is lost at exactly 27 s after the last renewal was sent, whether the renewal failed or never answered.

Observability

LockingKit traces and measures itself the way HttpClient and EF Core do. It uses only ActivitySource and Meter from the runtime, with no OpenTelemetry package, and nothing is recorded until the host listens:

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddSource(LockingKitInstrumentation.ActivitySourceName))
    .WithMetrics(m => m.AddMeter(LockingKitInstrumentation.MeterName));

Keys are never recorded, because they routinely carry ids. Exceptions are recorded by type only. OpenTelemetry has no lock conventions, so attributes use the lockingkit. prefix, apart from the general error.type.

Spans: try_acquire {name}, acquire {name} and release {name}, of kind Client. Attributes: lockingkit.lock (the provider name), lockingkit.provider (azure_blob, postgres, in_memory), lockingkit.operation, lockingkit.outcome (acquired, busy, timeout, cancelled, failure), lockingkit.acquire.attempts, lockingkit.fencing_token, and error.type and lockingkit.error.kind on failures. Contention is an outcome, not an error: busy and timeout spans have no error status.

Metrics, on the LockingKit meter, created through the host's IMeterFactory: