Introduction #

A near cache for .NET whose entries are invalidated by the Redis server itself.

RedisNearCache keeps an in-process copy (an L1) of the Redis values your application reads, and lets the Redis server tell you when one of them changes, using the CLIENT TRACKING feature Redis 6 introduced.

The one-sentence mechanism: your app keeps an in-process copy of the Redis values it reads, Redis remembers which keys each tracked connection has read, and when any client writes one of those keys, Redis pushes a message naming it and the local copy is thrown away. Nothing in the write path has to cooperate: a Java service, a Go job, or someone at redis-cli all invalidate you the same way.

Why server-assisted beats a backplane

FusionCache and the proposed HybridCache backplane solve staleness with an application-level pub/sub channel that the writer publishes to. That only works when every writer uses the same library and remembers to publish. A writer in another language or process silently leaves readers stale. Server-assisted tracking moves the responsibility to the one place every write already passes through: Redis itself. Any client, in any language, doing a plain SET or DEL (or redis-cli by hand) causes Redis to push an invalidation, with no cooperation required from writers.

Requirements

Quickstart #

Install the package, register the cache, and watch an outside write invalidate it.

1. Install

Add the package to your project.

2. Register and resolve

Register IRedisNearCache against a connection string and resolve it from DI. Await Ready once at startup so the invalidation subscription and the initial tracking arm have completed before you rely on the cache being coherent.

3. Write, then read

SetAsync writes through to Redis and evicts any local copy. The first GetAsync<T> after that is always a miss: it fetches from Redis, stores the value in L1, and arms server-side tracking for that key. Every read after that is served from L1 with no network call, until the key is invalidated.

4. See an invalidation from redis-cli

Read a key so it is cached, then change it from a completely different client, one that knows nothing about RedisNearCache. The very next read reflects the new value, because Redis itself pushed the invalidation.

Back in your application, the next GetAsync<T>("user:42") is a miss (it goes to Redis to re-populate L1 and re-arm tracking) and returns Grace. Every read after that is a hit again, until the next external write.

5. Check the stats

Statistics exposes six cumulative, thread-safe counters. See Operations for what to watch in production.

How it works #

The private connection, one-shot tracking, NOLOOP writes, and the in-flight guard.

Why not an app-level backplane

FusionCache and the proposed HybridCache backplane solve staleness with pub/sub that the writer publishes to. That only works when every writer uses the same library. Server-assisted tracking moves the responsibility to the one place every write already passes through.

The parts

RedisNearCache opens one private StackExchange.Redis multiplexer, cloned from your connection settings with Protocol=Resp2, AllowAdmin=true and a unique client name. Under RESP2 that multiplexer has two connections per Redis node: an interactive connection, used for the actual GET/SET calls, and a subscriber connection, which RedisNearCache tells Redis to redirect invalidations to (CLIENT TRACKING ON REDIRECT <subscriber id>). The subscriber subscribes to __redis__:invalidate and turns each incoming message into an eviction from L1.

One-shot tracking

Tracking is one-shot per key: after Redis sends an invalidation for a key, it forgets that key was being tracked until the connection reads it again. Every GetAsync<T> miss re-arms tracking for that key by reading it over the tracked interactive connection.

