EdiHybridCache 0.5.6

🚀 EdiHybridCache - Event Driven Cache Invalidation with Hybrid Cache

The .NET Hybrid Cache Library — Blazing Fast, Battle-Tested, Enterprise-Ready

Why EdiHybridCache?

Hybrid caching combines the speed of in-process memory (L1) with the durability and sharing of Redis (L2). EdiHybridCache takes this further with:

• ⚡ L1: IMemoryCache — microsecond reads, zero network
• 📡 L2: Redis — shared across instances, persistent
• 🧠 Event-driven invalidation: RabbitMQ fanout — invalidate all L1s instantly
• 🛡️ Anti-stampede: Per-key async locking — only one request hits Redis
• 🔁 Resilience: Polly retries with exponential backoff + jitter
• 📦 Compression: GZip for large values
• 🔒 Secure by design: CWE-409, CWE-502, CWE-754, CWE-295, CWE-770 mitigated

📊 Performance

📦 Installation

dotnet add package EdiHybridCache

Or reference the project directly:

<ProjectReference Include="..\src\EdiHybridCache\EdiHybridCache.csproj" />

🔏 Verifying Package Signature (Sigstore)

Every NuGet release is signed with Sigstore using a private key stored as a GitHub Actions secret. The public key (cosign.pub) is available in the repository and in every workflow artifact.

1. Download the .sig file for the release version from the workflow artifacts and the public key from the repo root.
2. Verify with cosign:

cosign verify-blob \
  --key cosign.pub \
  --signature EdiHybridCache.X.Y.Z.nupkg.sig \
  EdiHybridCache.X.Y.Z.nupkg

Replace X.Y.Z with the actual version number. Verification succeeds if the package was signed by the trusted private key.

🔧 Quick Start

1. Register in DI

// Program.cs
builder.Services.AddEdiHybridCache(builder.Configuration);

2. Configure appsettings.json

{
  "EdiHybridCache": {
    "RedisConnectionString": "localhost:6379",
    "RabbitMqHost": "localhost",
    "L1TtlSeconds": 300,
    "DefaultL2TtlSeconds": 3600,
    "EnableCompression": true
  }
}

3. Inject and Use

public class MyService
{
    private readonly IHybridCache _cache;

    public MyService(IHybridCache cache) => _cache = cache;

    public async Task<string?> GetUserAsync(int id)
    {
        var key = $"user:{id}";
        return await _cache.GetAsync<string>(key);
    }

    public async Task SetUserAsync(int id, string data)
    {
        var key = $"user:{id}";
        await _cache.SetAsync(key, data, TimeSpan.FromMinutes(30));
    }

    public async Task RemoveUserAsync(int id)
    {
        var key = $"user:{id}";
        await _cache.RemoveAsync(key);
    }
}

4. Start the Invalidation Subscriber (optional)

using (var scope = app.Services.CreateScope())
{
    await scope.ServiceProvider.UseEdiHybridCacheSubscriberAsync();
}

🏗️ Architecture

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  Instance A  │     │  Instance B  │     │  Instance C  │
│  ┌───────┐   │     │  ┌───────┐   │     │  ┌───────┐   │
│  │  L1   │   │     │  │  L1   │   │     │  │  L1   │   │
│  │Memory │   │     │  │Memory │   │     │  │Memory │   │
│  └───┬───┘   │     │  └───┬───┘   │     │  └───┬───┘   │
│      │       │     │      │       │     │      │       │
│  ┌───▼───┐   │     │  ┌───▼───┐   │     │  ┌───▼───┐   │
│  │  L2   │   │     │  │  L2   │   │     │  │  L2   │   │
│  │ Redis │   │     │  │ Redis │   │     │  │ Redis │   │
│  └───────┘   │     │  └───────┘   │     │  └───────┘   │
│      │       │     │      │       │     │      │       │
└──────┼───────┘     └──────┼───────┘     └──────┼───────┘
       │                    │                    │
       └──────────┬─────────┴──────────┬─────────┘
                  │                    │
          ┌───────▼───────┐    ┌───────▼───────┐
          │   RabbitMQ    │    │   RabbitMQ    │
          │  Exchange     │    │  Queue (each  │
          │  (Fanout)     │───▶│   instance)   │
          └───────────────┘    └───────────────┘

L1 — In-Process Memory

• Provider: Microsoft.Extensions.Caching.Memory
• Latency: 1.28 μs (microseconds)
• Allocation: 144 B per hit (dropping to ~104 B with ValueTask)
• Scope: Per-instance, ephemeral

L2 — Redis

• Provider: StackExchange.Redis
• Persistence: Shared across all instances
• Resilience: Automatic retry via Polly (exponential backoff 1s → 2s → 4s + jitter)
• Connection: Singleton via DI

Event-Driven Invalidation

