feat(csc): multi-strategy client-side caching (Broadcast / PerConnection / SharedTracking)

[ofekshenawa]

Note

Medium Risk
Large correctness-sensitive change to caching, invalidation timing, and connection lifecycle; mitigated by extensive tests and conservative flush/disable paths on sidecar failure and disconnect.

Overview
Adds Options.ClientSideCacheStrategy (CSCStrategySharedTracking default, Broadcast, PerConnection) so RESP3 client-side caching can pick how invalidations reach the cache, with docs/csc-strategy-guide.md describing trade-offs.

SharedTracking (default behavior change): drops the per–cache-hit drainPendingInvalidations sweep and runs a background drainer (configurable DrainInterval, default 5ms) that uses pool.DrainIdleConns and drainPushNotifications with a hard read deadline. Cache hits are served without re-draining the pool first.

Broadcast: a dedicated BCAST sidecar (CLIENT TRACKING ON BCAST) feeds the shared cache; pool connections do not enable tracking. Sidecar disconnect/reconnect flushes the cache; failed sidecar start disables CSC for that client.

PerConnection: private localCache per pool conn, commands bound to one conn via cscPerConnTryProcess, with invalidations routed to that conn’s cache only.

localCache: sharded storage with approximate LRU, plus MaxStaleness and DrainInterval on CacheConfig. CSC is limited to DB == 0 (logged disable otherwise).

Observability: Client.CSCStats(), process-wide CommandStats() / RESPInvalidationBytesRead(), and pool conn lastPushDrainAt to skip redundant push peeks.

^{Reviewed by Cursor Bugbot for commit 6f3ca29. Bugbot is set up for automated code reviews on this repo. Configure here.}

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6f3ca29. Configure here.}

[cursor]

Reader-buffered pushes skipped

Medium Severity

Sharded NewLocalCache assigns each shard ceil(MaxEntries / shardCount) as its own cap and evicts per shard independently, so total resident entries can exceed CacheConfig.MaxEntries (e.g. 100 configured with 16 shards allows up to 112).

Additional Locations (1)

• csc_per_connection.go#L301-L307

 

^{Reviewed by Cursor Bugbot for commit 6f3ca29. Configure here.}

[cursor]

SharedTracking drainer skips custom pools

Medium Severity

startBackgroundDrainer no-ops unless connPool is *pool.ConnPool, and processCached no longer drains invalidations on cache hits. SharedTracking clients with a custom Pooler may apply idle invalidations only when a connection runs a command, widening staleness beyond the documented drain interval.

Additional Locations (1)

• csc_integration.go#L242-L250

 

^{Reviewed by Cursor Bugbot for commit 6f3ca29. Configure here.}