sequenceDiagram
    autonumber
    participant App as Your code
    participant NC as RedisNearCache
    participant L1
    participant I as interactive conn
    participant S as subscriber conn
    participant R as Redis
    participant W as Any writer
    App->>NC: GetAsync("user:42")
    NC->>L1: TryGet
    L1-->>NC: miss
    NC->>NC: inflight.Begin(user:42)
    NC->>I: GET user:42
    I->>R: GET user:42
    Note over R: remembers user:42 was read by this connection
    R-->>I: value v1
    I-->>NC: value v1
    NC->>NC: invalidated while in flight? no
    NC->>L1: Set(user:42, v1)
    NC-->>App: v1
    App->>NC: GetAsync("user:42")
    NC->>L1: TryGet
    L1-->>NC: hit
    NC-->>App: v1 (no network)
    W->>R: SET user:42 v2
    R->>S: message __redis__:invalidate [user:42]
    Note over R: forgets user:42 for this connection (one-shot)
    S->>NC: KeyInvalidated(user:42)
    NC->>L1: Remove(user:42)
    App->>NC: GetAsync("user:42")
    NC->>L1: TryGet
    L1-->>NC: miss
    NC->>I: GET user:42
    I->>R: GET user:42
    Note over R: tracks user:42 again
    R-->>NC: value v2
    NC->>L1: Set(user:42, v2)
    NC-->>App: v2

NOLOOP

Writes made through RedisNearCache’s own SetAsync/RemoveAsync are armed with NOLOOP, so Redis does not echo them back as invalidations; RedisNearCache evicts its own L1 entry for the key directly around the write instead.

The in-flight guard

Because an invalidation can arrive between sending a GET and storing its reply, RedisNearCache keeps an in-flight guard: each read records a version token before the request goes out, and the reply is only stored in L1 if no invalidation for that key was seen in the meantime. A stale reply is still returned to the caller (it was correct when read); it is simply not cached, and Statistics.RaceDiscards counts it.

sequenceDiagram
    participant NC as RedisNearCache
    participant L1
    participant R as Redis
    participant W as Any writer
    NC->>NC: token = inflight.Begin(k)  (version 7)
    NC->>R: GET k
    R-->>NC: v1 (in transit)
    W->>R: SET k v2
    R->>NC: invalidate [k]
    NC->>NC: inflight.MarkInvalidated(k)  (version 8)
    NC->>L1: Remove(k)  (nothing there yet)
    Note over NC: reply v1 arrives
    NC->>NC: WasInvalidated(k, token)? version 8 ≠ 7 → yes
    NC->>NC: discard v1, Statistics.RaceDiscards++
    Note over NC: return v1 to the caller (it was true when read); next read fetches v2

Reconnects, the part that actually needs care

Tracking is per-connection state on the server. The spike showed two silent failure modes, both handled by re-arming and flushing.

sequenceDiagram
    participant A as TrackingArmer
    participant L1
    participant I as interactive conn (id 26)
    participant S as subscriber conn (id 27 → 58)
    participant R as Redis
    Note over R: redirect target for id 26 is 27
    R-xS: connection killed
    S->>R: reconnect, CLIENT ID = 58
    Note over R: id 26 still redirects to dead 27
    S-->>A: ConnectionRestored(Subscription)
    A->>L1: Clear()  (anything missed is gone)
    A->>R: CLIENT LIST (via interactive)
    R-->>A: our subscriber = 58
    A->>R: CLIENT TRACKING OFF
    A->>R: CLIENT TRACKING ON REDIRECT 58
    R-->>A: OK
    A-->>L1: Armed(SubscriptionRestored)

Per-endpoint state

stateDiagram-v2
    [*] --> Unarmed
    Unarmed --> Arming: StartAsync / find subscriber id
    Arming --> Armed: TRACKING ON REDIRECT ok
    Arming --> Arming: subscriber not visible yet, backoff retry
    Armed --> Lost: ConnectionFailed (either type)
    Lost --> Arming: ConnectionRestored
    Armed --> Arming: ConnectionRestored (server dropped or re-pointed)
    note right of Armed: L1 trusted
    note right of Lost: L1 flushed, reads pass through

Cluster

Client ids and tracking tables live on each node, and a node sends invalidations only for keys it owns. The private multiplexer already keeps an interactive and a subscriber connection per master, so the armer repeats the same dance per node with that node’s subscriber id.

