Caching

Elarion can cache handler results declaratively. Mark a read handler with [Cacheable] and the generator wraps it in a cache decorator; mark a write handler with [CacheInvalidate] and it clears the matching entries. Caching is opt-in per handler and integrates with the same decorator pipeline as everything else.

Caching a read handlerCopy Anchor Link

using Elarion.Abstractions;
using Elarion.Abstractions.Caching;
using Microsoft.EntityFrameworkCore;

[Cacheable("clients", DurationSeconds = 120)]
[Handler("clients.get")]
public sealed class GetClient(AppDbContext db)
    : IHandler<GetClient.Query, Result<GetClient.Response>> {
    public sealed record Query(Guid Id);
    public sealed record Response(Guid Id, string Name);

    public async ValueTask<Result<Response>> HandleAsync(Query query, CancellationToken ct) {
        var client = await db.Clients
            .Where(c => c.Id == query.Id)
            .Select(c => new Response(c.Id, c.Name))
            .FirstOrDefaultAsync(ct);

        return client is null
            ? AppError.NotFound($"Client {query.Id} was not found.")
            : client;
    }
}

The generator emits an IHandlerCachePolicy<GetClient.Query> from the attribute metadata and inserts a CacheDecorator<,> into the handler's pipeline. The decorator computes a key from the request, looks it up, and only runs the handler on a miss.

[Cacheable] propertiesCopy Anchor Link

Use KeyProperties when only some request fields affect the response:

[Cacheable("reports", DurationSeconds = 300, KeyProperties = new[] { "Year", "Month" })]

Every property that participates in the key must have a stable, injective string formatting: a primitive, string, char, bool, Guid, an enum, DateTime/DateTimeOffset/DateOnly/TimeOnly/ TimeSpan, decimal, or a Nullable of those. A property of any other type (a collection, array, or custom object) would fall back to object.ToString() — colliding every value into one key and risking a cross-request cache leak — so the generator rejects it at build time (ELCACHE006). Narrow the key with KeyProperties to exclude such a property.

Cache scopeCopy Anchor Link

HandlerCacheScope controls isolation:

Both scopes sit inside the tenant when tenant scoping is registered: Global then means every user of the tenant in scope.

Invalidating with tagsCopy Anchor Link

A command handler clears cached entries by tag with [CacheInvalidate]. Invalidation is tag-based, so the writer does not need to know the concrete keys produced by read handlers:

[CacheInvalidate("clients")]
[Handler("clients.update")]
public sealed class UpdateClient(AppDbContext db)
    : IHandler<UpdateClient.Command, Result<UpdateClient.Response>> {
    public sealed record Command(Guid Id, string Name);
    public sealed record Response(Guid Id);

    public async ValueTask<Result<Response>> HandleAsync(Command command, CancellationToken ct) {
        var client = await db.Clients.FirstOrDefaultAsync(c => c.Id == command.Id, ct);
        if (client is null) {
            return AppError.NotFound($"Client {command.Id} was not found.");
        }

        client.Name = command.Name;
        await db.SaveChangesAsync(ct);
        // The decorator invalidates the "clients" tag on success.
        return new Response(client.Id);
    }
}

[CacheInvalidate] takes the same tags and Scope as [Cacheable]. The scopes compose precisely:

• A Global invalidation (the default) evicts the globally shared entries and every user's CurrentUser-scoped entries for the listed tags. User-scoped entries are deliberately also stamped with the global tag namespace so the default [Cacheable] (CurrentUser) / default [CacheInvalidate] (Global) pairing works out of the box.
• A CurrentUser invalidation clears only the invoking user's entries for the listed tags — never another user's, and never the globally shared entries.

Tenant isolationCopy Anchor Link

A cache hit never runs the handler, so it never runs the tenant read filter either. Once tenant scoping is registered (AddElarionTenantScoping()), the default cache therefore puts the tenant in scope into every key and tag, whatever the Scope. A [Cacheable(Scope = HandlerCacheScope.Global)] query over tenant-scoped rows caches one entry per tenant, and a user who belongs to several tenants gets one CurrentUser entry per tenant. Nothing changes on the handler or its attributes.

A tenant's id is hashed before it enters a key or tag, like a user id. A host without tenant scoping keeps exactly the keys and tags it had before.

