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.

Redis remembers which keys each tracked connection has read, and when any client writes one of those keys it 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, not 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

Multi-key reads

GetManyAsync<T> and GetManyBytesAsync are the read path above run once per distinct key, not an MGET: starting every key’s read before awaiting any of them still pipelines the misses onto one round trip per node, while each key keeps its own in-flight guard, TTL cap and KeyPrefixes handling, and cluster slot routing keeps working.

Reconnects

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. AddRedisNearCache also registers an options validator (ValidateOnStart) that checks, among other things, that either Configuration or ConnectionString ends up set. A misconfigured registration throws OptionsValidationException — at host startup if you are running under IHost, otherwise the first time IRedisNearCache is resolved. See Options validation.

RedisNearCacheOptions

Serializer customisation

The default JsonRedisNearCacheSerializer uses System.Text.Json, with string and byte[] passed through untouched. The IDistributedCache adapter does not use the serializer at all, so a custom one does not affect it. Pass your own JsonSerializerOptions to the constructor, or implement IRedisNearCacheSerializer directly for a non-JSON format.

Options validation #

AddRedisNearCache registers a validator for RedisNearCacheOptions with ValidateOnStart, which checks: either Configuration or ConnectionString is set; L1SizeLimit is greater than zero; L1SizeLimitBytes is null or greater than zero; L1MaxAge is greater than TimeSpan.Zero or Timeout.InfiniteTimeSpan; ClientNamePrefix is non-empty and contains no whitespace; Serializer is not null; and KeyPrefixes contains no null or empty entry. A misconfigured registration throws OptionsValidationException — at host startup under IHost, or the first time IRedisNearCache is resolved otherwise.

Behaviour change: a misconfigured registration used to throw InvalidOperationException the first time IRedisNearCache was resolved. It now throws OptionsValidationException, and under IHost it throws at startup rather than on first resolve.

Key namespaces #

KeyNamespace puts a prefix in front of every key given to the cache, so several applications, tenants or cache instances can share one Redis database without their keys meeting: with "app1:", GetAsync("user:42") reads the Redis key app1:user:42. The caller's key becomes namespace + key once, at the cache's edge (GetAsync/GetBytesAsync, SetAsync/SetBytesAsync, RemoveAsync, EvictLocal and TryGetLocal); L1, the in-flight tracker and Redis all work on the full key from there, which is also what the server's invalidations carry, so the invalidation path never has to translate anything back. Callers keep using their own keys everywhere, including as the keys of the dictionary GetManyAsync returns. Anything that writes to Redis directly — another service, redis-cli — must use the full key for its write to invalidate the local copy; a write to the bare key, or to the same key under another namespace, is simply not this cache's key.

KeyPrefixes are relative to the namespace, and in TrackingMode.Broadcast a namespace with no KeyPrefixes arms the server with BCAST PREFIX <namespace> instead of the whole keyspace, which removes the main cost of running Broadcast mode with empty prefixes. Cost is one string concatenation per call, and only when a namespace is set. When you adopt a namespace, stop passing full keys: a key that already begins with it gets it a second time (app1:app1:user:42); the cache reports that once, as a warning, and otherwise does as asked. Log messages name the full key, as Redis sees it. On a cluster keep {…} out of the namespace, where it would be a hash tag that puts every key in one slot. With a namespace set, a null key throws ArgumentNullException. null or empty (the default) changes nothing: keys go to Redis exactly as given, byte for byte today's behaviour.

Named instances #

AddKeyedRedisNearCache adds a second (third, ...) IRedisNearCache under a name, alongside the default one from AddRedisNearCache or instead of it: its own options, its own private connections to Redis, its own L1 and statistics. Use it for a second Redis deployment, or for differently tuned caches over one (a different KeyNamespace, L1SizeLimit, TrackingMode, ...). Resolve it with [FromKeyedServices(name)] IRedisNearCache or GetRequiredKeyedService<IRedisNearCache>(name).