flowchart LR
    subgraph P[private multiplexer]
      direction TB
      A1[interactive → 7100]
      S1[subscriber id 11]
      A2[interactive → 7101]
      S2[subscriber id 7]
      A3[interactive → 7102]
      S3[subscriber id 7]
    end
    subgraph C[cluster]
      N1[(master 7100
slots 0-5460)]
      N2[(master 7101
slots 5461-10922)]
      N3[(master 7102
slots 10923-16383)]
    end
    A1 -- "TRACKING ON REDIRECT 11" --> N1
    A2 -- "TRACKING ON REDIRECT 7" --> N2
    A3 -- "TRACKING ON REDIRECT 7" --> N3
    N1 -. "invalidate spike:c1" .-> S1
    N2 -. "invalidate spike:c3" .-> S2
    N3 -. "invalidate spike:c2" .-> S3

What was ruled out, and why

Configuration #

Two ways to register the cache, and every option on RedisNearCacheOptions.

AddRedisNearCache has two overloads. Both register IRedisNearCache as a singleton together with the private connection, the tracking armer, and the invalidation listener it depends on.

The convenience overload takes a connection string directly and sets RedisNearCacheOptions.ConnectionString.

The full overload takes an Action<RedisNearCacheOptions> and lets you set every option, including Configuration (a ConfigurationOptions instance) instead of a plain connection string. Either Configuration or ConnectionString must end up set; resolving IRedisNearCache without one throws InvalidOperationException.

RedisNearCacheOptions

Serializer customisation

The default JsonRedisNearCacheSerializer uses System.Text.Json, with string and byte[] passed through untouched (no double-encoding, which matters for the IDistributedCache adapter). Pass your own JsonSerializerOptions to the constructor, or implement IRedisNearCacheSerializer directly for a non-JSON format.

API reference #

Every public member of RedisNearCache, one entry at a time.

ValueTask<T?> GetAsync<T>(
    string key,
    CancellationToken cancellationToken = default);

ValueTask SetAsync<T>(
    string key,
    T value,
    TimeSpan? expiry = null,
    CancellationToken cancellationToken = default);

ValueTask<bool> RemoveAsync(
    string key,
    CancellationToken cancellationToken = default);

void EvictLocal(string key);

bool TryGetLocal<T>(string key, out T? value);

RedisNearCacheStatistics Statistics { get; }

Task Ready { get; }

cache.Statistics.ToString();
// "hits=1 misses=1 invalidations=0 flushes=0 rearms=0 raceDiscards=0"

byte[] Serialize<T>(T value);
T? Deserialize<T>(ReadOnlyMemory<byte> data);

public static JsonRedisNearCacheSerializer Instance { get; }

public JsonRedisNearCacheSerializer(JsonSerializerOptions options);

public static IServiceCollection AddRedisNearCache(
    this IServiceCollection services,
    Action<RedisNearCacheOptions> configure);

public static IServiceCollection AddRedisNearCache(
    this IServiceCollection services,
    string connectionString,
    Action<RedisNearCacheOptions>? configure = null);

HybridCache and IDistributedCache #

An optional package that adapts IRedisNearCache to the standard distributed-cache abstractions.

A separate package from the core library.

This registers RedisNearCacheDistributedCache as both IDistributedCache and IBufferDistributedCache, backed by the IRedisNearCache that AddRedisNearCache already registered, and then calls AddHybridCache so that Microsoft.Extensions.Caching.Hybrid.HybridCache uses RedisNearCache as its distributed tier. Use AddRedisNearCacheDistributedCache() alone if you only want the IDistributedCache/IBufferDistributedCache adapters (for session state, output caching, etc.) without HybridCache.

public static IServiceCollection AddRedisNearCacheDistributedCache(
    this IServiceCollection services);

public static IServiceCollection AddRedisNearCacheHybridCache(
    this IServiceCollection services,
    Action<HybridCacheOptions>? configure = null);

// DistributedCacheEntryOptions -> TimeSpan? passed to SetAsync
// 1. AbsoluteExpirationRelativeToNow, if set
// 2. AbsoluteExpiration, converted to a relative duration
// 3. SlidingExpiration, treated as an absolute expiry
// null (never expires) if none of the three is set