No tenant means no cache. This fails closed, the same way the read filter matches no rows when the tenant is unresolved. A shared namespace for every caller without a tenant would be keyed on a missing value: a handler that enters a tenant itself, with ITenantContext.Scope in its body, would store that tenant's result there and serve it to the next caller without a tenant. Bypassing gives up caching for those callers instead, typically anonymous visitors when the tenant comes from a claim. To cache their reads, resolve a tenant for them before the pipeline runs (from the host name, say).

Invalidation stays inside the tenant. A tenant's writes are guarded to its own rows, so its [CacheInvalidate] leaves other tenants' entries alone, and one busy tenant cannot keep flushing everyone else's cache. A system scope and a scope with no tenant are not confined to one tenant's rows, so their invalidations reach every tenant.

Registering the cache runtimeCopy Anchor Link

The attributes and generated policies are runtime-neutral. The host chooses the implementation. The default is backed by HybridCache:

// dotnet add package Elarion.Caching
builder.Services.AddElarionHandlerCaching();

Elarion.Caching is an opt-in sibling package — referencing it is what pulls Microsoft.Extensions.Caching.Hybrid, so the core stays dependency-light (ADR-0017). This registers HybridCache and the default IHandlerCache (HybridHandlerCache). There are three ways to change the backing store, from least to most invasive:

• Add an L2 distributed cache so entries survive restarts and are shared across instances — see Adding an L2 distributed cache below. The recommended default for most applications is a PostgreSQL UNLOGGED table; Redis, SQL Server, and others work too.
• Swap the HybridCache implementation itself. HybridCache is the abstraction, and HybridHandlerCache simply resolves whatever HybridCache is in the container. Register your own HybridCache before AddElarionHandlerCaching() — its AddHybridCache() call uses TryAddSingleton, so it adds the default only when one is not already registered, and your implementation wins.
• Replace IHandlerCache entirely when you want to bypass HybridCache and own the whole caching contract. A replacement then owns tenant isolation as well: the generated policies' keys contain only request values.

Adding an L2 distributed cacheCopy Anchor Link

HybridCache is two-tier. The L1 is an in-process MemoryCache that absorbs the hot path and is lost on restart; the L2 is an optional IDistributedCache that HybridCache auto-discovers from DI and uses for cross-instance coherence, warm-restart survival, and stampede coordination. With no L2 registered, caching is L1-only — fine for a single instance, but each instance keeps its own copy and a restart starts cold.

For most applications the recommended L2 is a PostgreSQL UNLOGGED table — reuse the database you already run instead of standing up a separate Redis tier. Elarion.Caching.PostgreSql wires it in one call:

// dotnet add package Elarion.Caching.PostgreSql
using Elarion.Caching.PostgreSql;

builder.Services.AddElarionPostgreSqlHandlerCaching(
    builder.Configuration.GetConnectionString("CacheDb")!);

That registers the official Microsoft.Extensions.Caching.Postgres distributed cache as the L2 — an auto-created UNLOGGED table named elarion_cache in the public schema — and calls AddElarionHandlerCaching() for you, so HybridCache picks the table up automatically. The optional configure delegate overrides any default (it runs last, so it always wins):

builder.Services.AddElarionPostgreSqlHandlerCaching(
    builder.Configuration.GetConnectionString("CacheDb")!,
    options => {
        options.SchemaName = "cache";
        options.TableName = "handler_cache";
    });

Why this fits most apps: HybridCache's in-process L1 carries the high-frequency reads, so the L2 mostly handles cross-instance coherence and warm restarts — a load Postgres serves comfortably. Reach for a dedicated tier such as Redis when the cache itself must be a very high-throughput, independently scaled, or multi-region store, where routing all cache traffic through your primary Postgres (and the "not on replicas" limitation of UNLOGGED) would make the database the bottleneck. Any IDistributedCache works as the L2: register Redis (AddStackExchangeRedisCache), SQL Server, or another provider before AddElarionHandlerCaching() and HybridCache uses it just the same.

How it composesCopy Anchor Link

CacheDecorator<TRequest, TResponse> and CacheInvalidationDecorator<TRequest, TResponse> are ordinary handler decorators inserted by the [Cacheable] / [CacheInvalidate] attributes. They sit in the generated pipeline alongside your application decorators, so caching composes deterministically with logging, validation, and transactions. Cache operations are also trace-visible: get/create spans report the precise outcome — miss-factory-executed, miss-non-cacheable, cached-or-coalesced, or bypass-no-tenant — and invalidation emits its own spans, all without leaking full keys, raw user ids, or tenant ids into tags.