name is both the service key and the options name, so IOptionsMonitor<RedisNearCacheOptions>.Get(name) returns this instance's options; they are validated like the default instance's, at host startup under IHost. Options kept under a name that was not registered with AddKeyedRedisNearCache are left alone. Calling this twice with one name registers one instance. Metrics of a named instance carry an extra tag, rnc.instance = <name> (stable across restarts, unlike rnc.client_name); the default instance's metric series are unchanged. AddRedisNearCacheDistributedCacheFor(name) and AddRedisNearCacheHybridCacheFor(name, configure?), in the RedisNearCache.HybridCache package, back the application's single IDistributedCache/HybridCache with a named instance the same way the unnamed forms back it with the default one (first registration wins). See Health check for wiring a health check to a named instance.

Every named instance opens its own connections to Redis (one multiplexer plus its subscriber, or its own Broadcast sockets), so registering several is several times the connections. See Limitations for a caveat around keyed services in general.

Managed services #

Where RedisNearCache runs, which tracking mode each platform needs, and how TrackingMode.Broadcast works on Redis Enterprise-based services.

Supported platforms

Redis Enterprise, Azure Managed Redis, Redis Cloud

The proxy in front of these Redis Enterprise-based services (databases 7.4+, the versions on which they support client-side caching) rejects tracking outright on RESP2 (ERR Client tracking is not supported when using RESP2), rejects REDIRECT under RESP3 with a syntax error, and its CLIENT LIST does not show RedisNearCache’s subscriber connection — so the default Redirect mode cannot arm there at all. Arming now fails with a clear error telling you to set TrackingMode.Broadcast, rather than a bare server exception.

In Broadcast, RedisNearCache opens one small RESP3 connection of its own per master — TLS and auth taken from the same connection settings as the private multiplexer, client name <private client name>-bcast — and sends HELLO 3 followed by CLIENT TRACKING ON BCAST PREFIX <p> for every entry of KeyPrefixes. That connection then receives an invalidation push for every write or delete under those prefixes from any client, whether or not this instance holds the key; FLUSHDB and FLUSHALL arrive as the null invalidation and flush L1 like anywhere else. Reads still go through the private multiplexer, unchanged. Replicas are not pre-armed in this mode — there is no redirect target to keep warm across a promotion — so a newly promoted master gets its own broadcast connection at the next topology check (every 5 s).

If the broadcast connection dies — the socket closes, or a keepalive PING sent every 10 s goes unanswered for 5 s — the cache goes pass-through for that endpoint, reconnects with the same fast ladder (100 ms, 300 ms, 1 s, 1 s, then every 5 s), re-arms, and flushes L1: the existing “any reconnect on any master means re-arm then flush” rule applies here exactly as it does to the interactive/subscriber pair in Redirect mode.

NOLOOP cannot apply here: it suppresses pushes for writes made by the tracking connection itself, and the broadcast connection never writes. So this instance’s own SetAsync and RemoveAsync (sent on the private multiplexer) echo back as pushes. That is harmless for coherence — the facade already evicts the key around its own write — but it means a GetAsync issued right after a SetAsync can have its reply discarded once by the in-flight rule when the echo lands between the GET reply and the store; the read after that caches the key.

The CLIENT CACHING NO transaction that Redirect sends for reads outside KeyPrefixes is skipped in Broadcast: the reading connection was never tracked, so a plain GET is already untracked. Set KeyPrefixes: leaving it empty is legal but means every write in the database is broadcast to this client (logged once as a warning), and a prefix that overlaps another already configured one is dropped with a log line, because Redis rejects overlapping prefixes for one client. Invalidation volume scales with the write rate under the prefixes rather than with what L1 holds, and the server’s per-key tracking table is not used, so the Enterprise tracking_table_max_keys limit does not apply. Broadcast also works on OSS Redis 6+ and Valkey — CI runs the Broadcast suite on every image — but Redirect stays the default there since it only pushes for keys this instance actually read.