• Provider: RabbitMQ fanout exchange
• Flow: RemoveAsync → publish event → all subscribers receive → each clears its L1
• Graceful degradation: If RabbitMQ is unavailable, invalidation events are skipped with a warning
• Durable: Messages are persistent; queues are auto-deleted per instance

📚 API Reference

ValueTask<T?> GetAsync<T>(string key, CancellationToken ct = default)

Retrieves a value from the cache.

Behavior:

1. Check L1 (memory) → if found, return immediately (synchronous ValueTask, zero Task allocation)
2. Acquire per-key async lock
3. Double-check L1 (anti-stampede)
4. Read from L2 (Redis) with Polly retry
5. If found, populate L1 and return
6. If not found, return null

var user = await cache.GetAsync<User>("user:42");
// Returns null if not found

Task SetAsync<T>(string key, T value, TimeSpan? ttlL2 = null, CancellationToken ct = default)

Stores a value in the cache.

Behavior:

1. Validate key length (max 512 chars)
2. Serialize value with System.Text.Json (camelCase)
3. Optionally compress with GZip (threshold configurable)
4. Write to L1 (memory) - always
5. Write to L2 (Redis) with Polly retry
6. Log the operation

await cache.SetAsync("user:42", user, TimeSpan.FromMinutes(30));
// Uses L1 TTL from config, L2 TTL = 30min (adjusted if below minimum)

TTL Adjustment:

• If ttlL2 < L1TtlSeconds × L2TtlMultiplier, it's automatically raised to the minimum
• This prevents race conditions where L2 expires before L1

Task RemoveAsync(string key, CancellationToken ct = default)

Removes a value from the cache and notifies other instances.

Behavior:

1. Remove from L1 (memory)
2. Delete from L2 (Redis) with Polly retry
3. Publish invalidation event via RabbitMQ (best-effort)

await cache.RemoveAsync("user:42");

Task PublishInvalidationAsync(string key, CancellationToken ct = default)

Publishes an invalidation event without modifying the local cache. Useful when another service writes directly to Redis.

await cache.PublishInvalidationAsync("user:42");

void InvalidateLocal(string key)

Synchronously removes a value from L1 only. No network I/O.

if (cache is HybridCache hc)
    hc.InvalidateLocal("user:42");

🔒 Security

📈 Benchmark Results

BenchmarkDotNet v0.14.0, .NET 10.0.9, AMD Ryzen 7 5700U
9 benchmarks, 2 warmup, 5 iterations each

Key takeaways:

• GetAsync L1 Hit in 2.23 μs, 72 B allocated — Zero-allocation fast path via synchronous lock acquisition
• SetAsync 10KB + compress: 45% less allocations (22 KB → 11.9 KB) after removing extra MemoryStream copy in TryDecompress
• Zero LOH allocations on hot paths — ArrayPool<byte> + struct Releaser + ReadOnlySpan
• LoggerMessage.Define eliminated params object[] allocation, saving ~32 B per hot log call

🧪 k6 Load Test

Standalone (direct Redis connection)

15,164 req/s · 0% failure · p(95) = 226 ms · 5,000 VUs
1,289,184 total requests, 1,718,912 checks passed ✅

Aspire AppHost (with DCP proxy)

14,063 req/s · 0% failure · p(95) = 225 ms · 5,000 VUs
1,195,692 total requests, 1,594,256 checks passed ✅

Test scenario: Set → Get(L1) → InvalidateLocal → Get(L2) → Remove → Get(Miss) (6 requests/iteration)

Status Final

📊 Code Coverage

Per-Class Coverage

📉 Code Quality & Complexity

Cyclomatic Complexity Reduction

CRAP Score Improvement

CRAP = (CC²) × (1 − coverage)³ + CC

Clean Code Practices

• ✅ DRY: RedisSafeExecuteAsync<T> extracted from 3 repetitions
• ✅ DRY: TryOverrideFromEnv / TryParseEnvInt / TryParseEnvDouble replace 8 repetitions
• ✅ DRY: ValidateMaxSize extracted from 2 repetitions
• ✅ Single Responsibility: Each method does one thing
• ✅ Early Return: No else branches — early exit pattern
• ✅ Static members before instance (SA1204 compliance)
• ✅ Zero params object[] in hot path logs (LoggerMessage.Define)
• ✅ No magic strings — all constants named

⚙️ Configuration

Environment Variables

appsettings.json Example

{
  "EdiHybridCache": {
    "RedisConnectionString": "localhost:6379",
    "RabbitMqHost": "localhost",
    "RabbitMqPort": 5672,
    "RabbitMqUseSsl": false,
    "L1TtlSeconds": 300,
    "DefaultL2TtlSeconds": 3600,
    "L2TtlMultiplier": 1.5,
    "EnableCompression": true,
    "CompressionThresholdBytes": 4096,
    "RetryCount": 3,
    "RetryBaseDelaySeconds": 1
  }
}

🧰 How to Run

