jaytwo.DistributedLocks 0.1.0-beta-20251122220232

jaytwo.DistributedLocks

Package
jaytwo.DistributedLocks
jaytwo.DistributedLocks.Postgres
jaytwo.DistributedLocks.MySql
jaytwo.DistributedLocks.RedLock
jaytwo.DistributedLocks.SqlServer

jaytwo.DistributedLocks is a .NET abstraction layer for distributed locking across multiple providers including in-memory, MySQL, PostgreSQL, and Redis (via RedLock), and SQL Server. It provides a consistent interface for acquiring and managing distributed locks in both sync and async contexts.

Features

• Unified interface for multiple distributed lock backends
• Support for both IDisposable and IAsyncDisposable
• Customizable acquisition timeouts
• Built-in health checks with HealthCheckAsync()
• Available providers:
  • In-memory (single process)
  • MySQL
  • PostgreSQL
  • Redis (RedLock.NET)
  • SqlServer

Installation

Install the NuGet package(s) that match your backend:

PM> Install-Package jaytwo.DistributedLocks              # Core abstractions
PM> Install-Package jaytwo.DistributedLocks.MySql        # MySQL provider
PM> Install-Package jaytwo.DistributedLocks.Postgres     # PostgreSQL provider
PM> Install-Package jaytwo.DistributedLocks.RedLock      # Redis (RedLock.NET) provider
PM> Install-Package jaytwo.DistributedLocks.SqlServer    # SQL Server provider

Usage

Lock Namespaces

Lock namespaces let you isolate lock keys by environment and app so different services (or dev/test/prod) don't fight over the same "resource" name. Each provider qualifies your resource as "{LockNamespace}:{resource}" (or a hashed equivalent) before acquiring the lock—e.g., orders:charge-123—so "orders:charge-123" in stage never collides with "orders:charge-123" in dev.

If you don't specify one, helpers build a sensible default from your application name plus ASPNETCORE_ENVIRONMENT / DOTNET_ENVIRONMENT, and they'll log a warning if no environment is present.

Some backends also hash the qualified name to meet engine limits—MySQL and SQL Server convert to stable hex strings (for MySQL's shorter GET_LOCK name and SQL Server's sp_getapplock nvarchar limit), while Postgres maps the qualified name to a 64-bit integer advisory lock key.

Acquire and Release a Lock

Locks are automatically released when disposed:

await using (var myLock = await provider.CreateLockAsync("my-key"))
{
    if (!myLock.IsAcquired)
    {
        Console.WriteLine("Could not acquire lock");
        return;
    }

    // Critical section
}

Set a Custom Wait Timeout

await using var myLock = await provider.CreateLockAsync("my-key", waitTime: TimeSpan.FromSeconds(5));

Health Check

You can check the health of the underlying lock provider. This is useful for monitoring and diagnostics:

var healthCheckResult = await provider.HealthCheckAsync();

Background

RedLock.NET is great, but I don't love the polling nature of the RedLock algorithm, and many smaller apps aren't connected to a Redis instance. Most SQL-based systems already support advisory locking or built-in mutex mechanisms. This library provides a consistent API across different database backends, giving you the flexibility to use what you already have deployed.

When to Use

Use jaytwo.DistributedLocks when you need:

• Coordination across distributed services or processes
• A lightweight alternative to full orchestration frameworks
• Backend flexibility without rewriting business logic
• Locking via familiar SQL databases or Redis

Typical scenarios:

• Distributed job scheduling
• Coordinating background workers
• Ensuring single execution of batch jobs
• Preventing double-processing across instances

Made with ♥ by Jake — Licensed under the MIT License