Soenneker.Redis.WorkQueue 11.0.173

Soenneker.Redis.WorkQueue

A durable, partition-aware Redis work queue with scheduling, leases, retries, deduplication, and round-robin fairness.

Installation

dotnet add package Soenneker.Redis.WorkQueue

Registration

services.AddRedisWorkQueueAsSingleton<SendMessageWork>("send-message", options =>
{
    options.MaxConcurrentItemsPerPartition = 2;
    options.ClaimLeaseDuration = TimeSpan.FromMinutes(1);
    options.MaximumAttempts = 10;
    options.MaintenanceInterval = TimeSpan.FromSeconds(1);
});

Registration starts a background maintenance service by default. Every process may register it; a distributed Redis semaphore ensures that only one process maintains a logical queue at a time. Set EnableBackgroundMaintenance to false only when another component calls RunMaintenance periodically.

AddRedisWorkQueueAsScoped<T>() scopes the queue and semaphore wrappers while retaining the shared Redis client transport. Disposing a scope does not close the application's Redis connection.

The partition key is the fairness and concurrency boundary. For a multi-tenant application, for example, use the business ID. Ready partitions are dispatched round-robin, and Soenneker.Redis.Semaphores prevents more than the configured number of claims for one partition across every process.

Enqueue and process

await queue.Enqueue(new RedisWorkQueueItem<SendMessageWork>
{
    Id = message.Id,
    PartitionKey = message.BusinessId,
    Value = new SendMessageWork(message.Id),
    AvailableAt = DateTimeOffset.UtcNow // set a future value to schedule it
}, cancellationToken);

await using RedisWorkQueueClaim<SendMessageWork>? claim =
    await queue.TryClaim(workerId, cancellationToken);

if (claim is null)
    return;

try
{
    await Process(claim.Item.Value, claim.OwnershipLostToken);
    await queue.Complete(claim, cancellationToken);
}
catch (Exception exception)
{
    await queue.Retry(claim, new RedisWorkQueueFailure
    {
        Reason = exception.GetType().Name,
        Details = exception.Message
    }, TimeSpan.FromSeconds(10), cancellationToken);
    throw;
}

The queue provides at-least-once delivery. Claims automatically renew both their work-item lease and their partition semaphore permit. Background maintenance promotes scheduled items, recovers expired claims, repairs ready partitions, and expires completed-item deduplication markers.

Retry moves work to the dead-letter store when it reaches MaximumAttempts. Use GetDeadLetter and RequeueDeadLetter to inspect and recover valid items. Missing or unreadable payloads are dead-lettered automatically so they cannot block a partition. Use Abandon when a healthy worker needs to relinquish a claim immediately without treating it as a processing failure.

The implementation uses typed Soenneker.Redis.Util operations and Redis transactions with optimistic conditions. It does not use Redis scripts.