Docker (Redis + RabbitMQ)

Start the required infrastructure (Redis and RabbitMQ) with Docker Compose:

docker-compose up -d

This starts:

• Redis on localhost:6379
• RabbitMQ on localhost:5672 (AMQP) and localhost:15672 (Management UI — guest/guest)

Standalone

# Build
dotnet build

# Run tests
dotnet test tests/EdiHybridCache.Tests

# Run benchmarks
dotnet run -c Release --project benchmarks/EdiHybridCache.Benchmarks

# Run the playground (Web API with Swagger) - requires Redis + RabbitMQ
# (start docker-compose first, or have Redis + RabbitMQ running locally)
dotnet run --project playground/EdiHybridCache.Playground
# Swagger UI: http://localhost:5000/swagger/index.html
# API base URL: http://localhost:5000

# Run k6 load test (while playground is running)
k6 run k6-load-test.js

With Aspire AppHost (recommended)

The Aspire AppHost automatically provisions Redis and RabbitMQ containers, injects environment variables, and starts the Playground:

dotnet run --project src/EdiHybridCache.AppHost/EdiHybridCache.AppHost.csproj

The dashboard will be available at https://localhost:XXXXX (random port). Redis and RabbitMQ credentials are auto-generated — no manual configuration needed.

🏗️ Project Structure

EdiHybridCache/
├── src/EdiHybridCache/           # 📚 Library source
│   ├── Cache/
│   │   ├── HybridCache.cs        # Core implementation
│   │   ├── IHybridCache.cs       # Public interface
│   │   ├── HybridCacheOptions.cs # Configuration options
│   │   ├── AsyncLock.cs          # Per-key async locking
│   │   ├── CacheMetrics.cs       # OpenTelemetry metrics
│   │   ├── CompressionHelper.cs  # GZip compression (ArrayPool)
│   │   ├── Constants.cs          # Central constants
│   │   └── Invalidation/
│   │       ├── ICacheInvalidationPublisher.cs
│   │       ├── ICacheInvalidationSubscriber.cs
│   │       ├── RabbitMqInvalidationPublisher.cs
│   │       └── RabbitMqInvalidationSubscriber.cs
│   ├── Configuration/
│   │   └── HybridCacheServiceCollectionExtensions.cs
│   └── EdiHybridCache.csproj     # NuGet package
├── src/EdiHybridCache.AppHost/  # 🚀 Aspire orchestration
│   ├── Program.cs               # AppHost entry point
│   ├── AppHostConstants.cs      # Resource names & env vars
│   └── EdiHybridCache.AppHost.csproj
├── tests/                        # ✅ Unit tests (26/26 passing)
│   └── EdiHybridCache.Tests/
├── benchmarks/                   # ⚡ Performance benchmarks
│   └── EdiHybridCache.Benchmarks/
├── playground/                   # 🎮 Sample Web API (Swagger)
│   └── EdiHybridCache.Playground/
├── k6-load-test.js               # 📊 Load testing script
└── README.md

🧠 Anti-Stampede (Cache Stampede Protection)

When a popular key expires in L1 and multiple requests arrive simultaneously, only one request hits Redis:

using (await _asyncLock.LockAsync(key, cancellationToken))
{
    // Double-check: if another thread already populated L1, return it
    if (_memoryCache.TryGetValue(key, out cached))
        return cached;

    // Only ONE request reaches Redis
    var redisValue = await _redisDb.StringGetAsync(key);
}

🔁 Resilience

• Redis retries: Automatic Polly retry policy (configurable count + exponential backoff + jitter)
• RabbitMQ retries: Separate Polly retry policy for publisher; background reconnection with exponential backoff (1s → 60s max) for subscriber
• Graceful degradation: If RabbitMQ is down, cache continues operating; invalidation events are skipped with a warning; subscriber retries in background
• Timeouts: Configurable RedisOperationTimeoutSeconds (default: 5s)
• Connection tuning: AbortOnConnectFail=false, SyncTimeout=5s, KeepAlive=60s, ReconnectRetryPolicy for StackExchange.Redis

🔒 Security Features

• Key length validation: Max 512 characters (ArgumentException)
• Value size cap: Max 100 MB (LogWarning + skip)
• ZIP bomb protection: Hard cap on decompression buffer doubling; leftover byte detection
• Cache poisoning prevention: TypeNameHandling is not supported by System.Text.Json; JsonException is caught and logged with "Possible cache poisoning"
• Deadlock prevention: No .GetAwaiter().GetResult() in constructors (CWE-754)
• SSL/TLS: Configurable for RabbitMQ connections
• Log injection prevention: Structured logging via LoggerMessage.Define — no params object[] on hot paths

⚖️ License

MIT License — Free to use, modify, distribute, and incorporate into any project (commercial or not). No attribution required, though appreciated.

Copyright © 2026 Valdomiro Galo ·

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.