Ruvio.AspNetCore.DistributedLock 0.1.0

Ruvio.AspNetCore.DistributedLock

Distributed mutual exclusion on Ruvio. A lock is one key holding a random owner token, and every step is a single server command that only the owner can win:

Release and renewal can never touch a lock another owner took after yours expired, which is the bug a plain DEL has. This needs a Ruvio server with SET … IFEQ and DELEX.

services.AddRuvioDistributedLock(options => options.KeyPrefix = "myapp:lock:");

await using IRuvioLock? held = await locks.TryAcquireAsync(
    "nightly-report", lease: TimeSpan.FromSeconds(30), wait: TimeSpan.FromSeconds(5));

if (held is null) return;               // someone else runs it

await RunReportAsync(held.LockLost);    // stops if the lock is lost mid-run

• TryAcquireAsync returns null when the lock stayed taken; AcquireAsync throws TimeoutException.
• With AutoRenew (default) the lease is renewed every third of its length. If a whole lease passes without a successful renewal, or a renewal finds another owner, IsHeld turns false and LockLost is cancelled; pass that token to the guarded work.
• Disposing releases the lock; a failed release is swallowed because the lease expires on its own.

ASP.NET Core: [RuvioLock] for endpoints

Why. Some endpoints must never run twice at once for the same thing: charging an order, numbering an invoice, importing a file, closing a day. A lock or SemaphoreSlim only protects one instance. With two pods, or a double click that reaches a different pod, both requests run. [RuvioLock] moves the guard into Ruvio so it holds across every instance, and removes the acquire / try-finally / renew / map-to-HTTP boilerplate.

builder.Services.AddRuvioDistributedLock();          // needs an IRuvioClient registered
app.UseRouting();
app.UseAuthentication();
app.UseRuvioLock();                                  // after routing and auth

// minimal API
app.MapPost("/orders/{id}/pay", PayAsync).WithMetadata(new RuvioLockAttribute("order:{id}"));

// controller
[RuvioLock("nightly-import", leaseSeconds: 120, WaitMilliseconds = 0)]
[HttpPost("import")]
public Task<IActionResult> Import(CancellationToken ct) => ...;   // ct is cancelled if the lock is lost

Telemetry

Meter and ActivitySource Ruvio.AspNetCore.DistributedLock (same shape as the rate-limiting package): counters ruvio.lock.acquired, ruvio.lock.rejected (contention), ruvio.lock.lost (unhealthy server link) and ruvio.lock.errors, plus histogram ruvio.lock.wait_duration (ms). Fixed names are tagged resource; templated names are not, to keep cardinality bounded.

builder.Services.AddOpenTelemetry().WithMetrics(m => m.AddMeter(RuvioLockTelemetry.Name));

Limits

• One lock lives on one server. If a failover loses the key, two owners can overlap for up to a lease. Work that must never overlap should also check a version or fencing value on the resource it writes. This package does not issue fencing tokens: handing out an increasing number and taking the lock are two commands, so they cannot be made atomic here.
• Locks are not reentrant. Acquiring a held resource again from the same process waits like any caller.
• Lease times are wall-clock server TTLs; keep the lease well above the longest pause your process can have.