Custom certificate validation registered through ConfigurationOptions.CertificateValidation is not visible to the broadcast connection; supply it through ConfigurationOptions.SslClientAuthenticationOptions instead.

Entra ID

Entra ID authentication (Microsoft.Azure.StackExchangeRedis) works with Broadcast, including in-place re-authentication of a live connection when the token rotates. Configure ConfigurationOptions with the extension and pass it as RedisNearCacheOptions.Configuration; RedisNearCache clones those options, and the clone shares the extension’s token provider — ConfigurationOptions.Defaults, where the extension installs it, is copied by reference on Clone(). The private multiplexer is created from that same provider, so the extension registers it through its AfterConnectAsync hook and re-authenticates it exactly as it does any multiplexer it manages; every broadcast connection reads the current object id and token when it connects; and a live broadcast connection compares its current credentials against the provider on every keepalive tick (10 s, up to about 15 s if a PING is in flight), re-authenticating in place with AUTH <objectId> <token> when they changed — no TrackingLost, no L1 flush. If the server rejects the rotated credential, the connection keeps the one it has (a failed AUTH leaves a Redis connection’s authentication unchanged) and stays armed; the rotation is retried as soon as the provider yields a different credential, and a connection the server closes at token expiry is re-armed with an L1 flush like any reconnect. The broadcast connection’s in-place re-authentication works the same for any rotating credential supplied through a custom DefaultOptionsProvider subclass whose User/Password overrides change (ACL password rotation, for example); values set directly on ConfigurationOptions.User/Password are static and shadow the provider, so use the provider for rotation. Re-authenticating the private multiplexer itself is the provider’s job, which the Azure extension does through its AfterConnectAsync hook and a hand-written provider must do too.

Test locally with ./enterprise-up.sh (a single-node Redis Software container behind its proxy at localhost:12000), then RNC_ENTERPRISE_REDIS=localhost:12000 dotnet test tests/RedisNearCache.Tests --filter FullyQualifiedName~RedisNearCache.Tests.Enterprise.

API reference #

Every public member of RedisNearCache.

IRedisNearCache is for consuming, not implementing: the library’s own implementation is the only supported one, and members may be added to the interface in a minor release. To wrap or decorate it, delegate to the registered instance.

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.

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; a master found already pre-armed as a replica is moved to the armed-master set with ArmReason.Promoted instead: no re-arm and no pass-through gap, one flush. 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 pre-armed, not read from

Only masters are ever read from, and only masters count toward pass-through, but every connected replica is armed ahead of time too: CLIENT TRACKING ON REDIRECT <id> OPTOUT NOLOOP immediately followed by ROLE on the same connection, to confirm it is still a replica once the command completes. A replica is never read through RedisNearCache, so pre-arming costs nothing and its tracking table stays empty until it is promoted; from the first read routed to it after that, the key is tracked, which is what lets a promotion be reported as ArmReason.Promoted with no re-arm and no pass-through gap (L1 is still flushed once, for the entries read from the demoted master). A pre-armed replica whose connection fails, or whose replication link goes down, loses its pre-arm and is re-armed by a later reconcile sweep (every 5 s) once the multiplexer confirms it is still a replica.

Operations #

Logging categories, statistics to graph, detecting a lost endpoint, sizing L1, metrics, the health check, and ACL permissions.

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.
• IsCoherent. True only while every known master is armed and L1 is trusted; check it directly, or await WaitForCoherenceAsync, instead of inferring pass-through from Statistics.Hits.
• 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, and MemoryCache compacts by priority then least-recently-used once it is full, so a new entry may not be stored until compaction has run (the read itself still returns the value). 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). Set L1SizeLimitBytes instead if you would rather bound L1 by the total bytes of the cached values; when it is set, L1SizeLimit is ignored and a single value larger than the limit is never cached (it is still returned to the caller). 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.

Metrics #

