Faactory.Leases.Redis 1.0.3

Distributed Coordination

Minimal abstractions for coordinating work across multiple instances.

Provides two independent primitives:

• Distributed leases: coordinate who runs
• Distributed timers: coordinate when work runs

They can be used separately or combined.

Concepts

Lease

A lease represents temporary ownership of a resource.

Used for:

• leader election
• singleton work
• coordinated execution across instances

Timer

A timer represents a shared periodic schedule.

Used for:

• periodic background tasks
• coordinated execution across instances
• restart-safe scheduling without cron

Behavior:

• first execution occurs after the configured period
• subsequent executions occur at the same interval, aligned to the initial schedule
• timer state survives restarts while the backend persists the timer key
• all instances align on the same schedule

Registration

Depending on the underlying implementation, different dependencies are required.

Redis

To use Redis, install both Redis and the distributed coordination packages:

dotnet add package StackExchange.Redis
dotnet add package Faactory.Leases.Redis

Leases

services.AddRedisDistributedLeases( options =>
{
    options.KeyPrefix = "leases";
} );

Timers

services.AddRedisDistributedTimers( options =>
{
    options.KeyPrefix = "timers";
} );

NATS

To use NATS, install both NATS and the distributed coordination packages:

dotnet add package NATS.Client
dotnet add package Faactory.Leases.NATS

Leases

services.AddNatsDistributedLeases( options =>
{
    options.BucketName = "leases";
    options.BucketMarkerTtl = TimeSpan.FromMinutes( 5 );
    options.KeyPrefix = "leases";
} );

Timers

services.AddNatsDistributedTimers( options =>
{
    options.BucketName = "timers";
    options.KeyPrefix = "timers";
} );

Usage

Acquiring a lease

public sealed class MyService( IDistributedLeaseStore leaseStore )
{
    public async Task ExecuteAsync( CancellationToken cancellationToken )
    {
        var leaseHandle = await leaseStore.TryAcquireAsync(
            "my-lease",
            Guid.NewGuid().ToString(),
            TimeSpan.FromSeconds( 30 ),
            cancellationToken
        );

        if ( leaseHandle is null )
        {
            // failed to acquire lease
            return;
        }

        await using var lease = new DistributedLease(
            leaseStore,
            leaseHandle,
            TimeSpan.FromSeconds( 10 )
        );

        // do work while lease is held
    }
}

Periodic execution

public sealed class MyService( IDistributedTimerStore timerStore )
{
    public async Task ExecuteAsync( CancellationToken cancellationToken )
    {
        var timer = new DistributedTimer(
            timerStore,
            "my-timer",
            TimeSpan.FromMinutes( 10 )
        );

        while ( await timer.WaitForNextTickAsync( cancellationToken ) )
        {
            // periodic work
        }
    }
}

Combining leases and timers

public sealed class MyService(
    IDistributedLeaseStore leaseStore,
    IDistributedTimerStore timerStore
)
{
    public async Task ExecuteAsync( CancellationToken cancellationToken )
    {
        var timer = new DistributedTimer(
            timerStore,
            "my-timer",
            TimeSpan.FromMinutes( 10 )
        );

        while ( await timer.WaitForNextTickAsync( cancellationToken ) )
        {
            // non-leader work can be done here (if any)

            var leaseHandle = await leaseStore.TryAcquireAsync(
                "my-lease",
                Guid.NewGuid().ToString(),
                TimeSpan.FromSeconds( 30 ),
                cancellationToken
            );

            if ( leaseHandle is null )
            {
                continue;
            }

            await using var lease = new DistributedLease(
                leaseStore,
                leaseHandle,
                TimeSpan.FromSeconds( 10 )
            );

            // leader-only periodic work
        }
    }
}

Convenience APIs

The library also provides optional convenience base classes for hosted services.

LeasedService

Convenience base class for leased services with opiniated defaults. Handles lease acquisition and renewal, allowing you to focus on the leader-only work.

public sealed class MyService( ILoggerFactory loggerFactory, IDistributedLeaseStore leaseStore )
    : LeasedService( loggerFactory, leaseStore )
{
    protected override async Task ExecuteLeaderAsync( CancellationToken cancellationToken )
    {
        // leader-only work
    }
}

PeriodicLeasedService

Convenience base class for periodic leased services with opiniated defaults. Handles lease acquisition, renewal, and periodic execution, allowing you to focus on the leader-only work.

public sealed class MyService(
    ILoggerFactory loggerFactory,
    IDistributedLeaseStore leaseStore,
    IDistributedTimerStore timerStore
)
    : PeriodicLeasedService( loggerFactory, leaseStore, timerStore )
{
    protected override TimeSpan ExecutionInterval
        => TimeSpan.FromMinutes( 10 );

    protected override Task RunAsync( CancellationToken cancellationToken )
    {
        // leader-only periodic work

        return Task.CompletedTask;
    }
}

Redis Implementation

Leases

• SET NX PX for acquisition
• Lua scripts for safe renew/release
• owner-checked operations

Timers

• Redis TTL defines the timer window
• Lua script creates the timer if missing
• key expiration drives the next tick

NATS Implementation

Uses NATS JetStream KV storage for leases and timers.

Leases rely on bucket markers, which require NATS Server v2.11+.