Hellnet.Cache 1.1.15

Hellnet.Cache

Biblioteca de cache multi-camada para .NET com L1 (memória in-process), L2 (Valkey/Redis) e L3 opcional (cache externo).

Write-through, read-through, proteção contra cache stampede, configuração env-first, resiliência com Polly.

Instalação

dotnet add package Hellnet.Cache

Quick start

Env-first (recomendado para microserviços)

builder.Services.AddHellnetCache();

Exige as env vars HELLNET_CACHE_VALKEY_CONNECTION e HELLNET_CACHE_VALKEY_PASSWORD. Lança InvalidOperationException no startup se faltar.

Explicito

builder.Services.AddHellnetCache(new HellnetCacheOptions
{
    ValkeyConnection = "valkey.hellnet.com.br:6379",
    ValkeyPassword = "hellnet2026",
});

Configuração mínima

export HELLNET_CACHE_VALKEY_CONNECTION=valkey.hellnet.com.br:6379
export HELLNET_CACHE_VALKEY_PASSWORD=hellnet2026

Uso

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

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

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

    // GetOrSet — protegido contra stampede
    public async Task<Config> GetConfigAsync()
        => await cache.GetOrSetAsync("config:global",
            () => _db.Configs.FirstAsync(),
            TimeSpan.FromHours(24));

    // 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}");
}

Camadas

Read-through

Get("key") → L1 → L2 → L3 → miss/null

Quando um hit ocorre em L2 ou L3, as camadas inferiores são populadas automaticamente (warming assíncrono e deduplicado).

Write-through

Set("key") → L1.Set + L2.Set + L3.Set em paralelo (Task.WhenAll)

TTL por chave

Cada SetAsync/GetOrSetAsync aceita TimeSpan? ttl. Quando omitido, usa fallback por camada:

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)

L1 usa expiração absoluta por padrão (L1SlidingExpiration=false). Sliding disponível como opt-in.

Concorrência

Resiliência (Polly)

Valkey timeout → Retry 200ms → Retry 400ms → CB abre (30s) → fail fast → CB half-open → ok? fecha

Options

Env vars (HELLNET_CACHE_*)

DI methods

Dependências

• .NET 10+
• StackExchange.Redis — L2 Valkey provider
• Polly.Core — Resilience pipeline (retry + circuit breaker)
• Microsoft.Extensions.Caching.Memory — L1 memory provider
• Microsoft.Extensions.DependencyInjection.Abstractions
• Microsoft.Extensions.Logging.Abstractions

Licença

Apache 2.0 © 2026 Hellnet