Every instance owns a System.Diagnostics.Metrics Meter named RedisNearCache (the constant RedisNearCacheStatistics.MeterName), disposed with the cache. No new package dependency is needed. Every instrument is observable: each is read from Statistics, L1 or the armer when something collects, so nothing is added to the read path. Every measurement carries the tag rnc.client_name, the Redis client name of that instance's private connection ({ClientNamePrefix}-{guid}), so several instances in one process stay distinct in the same exported series. An instance registered with AddKeyedRedisNearCache carries a second tag, rnc.instance, holding the registration name — stable across restarts, unlike rnc.client_name. The default instance's series are unchanged. The instruments keep the redisnearcache.* prefix rather than following OpenTelemetry's semantic conventions for cache/database clients (cache.*/db.*): renaming would break every dashboard built against the current names, and publishing both would double every series.

Wire it into OpenTelemetry with .WithMetrics(m => m.AddMeter(RedisNearCacheStatistics.MeterName)), or watch it ad hoc with dotnet-counters monitor -n <app> --counters RedisNearCache.

Tracing #

Every instance also owns a System.Diagnostics.ActivitySource named RedisNearCache (the constant RedisNearCacheStatistics.ActivitySourceName — deliberately the same string as MeterName, so the metrics and the spans of one instance are one instrumentation scope), disposed with the cache. Two spans only, both ActivityKind.Client: redisnearcache.read around the Redis round trip of a read that missed L1, and redisnearcache.arm around arming CLIENT TRACKING on one endpoint (the initial arm and every re-arm, told apart by the rnc.arm_reason attribute rather than a second span name). An L1 hit produces no span at all — it returns before the cache even calls into tracing, so the common case pays nothing extra.

There is no flush span: a flush runs on the invalidation-handler path, which must add nothing observability-related, and is already visible through redisnearcache.flushes and its reason tag (see Metrics).

Health check #

RedisNearCacheHealthCheck (namespace RedisNearCache, in the core package) implements IHealthCheck. It reports Healthy while IsCoherent is true, and Degraded — not Unhealthy — while it is not, because reads still succeed as pass-through to Redis even when nothing is cached locally. The core package takes one extra dependency for it, Microsoft.Extensions.Diagnostics.HealthChecks.Abstractions; AddHealthChecks() itself comes from ASP.NET Core or the Microsoft.Extensions.Diagnostics.HealthChecks package in your application. There is deliberately no IHealthChecksBuilder extension method for it, since that would need the full Microsoft.Extensions.Diagnostics.HealthChecks package, a dependency this library does not take.

The result's Data carries every Statistics member (coherent, hits, misses, invalidations, flushes, rearms, raceDiscards, l1Entries, passThroughSeconds, lostEndpointCount, ttlCapAbandoned, untrackedReadsUnavailable, serializerFailures, l1StoreRefusals, preArmFailures), plus lostEndpoints — the lost endpoints' addresses, comma-joined. Unlike the rest, lostEndpoints is present only when the health check is wired to this library's own RedisNearCache, because an endpoint address is unbounded cardinality and so is never on Statistics itself (see Metrics); a caller's own IRedisNearCache implementation reports the other keys from its own counters' defaults and simply has no lostEndpoints entry, rather than an empty one that would read as "nothing is lost".

There is no separate health check type for a named instance: RedisNearCacheHealthCheck.Registration(name?, serviceKey?, tags?) builds a ready-made HealthCheckRegistration for the IHealthChecksBuilder you already have, resolving the cache by its service key inside the registration factory — pass serviceKey for a cache registered with AddKeyedRedisNearCache, or call it with no arguments for the default instance. name defaults to "redis-near-cache" for the default instance or $"redis-near-cache-{serviceKey}" for a keyed one, so two keyed registrations cannot collide.

ACL permissions #

What a least-privilege ACL user needs. The two users on the right are exercised by the test suite (Auth/PasswordAndAclTests.cs, Auth/AuthClusterTests.cs: standalone and a three-master cluster, on Redis 6.2 to 8 and Valkey 8.1), end to end — arm, cached read, an external write evicting it, a read outside KeyPrefixes, a key with a TTL, SetAsync, RemoveAsync, and in Broadcast a keepalive tick — with the server's ACL LOG asserted empty afterwards, replicas included: nothing the library or StackExchange.Redis sends is denied.

