DOC-6831 Document go-redis client-side caching - #3613
Open
andy-stark-redis wants to merge 5 commits into
Open
Conversation
andy-stark-redis
added
do not merge yet
parked
Contributor
Contributor
andy-stark-redis
force-pushed
the
DOC-6831-document-go-redis-client-side-caching-pr-3851
branch
from
July 10, 2026 14:07
240613e to
f41d88c
Compare
Add a "Connect using client-side caching" section to the go-redis connect page covering the multi-strategy CSC being added in redis/go-redis#3851: enabling via ClientSideCacheConfig on a RESP3 client, the three ClientSideCacheStrategy options (SharedTracking default, Broadcast, PerConnection), the tuning options (MaxEntries, MaxMemoryBytes, DrainInterval, MaxStaleness), and monitoring via CSCStats plus the process-wide stats functions. Register go-redis in the support table and relatedPages of the CSC introduction page. Written against the unmerged upstream PR, so the section carries a pre-release warning and the version is a TBD placeholder. Parked pending the upstream merge and release. Experience: Rejected /park's page-level bannerText in favour of a section-scoped {{< note >}} warning — the CSC section lives in an otherwise-released Connect page, so a page banner would wrongly flag basic/TLS/cluster/SCH as unreleased. Don't "correct" the missing bannerText on pickup; the section-scoped warning is intentional. Recheck: fill go-redis version once #3851 merges and is tagged (connect.md note + client-side-caching.md support table both use a "v9.<!-- DOC-6831: set on merge -->TBD" placeholder) Recheck: confirm final exported names against merged source — ClientSideCacheConfig, ClientSideCacheStrategy, CSCStrategy{SharedTracking,Broadcast,PerConnection}, ClientSideCacheConfig fields, (*Client).CSCStats, redis.CommandStats/CacheAdmissionRejects/RESPInvalidationBytesRead Recheck: verify DrainInterval default (5ms) / floor (1ms) and MaxEntries default (10000) survive to release Recheck: base of #3851 is the feature branch csc-standalone-connection-support, not master — confirm the whole CSC stack lands on master before treating the trigger as fired Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
andy-stark-redis
force-pushed
the
DOC-6831-document-go-redis-client-side-caching-pr-3851
branch
from
July 10, 2026 14:08
f41d88c to
396986f
Compare
Unpark reconciliation. go-redis v9.22.0 shipped CSC on 2026-08-03, so the version placeholders become v9.22.0 and the "not yet released" warning goes. The park snapshot was tagged LOW confidence and earned it. The upstream PR the page was written against, #3851, was superseded by #3941, and the shape that actually shipped is materially smaller than the one predicted. Three things the page documented do not exist in the release: the CSCStrategyBroadcast and CSCStrategyPerConnection strategies were never implemented (only CSCStrategySharedTracking exists, and Options.init clamps anything else to it with a log warning), CSCStats returns a struct rather than two uint64s, and none of the three package-level stats functions were ever exported. So the strategy table, its worked example, and the per-strategy cache note were all describing an API that no user could call. I proved this rather than eyeballing it by building the documented calls against the released module: the new code compiles, the old code fails with three errors that map exactly to the three findings. Because there is now one strategy and no choice to make, the strategy section became a plain explanation of how invalidation reaches the cache. That keeps the genuinely useful part -- invalidation is asynchronous, which is a correctness fact a reader needs -- while documenting an option with a single legal value would have been noise. The snapshot also under-recorded the restrictions, which is the more dangerous direction to be wrong in. Enabling CSC makes go-redis reject SELECT, AUTH, HELLO with arguments, RESET, CLIENT TRACKING and the raw subscribe commands, and one rejected command fails its whole pipeline; a credentials provider silently disables caching. Those can break working code, so they now have their own section instead of being absent. Learned: a merged-and-tagged upstream PR is not the PR the docs were written against; verify the released module by compiling against it, not by reading the diff that was parked Constraint: only CSCStrategySharedTracking exists in go-redis v9.22.0 -- do not document Broadcast or PerConnection strategies unless a release adds them Constraint: CSCStats() returns a CSCStats struct (Hits, Misses, Entries, MemoryUsageBytes), not a two-value (hits, misses) tuple Rejected: documenting ClientSideCacheStrategy as a tunable option | it has exactly one legal value and unknown values are clamped, so presenting it as a choice misleads Directive: go-redis CSC is Experimental and may change in a minor release; re-verify the exported names against the released module on any go-redis version bump touching this page Gaps: the enable and monitoring snippets are compile-verified against v9.22.0 but not run against a live server, so the MONITOR-based cache-hit demonstration is reasoned from the upstream example rather than observed Recheck: when go-redis adds a second CSC strategy or promotes the feature out of Experimental Ticket: DOC-6831
Contributor
🧠 Redis MemoryFound 5 related items from repository history:
Memory updated at 8df32d1 |
Trim the cacheable-command detail, which the client-side caching introduction page already covers under "Which commands can cache data?", and expand the closing note about ClientSideCache into a "Supplying your own cache" section. The section documents three levels of customization, because the release supports three and they differ a lot in effort: set Sizer if you only want to change how entry memory is estimated, wrap the built-in cache if you want to change behavior, or implement the eight-method Cache interface from scratch. Wrapping is the one worth leading with, and go-redis's own tests use exactly that shape. The wrapping advice carries a footgun I verified rather than assumed. Cache statistics are read through an optional Stats() method that the Cache interface does not declare, so a decorator that embeds the interface satisfies Cache, compiles, and silently makes CSCStats() report zeros; embedding the concrete *LocalCache promotes Stats() and keeps it working. I confirmed both directions by compiling against v9.22.0 -- the concrete form satisfies an anonymous Stats() CSCStats interface and the interface form fails with "missing method Stats" -- then compile-verified the documented snippet as written, including the Sizer signature. Learned: an optional method reached by type assertion is invisible to the interface, so wrapping advice must name the concrete type to embed or it silently degrades a feature Constraint: custom cache decorators must embed the concrete *redis.LocalCache, not the redis.Cache interface, or CSCStats() reports zeros Gaps: the countingCache snippet is compile-verified against v9.22.0 but not run against a live server, so the lookup counter is not observed incrementing Ticket: DOC-6831
Contributor
🧠 Redis MemoryFound 5 related items from repository history:
Memory updated at e5a21fd |
Copyedit only: no change to the documented API surface or behavior. Ticket: DOC-6831
Contributor
🧠 Redis MemoryFound 5 related items from repository history:
Memory updated at bad83f9 |
andy-stark-redis
removed
do not merge yet
parked
andy-stark-redis
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents client-side caching (CSC) in go-redis, released in
v9.22.0 via
redis/go-redis#3941. Adds a
Connect using client-side caching section to the go-redis connect page and
registers go-redis in the CSC introduction page (support table +
relatedPages).The section covers:
ClientSideCacheConfigon a RESP3 client, and the RESP3 /standalone / database-0 requirements.
MaxEntries,MaxMemoryBytes,MaxStaleness,DrainInterval.CSCStats().Sizerhook, wrapping the built-inLocalCache,or implementing the
Cacheinterface.Ready for review
This PR was originally written against the unmerged upstream PR
#3851 and parked. It has now been
reconciled against the released
v9.22.0source, so the parked warning, theversion placeholders, and the unpark manifest are gone.
The pre-release API differed substantially from what shipped, and the page has
been corrected accordingly:
ClientSideCacheStrategyoptionsCSCStrategySharedTrackingexists; other values are clamped to it with a log warninghits, misses := client.CSCStats()CSCStatsstruct (Hits,Misses,Entries,MemoryUsageBytes)redis.CommandStats(),redis.CacheAdmissionRejects(),redis.RESPInvalidationBytesRead()Every Go snippet on the page was compile-verified against
github.com/redis/go-redis/v9@v9.22.0. The config field names and defaults(
MaxEntries10,000;DrainInterval5ms default / 1ms floor) and the RESP3-only,database-0-only, and RESP2 no-op behaviors were all confirmed against the
released source. Hugo builds clean.
Notes for the reviewer
section carries an experimental caveat rather than presenting the API as stable.
{{< note >}}, not a page-levelbannerText,deliberately: the rest of the Connect page documents released features, so a page
banner would wrongly flag them.
page, which already covers it.
time series commands are not cached, but go-redis's cacheable-command allow-list
includes
TS.GET,TS.INFO,TS.RANGE, andTS.REVRANGE. The probabilistic andFT.*exclusions do match.Note
Low Risk
Documentation-only changes with no effect on runtime behavior; API details may still shift while the feature is experimental and the PR is parked pending a stable go-redis release.
Overview
Documents go-redis client-side caching (CSC) alongside the existing Python, Node, and Jedis guides.
The client-side caching introduction page now links to the Go connect guide and lists go-redis v9.22.0 in the support table.
The Go connect page gains a Connect using client-side caching section: enable with
ClientSideCacheConfigon a RESP3 (Protocol: 3) standalone client; notes on experimental status, Redis v7.4+, RESP2 no-op, and DB 0 only. It explains pool-wide shared invalidation, tuning viaMaxEntries,MaxMemoryBytes,MaxStaleness, andDrainInterval,CSCStats()monitoring, and custom caches via theCacheinterface (including embedding*LocalCachefor stats and optionalSizer).Reviewed by Cursor Bugbot for commit bad83f9. Bugbot is set up for automated code reviews on this repo. Configure here.