Eryri.FileDistributedCache 1.0.1

Eryri.Extensions.Caching.FileSystem

A filesystem-backed cache for .NET applications using IDistributedCache / IBufferedDistributedCache.

Designed for low-latency, high-throughput access within a single process, with thread-safe operations and Native AOT compatibility.

Features

• Stores cache payloads on the filesystem.
• Eviction policies include:
  • Least Recently Used (LRU)
  • Least Frequently Used (LFU)
  • Soonest Time To Live (TTL)
  • First In First Out (FIFO).
• Supports DistributedCacheEntryOptions options for each entry: AbsoluteExpiration, AbsoluteExpirationRelativeToNow, SlidingExpiration.
• Supports synchronous and asynchronous cache operations.
• Auto eviction of expired items.
• Auto eviction when new items would cause the cache to exceed its size limit.

Installation

dotnet add package Eryri.FileDistributedCache

Quick start

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

// Arrange
using var services = new ServiceCollection()
    .AddDistributedFileCache()
    .BuildServiceProvider();

var cache = services.GetRequiredService<IDistributedCache>();
var key = Guid.NewGuid().ToString("N");
var payload = Guid.NewGuid().ToString("N");

// Act
await cache.SetStringAsync(key, payload);
var actual = await cache.GetStringAsync(key);

// Assert
if (actual != payload)
{
    throw new Exception("FileDistributedCache write value is not the same as the read value");
}
else
{
    Console.WriteLine("FileDistributedCache can write and read");
}

With HybridCache

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

// Arrange
using var services = new ServiceCollection()
    .AddDistributedFileCache()
    .AddHybridCache().Services
    .BuildServiceProvider();

var cache = services.GetRequiredService<HybridCache>();
var key = Guid.NewGuid().ToString("N");
var payload = Guid.NewGuid().ToString("N");
var options = new HybridCacheEntryOptions
{
    Flags = HybridCacheEntryFlags.DisableLocalCache
};

// Act
await cache.SetAsync(key, payload, options);
var actual = await cache.GetOrCreateAsync(key, _ => ValueTask.FromResult(string.Empty), options);

// Assert
if (actual != payload)
{
    throw new Exception("FileDistributedCache write value is not the same as the read value");
}
else
{
    Console.WriteLine("FileDistributedCache can write and read");
}

Configuration

Expiration and eviction

• Expiration: A background timer removes expired entries. It is scheduled for the next entry due to expire.
• Size limits: When an added entry would exceed the configured limit, the cache removes entries according to the eviction policy to make room.
• Manual compaction: When no size limit is configured, call IFileDistributedCache.Compact(double percentage) to remove at least the specified fraction of entries. For example, 0.10 removes at least 10%, selected according to the eviction policy.
• Write failures: If the filesystem rejects a write, the entry is not added to the cache.
• Storage location: Cache files are stored in a temporary directory under the current user’s temp folder and removed during normal application shutdown.

Operational notes

• Durability: Treat cached entries as disposable. The application must be able to recreate data after a restart or cache miss.
• Permissions: The application identity needs permission to create, read, write, and delete files in its temporary directory.
• Cleanup: Cache files are removed during normal shutdown. An abrupt exit may leave files behind; [document how these are found or cleaned up].
• Filesystem failures: Failed file creation, returns without caching, and logs an error with the underlying filesystem error.]