Reconnects and cluster #

Tracking is per-connection state on the server. A reconnect of either connection invalidates it.

Tracking is state Redis holds per connection, so a reconnect of either of RedisNearCache’s own connections (on any node) invalidates that state.

Every re-arm after the very first one, and every “tracking lost” event, flushes L1 completely: anything invalidated during the gap would otherwise be lost. Statistics.Rearms counts each re-arm issued after the initial pass, and Statistics.Flushes counts every whole-cache flush (a null invalidation/FLUSHDB, a lost connection, or a re-arm). On a cluster, each master node is armed and re-armed independently: losing one node’s connections flushes L1 (nothing can be trusted while any node is unarmed) but only that node is re-armed.

Pass-through mode

Caching is only enabled while every known master is believed armed. The moment any endpoint is lost, the facade stops populating and reading L1 for every key, not only that endpoint’s keys, and flushes what is already there; reads go straight to Redis until that endpoint re-arms. This is what Ready’s doc comment calls pass-through: nothing is stored locally, so nothing can go stale from the gap.

Background retry every 5 seconds

An arm that exhausts its fast retry ladder does not give up: RedisNearCache starts a background loop, at most one per endpoint, that retries the arm every 5 seconds until it succeeds, the endpoint stops being a master, or the cache is disposed. A successful background retry is always reported with ArmReason.Recovered, which flushes L1 the same way any other re-arm does, because reads that were in flight while the node was untracked cannot be trusted.

Topology changes and EndpointRemoved

On a cluster configuration change, RedisNearCache arms any master it has never armed (ArmReason.TopologyChanged) and leaves already-armed masters alone. If a previously known master stops being a master (or drops out of the deployment) and a retry loop is still chasing it, RedisNearCache stops retrying and raises an internal EndpointRemoved event so that a node which will never come back does not keep the whole cache stuck in pass-through forever.

Replicas are ignored

Only masters are armed. A replica is never a valid arm target: CLIENT TRACKING is issued per master node, and RedisNearCache’s internal check for “is this a master we track” excludes replicas outright, whether or not the replica is currently connected.

Operations #

Logging categories, statistics to graph, detecting a lost endpoint, and sizing L1.

RedisNearCache does not register logging itself; if the host never called AddLogging, it silently uses a no-op logger. Wire up ILoggerFactory in your host to see any of this.

Logging categories

Statistics to graph

IRedisNearCache.Statistics exposes six thread-safe counters. Sample them periodically (they are cumulative, so graph the rate/delta, not the raw value) rather than trying to log every change.

Detecting a lost or unarmed endpoint

There is no dedicated “is everything armed” property, but you can reconstruct the current state from the pieces the library already exposes.

• Logs. TrackingArmer logs Warning for ConnectionFailed and for giving up on the retry ladder. Alert on these.
• Statistics. A rising Flushes/Rearms rate, or Hits dropping to near zero while Misses stays high, both indicate pass-through mode on at least one endpoint.
• Ready. Awaiting cache.Ready only tells you whether at least one master armed during startup; it does not fault for a single node that failed to arm among several, and it does not report a later loss. Treat a completed Ready as “the cache is usable”, not “every node is armed”.
• Direct check against Redis. CLIENT LIST filtered to RedisNearCache’s client name (ClientNamePrefix, default rnc-<guid>) and the P (pub/sub subscriber) flag tells you whether the subscriber connection currently exists; CLIENT TRACKINGINFO on the interactive connection reports whether tracking is on and what it currently redirects to.

Sizing L1

L1SizeLimit (default 10_000) counts entries, not bytes: every stored value costs a size of 1 regardless of how large it is. There is no automatic memory-based eviction, so size the limit based on (expected working-set key count) rather than a memory budget, and separately estimate memory as (number of entries you expect resident) × (average serialized value size). If your key space includes large or infrequently-reused values you would rather not hold in-process at all, use KeyPrefixes to opt only the keys worth caching into L1.

