RepletoryLib.Caching.Redis8 1.0.0

RepletoryLib.Caching.Redis8

Redis 8 cache provider for RepletoryLib. Implements ICacheService and IDistributedLockService from RepletoryLib.Caching.Abstractions and adds first-class wrappers for the new data types and protocol features introduced in Redis 8.

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

When to choose Redis 8 over Caching.Redis

This package is a separate, opt-in provider -- both Redis 7 (RepletoryLib.Caching.Redis) and Redis 8 (RepletoryLib.Caching.Redis8) implement the same abstractions. Pick whichever matches the Redis server version your environment targets:

The two providers can coexist in a solution -- register only one of them in a given service.

What's new compared to Caching.Redis

Installation

dotnet add package RepletoryLib.Caching.Redis8

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

Dependencies

Prerequisites

• Redis 8+ running and accessible.

Update your docker-compose.yml to use the Redis 8 image:

redis:
  image: redis:8-alpine          # bundles JSON, Search, Bloom, Vector
  container_name: repletorylib-redis
  ports:
    - "6379:6379"

Quick start

using RepletoryLib.Caching.Redis8;

builder.Services.AddRepletoryRedis8(builder.Configuration);

{
  "RepletoryRedis8": {
    "ConnectionString": "localhost:6379",
    "InstanceName": "myapp",
    "DefaultExpiryMinutes": 60,
    "UseResp3": true,
    "UseNativeJson": true,
    "EnableClientTracking": false,
    "ClientTrackingPrefixes": [],
    "BloomFilterDefaultCapacity": 100000,
    "BloomFilterDefaultErrorRate": 0.01,
    "UseUnlinkForBulkDelete": true,
    "RetryCount": 3
  }
}

AddRepletoryRedis8 registers:

Configuration

Redis8Options -- section RepletoryRedis8

Usage

Standard cache (same API as ICacheService elsewhere)

public class CatalogService(ICacheService cache, IProductRepository repository)
{
    public Task<Product?> GetProductAsync(Guid id) =>
        cache.GetOrSetAsync(
            key: $"product:{id}",
            factory: () => repository.GetByIdAsync(id),
            expiry: TimeSpan.FromMinutes(30));
}

With UseNativeJson = true (default) the value is stored as a native JSON document, so any other client (or another IRedisJsonCacheService consumer) can read or patch sub-paths of the same key without re-serialising the whole entry.

Partial updates via JSONPath

public class UserProfileService(IRedisJsonCacheService json)
{
    public Task PatchEmailAsync(Guid userId, string newEmail) =>
        json.MergeAsync(
            key: $"user:{userId}",
            patch: new { email = newEmail });   // only the "email" field is rewritten server-side

    public Task<int> IncrementLoginCountAsync(Guid userId) =>
        json.IncrementAsync($"user:{userId}", "$.loginCount", 1)
            .ContinueWith(t => (int)t.Result);

    public Task<string?> GetEmailAsync(Guid userId) =>
        json.GetAsync<string>($"user:{userId}", "$.email");
}

Hash field TTL -- per-tenant or per-user sets

// Store every active session for a user under a single hash, each with its own TTL.
await hashCache.SetFieldAsync(
    hashKey: $"sessions:{userId}",
    field:   sessionId,
    value:   sessionData,
    expiry:  TimeSpan.FromMinutes(15));

await hashCache.ExpireFieldAsync($"sessions:{userId}", sessionId, TimeSpan.FromMinutes(15)); // slide
var ttl = await hashCache.GetFieldTtlAsync($"sessions:{userId}", sessionId);

This keeps related entries grouped under one Redis key (so they can be enumerated cheaply) while still expiring them independently -- something plain HSET could not do before Redis 7.4 / 8.

Bloom filter -- cache stampede prevention

public class ProductLookup(IBloomFilterService bloom, IProductRepository repo, ICacheService cache)
{
    private const string KnownProductsFilter = "known-products";

    public async Task EnsureFilterAsync() =>
        await bloom.ReserveAsync(KnownProductsFilter, capacity: 5_000_000, errorRate: 0.001);

    public async Task<Product?> GetAsync(string sku)
    {
        // Skip the DB lookup for SKUs we have never seen before.
        if (!await bloom.ExistsAsync(KnownProductsFilter, sku))
            return null;

        return await cache.GetOrSetAsync($"product:{sku}", () => repo.GetBySkuAsync(sku));
    }

    public async Task RegisterAsync(Product product)
    {
        await bloom.AddAsync(KnownProductsFilter, product.Sku);
    }
}

Top-K -- identify hot keys for promotion to L1

await topK.ReserveAsync("hot-keys", topK: 50);

// In your read path:
await topK.AddAsync("hot-keys", new[] { cacheKey });

// Periodically, in a Worker:
var hotKeys = await topK.ListAsync("hot-keys");
foreach (var key in hotKeys)
    inMemoryCache.Set(key, await cache.GetAsync<object>(key));

Pairs neatly with RepletoryLib.Caching.Hybrid for telemetry-driven L1 promotion.

Vector cache -- semantic search

public class SemanticCache(IVectorCacheService vectors, IEmbeddingService embeddings)
{
    public async Task IndexAsync(string id, string content)
    {
        var embedding = await embeddings.EmbedAsync(content);
        await vectors.AddAsync("docs", id, embedding.AsMemory());
    }

    public async Task<IReadOnlyList<VectorSearchResult>> FindSimilarAsync(string query, int k = 5)
    {
        var queryEmbedding = await embeddings.EmbedAsync(query);
        return await vectors.SearchAsync("docs", queryEmbedding.AsMemory(), count: k);
    }
}

Plugs into RepletoryLib.Ai.SemanticSearch as a Redis-resident replacement for the in-memory similarity index.

Distributed locks

Identical API to RepletoryLib.Caching.Redis -- use IDistributedLockService exactly the same way.

How it integrates with the rest of RepletoryLib

Server-assisted client tracking

When EnableClientTracking = true (requires UseResp3 = true), the package issues CLIENT TRACKING ON BCAST NOLOOP after connecting. Redis will then push invalidation notifications to this client for keys matching the configured ClientTrackingPrefixes, allowing a downstream L1 cache to evict stale entries with no pub/sub overhead.

Wire the push handler in your own L1 cache, e.g.:

multiplexer.GetSubscriber().Subscribe(RedisChannel.Literal("__redis__:invalidate"), (_, message) =>
{
    foreach (var key in message.ToString().Split(','))
        memoryCache.Remove(key);
});

Testing

For unit tests, use MockCacheService from RepletoryLib.Testing. For integration tests against a real Redis 8, point your testcontainer at the redis:8-alpine image and re-use the RedisFixture from RepletoryLib.Testing.Fixtures.

Troubleshooting

License

This project is licensed under the MIT License.

Copyright (c) 2024-2026 Repletory.