RepletoryLib.Caching.Hybrid 1.0.0

RepletoryLib.Caching.Hybrid

L1/L2 hybrid cache combining in-memory speed with Redis distributed consistency.

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

Overview

RepletoryLib.Caching.Hybrid implements ICacheService using a two-tier caching strategy:

• L1 (In-Memory) -- Ultra-fast, zero-latency local cache for hot data
• L2 (Redis) -- Distributed cache shared across all application instances

On a cache read, L1 is checked first. On a miss, L2 is checked and the result is promoted to L1. On a write or invalidation, both layers are updated and other instances are notified via Redis pub/sub to evict their L1 entries.

This gives you the speed of in-memory caching with the consistency of distributed caching.

Key Features

• Two-tier caching -- L1 (IMemoryCache) + L2 (Redis) with automatic promotion
• L1 invalidation via pub/sub -- Redis pub/sub notifies all instances when cache entries change
• Configurable TTLs -- Independent expiry for L1 and L2 layers
• Transparent -- Drop-in replacement for any ICacheService implementation

Installation

dotnet add package RepletoryLib.Caching.Hybrid

Or add to your .csproj:

<PackageReference Include="RepletoryLib.Caching.Hybrid" 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 (for L2 and pub/sub)

docker-compose up -d redis

Quick Start

using RepletoryLib.Caching.Hybrid;

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

{
  "RepletoryRedis": {
    "ConnectionString": "localhost:6379",
    "InstanceName": "myapp:",
    "DefaultExpiryMinutes": 60
  },
  "RepletoryHybridCache": {
    "L1ExpiryMinutes": 5,
    "L2ExpiryMinutes": 60
  }
}

Configuration

HybridCacheOptions

Section name: "RepletoryHybridCache"

L1 expiry should always be shorter than L2. This ensures stale local data is naturally evicted even if a pub/sub message is missed.

Usage Examples

How It Works

GET "user:123"
  ├─ L1 (InMemory) HIT → return immediately (sub-microsecond)
  └─ L1 MISS
       ├─ L2 (Redis) HIT → promote to L1, return
       └─ L2 MISS
            └─ Factory executes → store in L2, store in L1, return

SET "user:123"
  ├─ Store in L1 (local)
  ├─ Store in L2 (Redis)
  └─ Publish invalidation via Redis pub/sub → other instances evict L1

REMOVE "user:123"
  ├─ Remove from L1 (local)
  ├─ Remove from L2 (Redis)
  └─ Publish invalidation → other instances evict L1

Using the Hybrid Cache

using RepletoryLib.Caching.Abstractions.Interfaces;

public class ProductService
{
    private readonly ICacheService _cache;

    public ProductService(ICacheService cache) => _cache = cache;

    public async Task<Product?> GetProductAsync(Guid id)
    {
        // First call: misses L1 and L2, loads from DB, caches in both
        // Second call (same instance): hits L1, returns in <1ms
        // Second call (different instance): hits L2, promotes to L1
        return await _cache.GetOrSetAsync($"product:{id}", async () =>
        {
            return await _repository.GetByIdAsync(id);
        });
    }

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

        // Removes from L1, L2, and notifies other instances
        await _cache.RemoveAsync($"product:{product.Id}");
    }
}

When to Use Hybrid vs Redis-Only

Integration with Other RepletoryLib Packages

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.