For RedisNearCache itself. In TrackingMode.Redirect: CLIENT LIST, CLIENT TRACKING, CLIENT TRACKINGINFO (optional — a rejection is tolerated, it only affects arm verification), CLIENT CACHING with MULTI/EXEC (only needed when KeyPrefixes is set; a rejection degrades to tracking those keys instead of an error), ROLE (the replica pre-arm; a rejection is logged at Debug only and the pre-arm quietly stops happening), CLUSTER NODES (cluster deployments only), SUBSCRIBE plus channel permission for &__redis__:invalidate, GET, PTTL (optional — a rejection abandons the TTL cap rather than the cache), SET, and SETEX and PSETEX (SetAsync with an expiry: StackExchange.Redis sends SETEX for a whole number of seconds and PSETEX otherwise), and UNLINK (RemoveAsync: StackExchange.Redis sends UNLINK, not DEL). TrackingMode.Broadcast needs CLIENT ID, CLIENT TRACKING, CLIENT TRACKINGINFO (optional) and PING on its own connection (HELLO, which also names the connection, and AUTH need no grant), plus the data commands above on the multiplexer; it does not use CLIENT LIST, ROLE, CLIENT CACHING or the invalidation channel. PING is not optional there: a denied keepalive reads as a dead connection, which costs a reconnect, a re-arm and an L1 flush.

For StackExchange.Redis, on the private multiplexer, in either mode: INFO, ECHO and CONFIG GET (without these three it cannot connect at all), SELECT, CLIENT ID, CLIENT SETNAME, PING, SUBSCRIBE, from Redis 7.2 CLIENT SETINFO, and on a cluster CLUSTER NODES, CLUSTER SLOTS and READONLY (sent on its replica connections); key permission for its tie-breaker key __Booksleeve_TieBreak and channel permission for its configuration channel &__Booksleeve_MasterChanged (both are ConfigurationOptions settings: grant whatever yours are set to). About half the grants below are its, not this library's.

Replace ~product:* with the keys you cache. resetchannels is there for Redis 6.2, whose users default to every channel; it is the default from 7.0. +client|setinfo is left out of the examples on purpose: the command exists from Redis 7.2, where StackExchange.Redis sends it on every connection, so add it there; Redis 7.0 and 7.1 refuse a rule that names it (and refuse to start if it is in the configuration file), and the client never sends it to them. The test containers add it after start-up, ignoring a refusal.

Limitations #