L1MaxAge (default 5 minutes) is a time-based safety net independent of size: it bounds how long a value can survive after a missed invalidation, not a sizing lever by itself. Setting it very high increases the blast radius of anything that does get missed; setting it very low pushes more traffic back to Redis even when tracking is working correctly.

Limitations #

• RESP3 push tracking is not used. StackExchange.Redis 3.x collapses RESP3 to a single connection and swallows the invalidation push frames on it, so RedisNearCache always forces RESP2 for its own connection.
• No OPTIN/OPTOUT tracking mode. CLIENT CACHING YES must be sent immediately adjacent to the next command on the wire, which is not guaranteed on a multiplexed connection. Selection of what gets cached is done in the library instead, via KeyPrefixes.
• Garnet is not supported. Garnet does not implement CLIENT TRACKING.
• TTL expiry is only reflected in L1 once Redis actually expires the key. Redis’s active expiry cycle, not the TTL deadline itself, is what triggers the invalidation push; there can be a gap between a key’s TTL elapsing and Redis noticing and sending the invalidation. L1MaxAge is the safety net for this and for any other missed invalidation.
• Per-write invalidation cost on hot keys. Every write to a tracked key causes Redis to push an invalidation to every reader that had it tracked; a very hot key can mean a lot of pushes. Use KeyPrefixes to opt only the keys you actually want cached into L1, so writes to everything else cost nothing extra.
• Ready only faults if no master could be armed at all. If some masters armed and others did not, Ready completes, but the cache stays in pass-through until every master is armed. Unarmed masters are retried in the background every 5 seconds. Watch Statistics.Hits: it stays flat while the cache is in pass-through.
• Sentinel, ElastiCache, and Azure Managed Redis are not yet tested. The tests in this repository run against a plain standalone Redis 7.4 container and a 3-master Redis Cluster started via cluster-up.sh. Nothing in the design specifically depends on the absence of Sentinel or a managed offering, but no test exercises those configurations, so this is genuinely untested rather than a documented guarantee.

Performance #

Quoted from bench/RedisNearCache.Bench/README.md; see that file for full methodology.

Both modes need a Redis server reachable at localhost:6379 (the repo’s docker compose container).

Zero-traffic demo

--demo seeds a key, reads it once through the near cache (a miss), then reads it 1,000 more times and checks the server’s cmdstat_get counter delta.

All 1,000 repeated reads were served from L1 with zero Redis traffic; the one external write (from a second, separate multiplexer standing in for another client) evicted the local copy in 1688.0 µs, which is the invalidation push’s round trip: write, Redis, __redis__:invalidate, subscriber, L1 evicted.

BenchmarkDotNet suite

Run on an Apple M4 Pro against a local single-node Redis container (Toolchain=InProcessEmitToolchain, RunStrategy=Monitoring, 10 iterations).

NearCache_Hit and NearCache_TryGetLocal are roughly 100x faster than a plain Redis round trip in this run, because they never leave the process. NearCache_Miss lands close to (and, for the string case, a little above) Plain_StringGet, since both do a real Redis round trip; the near cache’s overhead on the miss path is locking, in-flight bookkeeping, and deserialization. RunStrategy.Monitoring with only 10 iterations means run-to-run variance is higher than a long Throughput run would show; this is a deliberate trade-off to keep the whole suite finishing in well under a minute.

Load test

--load is a production-shaped run: many application instances, each with its own private multiplexer (two tracked connections), many concurrent readers per instance, and foreign writers whose every SET fans out an invalidation to every instance that has the key tracked. Ends with a staleness audit of every instance’s L1 against Redis. Run on an Apple M4 Pro against the repo’s local Redis 7.4 container, 2026-09-13.

