Eryri.FileDistributedCache 1.0.10

Eryri.FileDistributedCache

A bounded, local disk-backed cache. No Redis. No cache server.

Eryri.FileDistributedCache implements the standard .NET IDistributedCache and IBufferDistributedCache APIs while storing cache values on the local filesystem. It gives one application process more cache capacity than memory alone, with configurable size limits, expiration, eviction policies, and optional recovery across restarts.

Use it as:

• a standalone local cache when your application needs fast, bounded filesystem storage without operating another service; or
• a HybridCache secondary tier behind the in-memory local tier.

dotnet add package Eryri.FileDistributedCache

Important: This is local, single-process storage. With a configured persistent directory, it can provide durable local storage across normal process restarts. It is not a shared Redis replacement, a cross-replica store, or a backup system.

Why use Eryri?

Compared with an in-memory cache, Eryri trades some latency for substantially more capacity and optional restart recovery. Compared with SQLite or another embedded database cache, it provides standard .NET cache abstractions and cache-specific eviction semantics without requiring application code to manage a database schema. Compared with Redis, it needs no service and has no network hop, but it is local to one process and cannot coordinate replicas.

Choose it when

• A single process needs a cache larger than the memory budget you want to reserve for it.
• Values are expensive to retrieve or compute but remain recoverable from another source.
• You need a maximum cache size and an eviction policy rather than an unbounded directory.
• You want a local HybridCache secondary tier without deploying Redis or another service.
• You run offline, on a developer workstation, in a test environment, or in a deployment where a local persistent volume is available.

Choose something else when

• Multiple processes, containers, or application replicas must read and write the same entries. Use a shared backend such as Redis or a managed distributed cache.
• You need replication, transactions, backups, or a system of record across hosts. Use a database or shared durable storage system.
• You need automatic migration of an existing in-memory cache to disk under memory pressure. Configure HybridCache explicitly instead.
• You need semantic search, vector indexing, serialization, or model management. Eryri stores opaque cache values; pair it with the system that provides those capabilities.

Quick start

Register Eryri with dependency injection and use the familiar distributed-cache API:

using Eryri.Extensions.Caching.FileSystem;
using Microsoft.Extensions.Caching.Distributed;
using Microsoft.Extensions.DependencyInjection;

using var services = new ServiceCollection()
	.AddDistributedFileCache(options =>
	{
		options.SizeLimitGiB = 1;
		options.EvictionPolicy = EvictionPolicy.LRU;
	})
	.BuildServiceProvider();

var cache = services.GetRequiredService<IDistributedCache>();

await cache.SetStringAsync(
	"product:42",
	"Cached product data",
	new DistributedCacheEntryOptions
	{
		AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(10)
	});

var value = await cache.GetStringAsync("product:42");
Console.WriteLine(value ?? "Cache miss");

That is all that is required for an ephemeral local cache. No database, cache server, or separate process is needed.

Use with HybridCache

Use Eryri as the filesystem-backed secondary tier while HybridCache manages the in-memory local tier:

using Eryri.Extensions.Caching.FileSystem;
using Microsoft.Extensions.Caching.Hybrid;
using Microsoft.Extensions.DependencyInjection;

using var services = new ServiceCollection()
	.AddDistributedFileCache(options =>
	{
		options.SizeLimitGiB = 2;
		options.EvictionPolicy = EvictionPolicy.LRU;
	})
	.AddHybridCache()
	.BuildServiceProvider();

var cache = services.GetRequiredService<HybridCache>();

var value = await cache.GetOrCreateAsync(
	"product:42",
	_ => ValueTask.FromResult("Cached product data"),
	new HybridCacheEntryOptions
	{
		Expiration = TimeSpan.FromMinutes(10),
		LocalCacheExpiration = TimeSpan.FromSeconds(5)
	});

The in-memory entry expires after five seconds, while the overall entry expires after ten minutes. HybridCache does not automatically spill arbitrary in-memory entries to disk; both tiers are configured local caches.

AI and local data workloads

Eryri is useful for AI applications that repeatedly retrieve or compute data locally and can safely rebuild it after a cache miss:

• LLM response caching: cache deterministic prompt results using a key that includes the model, relevant settings, prompt version, and input hash.
• Embedding and retrieval caching: cache serialized embeddings, chunk lookups, and retrieved context when the underlying documents or embedding model version are part of the key.
• Local model metadata and artifacts: cache downloaded metadata or derived files when the deployment has a suitable persistent volume and the source can be checked again.
• Agent and tool-call acceleration: cache idempotent, repeatable tool results with an expiration appropriate to the data freshness requirement.
• Offline and development workflows: reduce repeated network calls and model or document preparation during local development, evaluation, and constrained deployments.

services.AddDistributedFileCache(options =>
{
	options.CacheDirectory = "/var/cache/my-agent";
	options.SizeLimitGiB = 10;
	options.EvictionPolicy = EvictionPolicy.LFU;
	options.DefaultAbsoluteExpirationRelativeToNow = TimeSpan.FromHours(24);
});

Recommended cache-key inputs for AI workloads include the model/provider identifier, model version, prompt or pipeline version, relevant generation settings, document/index version, and a stable input hash. Do not use the cache as the source of truth for safety decisions, permissions, financial data, or other data that must be authoritative. Eryri does not provide vector search, embedding generation, prompt templating, or cross-process coordination.

Capacity and eviction

Set a maximum cache size in bytes, mebibytes, or gibibytes:

services.AddDistributedFileCache(options =>
{
	options.SizeLimitBytes = 1024L * 1024 * 1024; // 1 GiB
	options.EvictionPolicy = EvictionPolicy.LRU;
});