• RESP3 push tracking is not used on the multiplexer. 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 private multiplexer. TrackingMode.Broadcast is the exception: it uses RESP3 on its own separate connection, one per master, dedicated to receiving BCAST pushes; see Redis Enterprise, Azure Managed Redis, Redis Cloud.
• Tracking selection is OPTOUT, not OPTIN (Redirect mode). The private connection is armed OPTOUT; a read outside KeyPrefixes is preceded by CLIENT CACHING NO (inside a MULTI/EXEC, so the two stay adjacent on the wire), which is also what keeps it out of L1.
• Garnet is not supported. Garnet does not implement CLIENT TRACKING.
• TTL expiry is only reflected in L1 immediately when RespectServerTtl is on (the default). Off, an L1 entry survives until an actual invalidation arrives or L1MaxAge drops it: Redis’s active-expiry cycle, not the TTL deadline itself, is what triggers the invalidation push, and that cycle can lag the deadline by minutes on a large keyspace (measured on Redis 7.4 with 300,000 keys carrying TTLs, default hz 10: a key with a 2-second TTL, read once and never touched again, had still not been expired 150 seconds later). With RespectServerTtl on, the cap comes from a PTTL read pipelined with every miss’s GET (one extra command, no extra round trip), so a value is never served locally past its TTL.
• 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. Use IsCoherent or WaitForCoherenceAsync to observe or wait for that directly, instead of watching Statistics.Hits.
• ElastiCache Serverless cannot run RedisNearCache at all. Its own list of supported and restricted commands marks client tracking, client caching, client trackinginfo, client list and client id unavailable, and neither TrackingMode needs any of those to work around it. Redis Enterprise-based services need TrackingMode.Broadcast. Azure Managed Redis is built on Redis Enterprise, and Redis’s own client-side caching compatibility page for Redis Software and Redis Cloud states that client-side caching needs RESP3 and that two-connections mode and the REDIRECT option are not supported, so the default Redirect mode cannot run on Azure Managed Redis, Redis Cloud or Redis Software in any tier; TrackingMode.Broadcast does, and arming with Redirect now fails with a clear message naming these services and pointing at TrackingMode.Broadcast. See Redis Enterprise, Azure Managed Redis, Redis Cloud. Node-based ElastiCache and the older, OSS-based Azure Cache for Redis are unverified rather than ruled out; set RNC_EXTERNAL_REDIS to a real connection string and run ExternalManagedEndpointTests to check one; it only writes and deletes its own keys. (Sentinel is tested directly; see Testing.)
• A Sentinel failover flushes the local cache. When Sentinel promotes a replica, the old master is forgotten, L1 is flushed and the promoted master is armed within a few seconds of Sentinel announcing it. In Redirect mode replicas are pre-armed here too, so the promoted master is usually already tracked by the time Sentinel announces it, but the flush still happens regardless: entries read from the old master are protected by nothing once it is gone. A master that is down with no replacement yet keeps the cache in pass-through, which is the safe side.
• SWAPDB sends no invalidation. This is a server-side gap, not something RedisNearCache can detect: in both Redis and Valkey, dbSwapDatabases only touches WATCH state and calls no tracking invalidation. Verified on Redis 7.4: after SWAPDB the tracked key no longer exists in the connection’s database, but the server pushes nothing, so the local copy survives until L1MaxAge. Call EvictAllLocal() right after a SWAPDB on a database whose keys are cached, or avoid SWAPDB on it.
• The database number is not part of tracking. Redis tracks by key name only: a write to k in database 0 invalidates a cached k read from database 2. Harmless (an extra miss), but worth knowing if you reuse key names across databases; set a different KeyNamespace per database or application to avoid the collision instead.
• Cluster failover bookkeeping still catches up at the next topology check (up to 5 s). In Redirect mode replicas are pre-armed, so a read routed to a freshly promoted master is tracked from the moment it is promoted; what still waits for the topology check is RedisNearCache noticing the promotion and moving the endpoint from a pre-armed replica to an armed master, which is no longer a staleness window. StackExchange.Redis does call ReconfigureIfNeeded on a MOVED reply, but only when the last reconfigure was more than 5 s ago, so a run of local hits with no misses can still go that long without noticing a failover on its own.
• mTLS on the Broadcast connection needs SslClientAuthenticationOptions. The broadcast socket takes its TLS settings from ConfigurationOptions.Ssl, SslHost, SslProtocols and CheckCertificateRevocation, but ConfigurationOptions.CertificateSelection and CertificateValidation are events on ConfigurationOptions that nothing outside StackExchange.Redis can read, so the broadcast socket cannot use them. Supply a client certificate or custom validation for it through ConfigurationOptions.SslClientAuthenticationOptions instead, which is used verbatim when set, exactly as on the library’s own TLS path. With the client certificate supplied only through the event, Redirect works and Broadcast fails loudly: Ready faults within a few seconds with a RedisNearCacheTrackingException wrapping the TLS AuthenticationException (the server certificate it could not validate, or the client certificate it could not present, whichever the platform reaches first), the cache stays in pass-through (reads are correct, nothing is stored) and the reason is logged as a warning. All four combinations are covered by Auth/MutualTlsTests.cs against a server that requires client certificates.
• Sentinel and the data nodes share one password. ConfigurationOptions carries a single Password for both hops, so this is StackExchange.Redis’s rule rather than this library’s. Sentinels with the same password as the data nodes work, and so do sentinels with no password in front of data nodes that require one (the sentinel’s AUTH error is tolerated). A sentinel password that differs from the data nodes’ cannot be expressed: the connection fails at once with WRONGPASS, as it does for a plain ConnectionMultiplexer. Covered by Auth/SentinelAuthTests.cs.
• Dragonfly, KeyDB, AWS MemoryDB and Google Cloud Memorystore have not been tested. Memorystore for Redis (the non-cluster tier) blocks the CLIENT command group entirely, so RedisNearCache cannot work against it at all. Memorystore for Redis Cluster lists CLIENT TRACKING and CLIENT CACHING as supported, but is untested here. Dragonfly, KeyDB and AWS MemoryDB are untested either way.
• The stated floor is Redis 6, but CI starts at Redis 6.2. Redis 6.0 and 6.1 are untested.
• Some code that scans IServiceCollection throws on a keyed registration. AddKeyedRedisNearCache registers keyed services, and code that walks every descriptor reading ImplementationType/ImplementationFactory (some older scanning or decorator libraries, predating keyed services in Microsoft.Extensions.DependencyInjection) throws on one. This is a general keyed-services caveat, not specific to RedisNearCache; it does not affect the default, unnamed registration from AddRedisNearCache.