Profile: 20 instances (41 server connections), 8 readers per instance reading as fast as they can, 4 writers at 2,000 foreign writes/s, 10,000 keys of 512 bytes with 80% of traffic on 500 hot keys, 30 s.

The three run modes.

What the numbers say:

• With the same 20 clients, the near cache served 7.2x the reads while sending the server 3.2x fewer commands and 3x less network output. The server’s GET rate is the miss rate, 4% of reads.
• Every foreign write reached, on average, 14 to 18 of the 20 instances as an invalidation (the 500 hot keys are tracked by almost everyone). 35k invalidations/s were absorbed with zero stale entries in the audit.
• The chaos run killed both connections of 5 instances at T/2. Each raised TrackingLost for both connections, reconnected, and was re-armed (InteractiveRestored and SubscriptionRestored) within about 120 ms; the sampled hit ratio dipped by under a point and recovered in the next 5 s window.
• Miss latency in the near-cache runs is worse than the baseline’s read latency (p99 12 ms vs 1.6 ms). That is a load-generator artefact: 160 readers spin at 1.4 M reads/s on a 14-core machine, so the continuation of a network read waits for a thread-pool slot. A service that does real work between reads would not see this. The hit path is unaffected (p50 0.8 µs).
• Race discards ran at about 1 per 10,000 reads. Each costs one extra round trip on the next read; none cost correctness.
• Observed once in five near-cache runs and not reproduced: the server closed all 40 tracked sockets at once (SocketClosed on both connection types of every instance, no CLIENT KILL issued). Every instance raised TrackingLost, reconnected and re-armed, and the audit still found 0 stale entries.

Samples #

Two runnable samples that show IRedisNearCache invalidated by something outside the process.

Both connect to localhost:6379. Start the standalone Redis container first, from the repo root.

Bring up Redis.

MinimalApi

An ASP.NET Core minimal API (samples/MinimalApi) with:

• GET /products/{id} — reads through IRedisNearCache.GetAsync<Product>("product:{id}"); on a miss it falls back to an in-memory ProductRepository (a fake data store with a simulated 50 ms lookup delay) and then SetAsyncs the result back into Redis.
• PUT /products/{id} — writes a Product via SetAsync.
• GET /stats — returns IRedisNearCache.Statistics as JSON.
• GET /hybrid/{id} — the same read, through Microsoft.Extensions.Caching.Hybrid.HybridCache (backed by RedisNearCache via AddRedisNearCacheHybridCache()).

Run it on a free port.

From a second terminal, curl it a couple of times, then invalidate the key from outside the app (a plain redis-cli SET, nothing that goes through this process) and curl again. The third call reflects the change because the server pushed an invalidation over CLIENT TRACKING and evicted the app’s L1 entry.

The 2nd call is an L1 hit (hits goes from 0 to 1, misses stays at 1). After the external redis-cli SET, the 3rd call already returns "changed": invalidations goes from 0 to 1 (the server pushed one), and the GET after it counts as a miss again because the near cache had to go back to Redis to re-populate L1 for that key. Note: because SetAsync (used by PUT /products/{id} and by the repository-fallback path on GET /products/{id}) evicts L1 rather than populating it, the read immediately after a write is always a miss; the next read after that is what gets served from L1.

Worker

A BackgroundService (samples/Worker) that polls the key config:feature-flags through the near cache every 500 ms and logs whether that tick was an L1 hit or a Redis miss, plus a full Statistics snapshot every 5 seconds.

Run it.

From a second terminal, change the watched key at any point and watch the very next tick pick it up.

config:feature-flags did not exist yet, so every tick is a miss (RedisNearCache never stores a null value in L1, so a missing key stays a miss on every poll) until the external redis-cli SET partway through. The first tick after the SET (misses=19) is still a miss, the read that goes to Redis and populates L1, but it already returns the new value. Every tick after that is a hit until the key is written again from outside.

FAQ #