Hellnet.Cache 1.1.9

Hellnet.Cache

Multi-layer cache library for .NET with L1 (memory), L2 (Valkey/Redis), and optional External cache provider. Write-through, read-through, stampede-protected, env-first configuration.

Layers

Quick start

dotnet add package Hellnet.Cache

using Hellnet.Cache;

// ── Env-first (recommended) ────────────────────────────
// Throws if HELLNET_CACHE_VALKEY_CONNECTION or
// HELLNET_CACHE_VALKEY_PASSWORD are missing.
builder.Services.AddHellnetCache();

// ── Explicit — no validation ───────────────────────────
// You are responsible for providing valid values.
builder.Services.AddHellnetCache(new HellnetCacheOptions
{
    ValkeyConnection = "valkey.hellnet.com.br:6379",
    ValkeyPassword = "hellnet2026",
});

Minimal env config (env-first)

# Required — without these, AddHellnetCache() throws at startup
export HELLNET_CACHE_VALKEY_CONNECTION=valkey.hellnet.com.br:6379
export HELLNET_CACHE_VALKEY_PASSWORD=hellnet2026

Se esquecer de setar, o erro é claro:

Hellnet.Cache: AddHellnetCache() failed — required environment variables are missing:

  ❌ HELLNET_CACHE_VALKEY_CONNECTION
  ❌ HELLNET_CACHE_VALKEY_PASSWORD

Set them before startup or pass an explicit HellnetCacheOptions:

  # Minimal example:
  export HELLNET_CACHE_VALKEY_CONNECTION=valkey.hellnet.com.br:6379
  export HELLNET_CACHE_VALKEY_PASSWORD=your-password

  # Or in code:
  services.AddHellnetCache(new HellnetCacheOptions {
      ValkeyConnection = "valkey.hellnet.com.br:6379",
      ValkeyPassword = "your-password",
  });

Usage

public class OrderService(ICache cache)
{
    // ── Set with per-key TTL ────────────────────────────
    public async Task SetOrderAsync(Order order)
        => await cache.SetAsync(
            $"order:{order.Id}",
            order,
            TimeSpan.FromHours(1));  // ← TTL por chave

    public async Task SetSessionAsync(string id, Session s)
        => await cache.SetAsync(
            $"session:{id}",
            s,
            TimeSpan.FromMinutes(5)); // ← TTL curto

    // ── Get ─────────────────────────────────────────────
    public async Task<Order?> GetOrderAsync(string id)
        => await cache.GetAsync<Order>($"order:{id}");

    // ── GetOrSet (stampede-protected) ───────────────────
    public async Task<Config> GetConfigAsync()
        => await cache.GetOrSetAsync(
            "config:global",
            async () => await _db.Configs.FirstAsync(),
            TimeSpan.FromHours(24));  // ← TTL longo

    // ── Remove ──────────────────────────────────────────
    public async Task InvalidateOrderAsync(string id)
        => await cache.RemoveAsync($"order:{id}");

    // ── Exists ──────────────────────────────────────────
    public async Task<bool> HasOrderAsync(string id)
        => await cache.ExistsAsync($"order:{id}");
}

TTL per key

Cada SetAsync/GetOrSetAsync aceita TimeSpan? ttl. Quando omitido, usa o fallback do options.

// TTL explícito — cada chave com lifetime próprio
await cache.SetAsync("a", v, TimeSpan.FromMinutes(5));   // 5 min
await cache.SetAsync("b", v, TimeSpan.FromHours(24));    // 24h
await cache.SetAsync("c", v);                             // fallback: DefaultTtl (30min)

// L2 (Valkey) respeita o TTL exato passado
// L1 (Memory) usa absolute expiration por padrão

Architecture

ICache.GetAsync("key")
  ├─ L1 (Memory) ── hit? → retorna
  ├─ L2 (Valkey) ── hit? → popula L1, retorna
  └─ L3 (External) ─ hit? → popula L2+L1, retorna
                  └─ miss → null

ICache.SetAsync("key", value, ttl)
  ├─ L1.SetAsync (absolute TTL) ── paralelo
  ├─ L2.SetAsync (Valkey TTL)    ── paralelo
  └─ L3.SetAsync (se habilitado) ── paralelo

Concurrency

Options

Env-first — obrigatórias

DI method vs validation

Via env vars (HELLNET_CACHE_*)

Via code

new HellnetCacheOptions
{
    ValkeyConnection = "valkey.hellnet.com.br:6379",
    ValkeyPassword = "hellnet2026",
    ValkeyKeyPrefix = "myapp:cache:",
    L1DefaultTtl = TimeSpan.FromMinutes(2),
    DefaultTtl = TimeSpan.FromMinutes(15),
    TouchOnRead = true,
    TouchTtl = TimeSpan.FromMinutes(5),
    L1SlidingExpiration = true,
};

Dependencies

• .NET 10+
• StackExchange.Redis — L2 Valkey provider
• Microsoft.Extensions.Caching.Memory — L1 memory provider
• Microsoft.Extensions.DependencyInjection.Abstractions
• Microsoft.Extensions.Logging.Abstractions

Testing

# Unit tests (72)
dotnet test app/Hellnet.Cache.slnx

# Integration tests against real Valkey (14)
dotnet test app/tests/Hellnet.Cache.IntegrationTests/