Performance #

RedisNearCache against the caches a .NET team would otherwise use, under writes from another client and under writes through each library’s own API. Full tables, methodology and how to run them are in bench/RedisNearCache.Bench/README.md.

20 application instances, 160 readers, 2,000 writes/s, 10,000 keys of 512 bytes (80 % of reads on 500 hot keys), 30 s per run, Redis 7.4 in Docker on one Apple M4 Pro. TTL-based caches use a 10 s TTL. Writes come from another client doing a plain SET unless the row says otherwise.

Testing #

Coherence is the whole product, so most of the tests run against real Redis in Docker: standalone, a replica, a TLS server, a six-node cluster, a Sentinel-managed master with two replicas, and two containers that emulate managed-service restrictions. The same script brings that stack up on your machine and in CI.

What runs

Where it runs

CI runs the unit tests on .NET 8 and 10, then the integration tests (including the Broadcast suite) against Redis 7.4, and again against Redis 6.2, 7.0, 7.2, 8 and Valkey 8.1 in a matrix. Tests that need a feature a server lacks (subcommand-level ACL denial, FCALL, hostname-announcing clusters on 6.2) skip on that server and say so in the output. A separate job, “integration on Redis Enterprise (Redis Software in Docker)”, brings up enterprise-up.sh and runs the Enterprise suite with RNC_ENTERPRISE_REDIS=localhost:12000. After each run a check reads the results and fails the job if any suite ran no tests, so a missing container or a changed filter cannot pass silently. All of these jobs are required status checks on main. The soak test runs on manual dispatch.

Two behaviours the compat tests established, both documented under Limitations: SWAPDB sends no invalidation, and the database number is not part of tracking. One defect they exposed was fixed: a promoted cluster master used to be armed about 60 s after a failover; the private multiplexer now checks topology every 5 s and the measured delay is 4 s. The Sentinel tests exposed two more, both fixed. A killed master kept the cache in pass-through forever, because a node that can’t be reached never reports a new role. And after a graceful failover a value read from the demoted master could be served stale, because losing a node we had armed was ignored once the node was flagged as a replica. Later additions are covered by Resilience/ClusterFailoverPreArmTests.cs (replica pre-arm survives a cluster failover and the promoted node is tracked from the first read), EdgeCases/ServerTtlCapTests.cs and EdgeCases/OptOutUntrackedReadsTests.cs, plus the pre-arm bookkeeping unit tests in RedisNearCache.UnitTests/ReplicaPreArmTests.cs.

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 #