The size limit applies to storage managed by this cache. It does not reserve disk space or account for unrelated files, filesystem metadata, WAL files, or other workloads. Leave appropriate free-space headroom and monitor the volume used by the application.

Capacity eviction is separate from expiration. An entry can expire regardless of the selected capacity policy. Expired entries are cleaned up automatically, and a write can evict existing entries to make room for a new value.

An individual value larger than the configured size limit cannot be made to fit by eviction; size limits are intended to bound normal cache occupancy and should be paired with application-level payload limits when strict admission control is required.

To request proactive compaction through the package-specific API:

var fileCache = services.GetRequiredService<IFileDistributedCache>();
fileCache.Compact(0.10m); // request removal of at least 10% of entries

Expiration

Use the standard DistributedCacheEntryOptions API:

await cache.SetStringAsync(
	"product:42",
	"Cached product data",
	new DistributedCacheEntryOptions
	{
		AbsoluteExpirationRelativeToNow = TimeSpan.FromHours(1),
		SlidingExpiration = TimeSpan.FromMinutes(10)
	});

The entry expires after one hour at the latest, or after ten minutes without access, whichever occurs first. You can configure defaults for entries that do not specify an expiration. Treat cache misses as normal: retrieve or recompute the value from its source of truth and cache it again.

Entry-level expiration settings take precedence over the corresponding FileCacheOptions defaults. If no entry-level or configured default expiration is present, the value has no time-based expiration and remains subject to capacity eviction.

Persistence and operational reliability

By default, the cache uses a temporary directory that is removed during normal shutdown. Configure CacheDirectory to use Eryri as durable local storage whose values can be recovered after normal process restarts:

services.AddDistributedFileCache(options =>
{
	options.CacheDirectory = "/var/cache/myapp";
	options.SizeLimitGiB = 1;
	options.EvictionPolicy = EvictionPolicy.LRU;
});

For containers, mount a suitable persistent volume at the configured path. The application identity needs read, write, create, rename, and delete permissions. Snapshots and write-ahead-log checkpointing are managed internally; SnapshotInterval controls the snapshot interval when persistence is enabled.

This persistence mode is durable local storage, but it is not replicated or backed up automatically. A process crash or forced termination can leave the latest write subject to the filesystem and WAL durability guarantees. Disk failure, volume deletion, permission changes, corruption, expiration, or configured capacity eviction can still remove or make values unavailable. Use a database or backup system when you need transactions, replication, independent recovery, or guaranteed retention.

Eryri therefore supports two valid roles: a bounded cache for recoverable values, and a durable local store for values whose durability requirements fit a single persistent volume and the configured expiration and eviction policy.

Read failures and missing files are treated as cache misses rather than allowing an unavailable cached value to become application data. Write and cleanup failures are logged, but filesystem capacity and permissions remain deployment responsibilities. Monitor the persistent volume, reserve free space, and include the cache directory in your backup and recovery plan when the stored values are durable application data.

Configuration

Performance

Filesystem performance depends on the operating system, filesystem, storage medium, payload size, concurrency, cache state, and durability configuration. The repository contains repeatable BenchmarkDotNet coverage in BenchmarkTests.cs.

The benchmark suite compares several IDistributedCache implementations and exercises both unconstrained and capacity-constrained Eryri configurations. Run the benchmarks on your target hardware and workload before making capacity or latency commitments. Published numbers are directional evidence, not a performance guarantee.

The benchmark workload currently uses 4 KiB payloads, 10,000 initial entries, 100 parallel operations, five iterations, and one warmup iteration.

Published results

The following results are the supplied BenchmarkDotNet output for the workload described above. Use these figures as directional evidence and rerun the benchmarks on the target environment before making capacity or latency commitments.

Times are in microseconds (us). Allocated memory is per operation. 1 ms = 1,000 us and 1 us = 1,000 ns.

Eryri.FileDistributedCache - unbounded

Eryri.FileDistributedCache - capacity constrained

This run measures Eryri with capacity enforcement and eviction enabled. It is not directly equivalent to the unbounded run because the cache performs additional capacity work.

DamianH.FileDistributedCache

This is a comparison run from the same benchmark harness. It is included for context, not as a universal ranking across all workloads.

The comparison implementations do not necessarily provide the same feature set. In particular, their capacity behavior and eviction semantics differ; compare the capabilities you need, not only the mean latency.

NeoSmart.Caching.Sqlite

NeoSmart.Caching.Sqlite did not implement IBufferDistributedCache in this benchmark and did not provide a configurable disk-usage or maximum-cache-size limit in the reviewed configuration. These are capability differences, not just performance differences.

API and compatibility

• IDistributedCache support for existing .NET cache integrations.
• IBufferDistributedCache support for lower-allocation buffer-based access.
• Dependency injection registration through AddDistributedFileCache.
• HybridCache secondary-tier integration through the standard IDistributedCache registration.
• Native AOT and trimming compatibility are enabled in the package project.
• MIT licensed.

Frequently asked questions

Is this a local Redis alternative?

It is an alternative when one process needs a bounded local cache without a Redis server. It is not a protocol-compatible Redis server and does not provide shared state between replicas.

Is it really distributed because it implements IDistributedCache?

No. IDistributedCache is the .NET abstraction used for integration. Eryri stores data in the local process and local filesystem only.

Does persistence guarantee that every cached value survives?

No. Persistence supports recovery across normal restarts, but cache misses and data loss remain valid outcomes. Keep a source of truth.

Does it automatically move memory-cache entries to disk?

No. Configure Eryri as the IDistributedCache secondary tier for HybridCache; it does not automatically spill arbitrary existing memory-cache entries to disk.

Is it suitable for multiple application replicas?

Only as an independent cache per replica. Use a shared cache backend when replicas must observe the same entries.