DamianH.Http.HybridCacheHandler 0.2.0

DamianH.Http.HybridCacheHandler

RFC 9111 client-side HTTP caching for HttpClient, backed by .NET HybridCache for L1 memory and optional L2 distributed storage.

Full documentation is the authoritative guide for configuration, behavior, metrics, and limitations.

Naming migration

The package IDs, assembly names, and namespaces now use DamianH.Http.HybridCacheHandler, including all ContentStore packages. Update package references and using directives together. The HttpHybridCacheHandler type and AddHttpHybridCacheHandler methods are unchanged. The metrics meter name and keyed DI registration key also use the new name; update meter subscriptions and any literal registration keys.

Frameworks

The handler and all five content-store packages ship net10.0, netstandard2.0, and net472 assets. Samples and the separate FileDistributedCache product remain .NET 10. .NET Standard is a library target, not a runtime. Older-target headers can be normalized by public enumeration. Framework apps should enable automatic binding redirects and use HttpClientHandler with GZip/Deflate decompression instead of the modern handler example below.

Upstream support warning: HybridCache 10.8.0 warns that net472 is unsupported/untested upstream. That warning is not suppressed; this repository's coverage does not change Microsoft's support policy. Framework tests run on the installed Windows runtime, commonly 4.8, not necessarily an actual 4.7.2 runtime. See framework compatibility.

Install and start (.NET 10)

From your application project directory:

dotnet add package DamianH.Http.HybridCacheHandler

services.AddHttpHybridCacheHandler();
services.AddHttpClient("CachedClient")
    .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
    {
        AutomaticDecompression = DecompressionMethods.All,
        PooledConnectionLifetime = TimeSpan.FromMinutes(5),
        PooledConnectionIdleTimeout = TimeSpan.FromMinutes(2)
    })
    .AddHttpMessageHandler(sp => sp.GetRequiredService<HttpHybridCacheHandler>());

Important defaults and safety

• Default mode is CacheMode.Private, not shared proxy caching. Choose shared mode and authentication partitioning deliberately; response Vary is enforced.
• The default content limit is 10 MB. FallbackCacheDuration defaults to TimeSpan.MinValue: responses without caching headers are not cached by default.
• Use automatic decompression. See the pipeline guide for resilience and authentication ordering.
• Optional external body stores require explicit setup and operator-owned retention. Streaming requires ResponseHeadersRead and response consumption/ disposal; early disposal or cancellation does not fill the cache. Concurrent streaming misses do not share a live origin stream. Do not eagerly delete shared bodies when invalidating one URI.
• Provision a trusted private staging parent, even when using the system temp default. On Windows the handler inherits, but does not restrict or validate, its ACLs; unique spool directories and leases are not access control.

Guides

• Options and cache modes
• Behavior and diagnostics
• Content stores, ownership, staging, and migration
• Metrics
• Performance and memory
• Benchmarks
• RFC 9111 conformance
• HttpClientFactory sample
• YARP caching proxy sample