RepletoryLib.Caching.Redis 1.0.0

RepletoryLib.Caching.Redis

Redis implementation of ICacheService and IDistributedLockService with distributed locking via RedLock.

Part of the RepletoryLib ecosystem -- standalone, reusable .NET 10 libraries with zero business logic.

Overview

RepletoryLib.Caching.Redis provides a production-ready implementation of ICacheService and IDistributedLockService from RepletoryLib.Caching.Abstractions. It uses StackExchange.Redis for caching and RedLock.net for distributed locking.

This package is ideal for distributed applications where multiple instances need to share cache state and coordinate access to shared resources.

Key Features

• Distributed caching -- Share cache across multiple application instances via Redis
• Distributed locks -- RedLock algorithm for safe concurrent access across instances
• Prefix eviction -- Efficiently remove all keys matching a prefix using Redis SCAN
• Configurable retries -- Built-in retry count for transient Redis failures
• Compression -- Optional value compression to reduce memory usage

Installation

dotnet add package RepletoryLib.Caching.Redis

Or add to your .csproj:

<PackageReference Include="RepletoryLib.Caching.Redis" Version="1.0.0" />

Note: RepletoryLib packages are published to a local BaGet feed. See the main repository README for feed configuration.

Dependencies

Prerequisites

• Redis 7+ running and accessible

Start Redis with Docker:

docker-compose up -d redis
# Or standalone:
docker run -d -p 6379:6379 redis:7-alpine

Quick Start

using RepletoryLib.Caching.Redis;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRepletoryRedis(builder.Configuration);

{
  "RepletoryRedis": {
    "ConnectionString": "localhost:6379",
    "InstanceName": "myapp:",
    "DefaultExpiryMinutes": 60,
    "EnableCompression": false,
    "RetryCount": 3
  }
}

Configuration

RedisOptions

Section name: "RepletoryRedis"

Usage Examples

Caching with Redis

using RepletoryLib.Caching.Abstractions.Interfaces;

public class CatalogService
{
    private readonly ICacheService _cache;
    private readonly IProductRepository _repository;

    public CatalogService(ICacheService cache, IProductRepository repository)
    {
        _cache = cache;
        _repository = repository;
    }

    public async Task<Product?> GetProductAsync(Guid id)
    {
        return await _cache.GetOrSetAsync($"product:{id}", async () =>
        {
            return await _repository.GetByIdAsync(id);
        }, TimeSpan.FromMinutes(30));
    }

    public async Task UpdateProductAsync(Product product)
    {
        await _repository.UpdateAsync(product);

        // Invalidate all cached data for this product
        await _cache.RemoveByPrefixAsync($"product:{product.Id}:");
        await _cache.RemoveAsync($"product:{product.Id}");
    }
}

Distributed Locking

using RepletoryLib.Caching.Abstractions.Interfaces;

public class InventoryService
{
    private readonly IDistributedLockService _locks;

    public InventoryService(IDistributedLockService locks) => _locks = locks;

    public async Task<bool> ReserveStockAsync(Guid productId, int quantity)
    {
        // Only one instance can reserve stock for this product at a time
        var lockId = await _locks.AcquireAsync(
            resource: $"stock-reserve:{productId}",
            expiry: TimeSpan.FromSeconds(10));

        if (lockId is null)
            return false; // Another instance is reserving

        try
        {
            var stock = await GetCurrentStockAsync(productId);
            if (stock < quantity) return false;

            await DeductStockAsync(productId, quantity);
            return true;
        }
        finally
        {
            await _locks.ReleaseAsync(lockId);
        }
    }
}

Cache-Aside with Expiry

// Short-lived cache for frequently changing data
await _cache.SetAsync("exchange-rate:USD-ZAR", rate, TimeSpan.FromMinutes(5));

// Long-lived cache for stable reference data
await _cache.SetAsync("countries", countries, TimeSpan.FromHours(24));

// Check existence before expensive operation
if (!await _cache.ExistsAsync($"report:{reportId}"))
{
    var report = await GenerateReportAsync(reportId);
    await _cache.SetAsync($"report:{reportId}", report, TimeSpan.FromHours(1));
}

Integration with Other RepletoryLib Packages

Testing

For unit tests, use MockCacheService from RepletoryLib.Testing. For integration tests with real Redis, use RepletoryLib.Testing.Fixtures:

using RepletoryLib.Testing.Fixtures;

public class RedisCacheIntegrationTests : IntegrationTestBase, IClassFixture<RedisFixture>
{
    public RedisCacheIntegrationTests(RedisFixture fixture) : base(fixture) { }

    [Fact]
    public async Task SetAndGet_roundtrips_value()
    {
        var cache = new RedisCacheService(/* configured with RedisConnectionString */);

        await cache.SetAsync("test-key", "test-value", TimeSpan.FromMinutes(1));
        var result = await cache.GetAsync<string>("test-key");

        result.Should().Be("test-value");
    }
}

Troubleshooting

License

This project is licensed under the MIT License.

Copyright (c) 2024-2026 Repletory.

For complete documentation, infrastructure setup, and configuration reference, see the RepletoryLib main repository.