Repository navigation
DOC-7175 Document StackExchange.Redis v4 client-side caching [PARKED] - #4250
Open
andy-stark-redis wants to merge 1 commit into
Open
andy-stark-redis wants to merge 1 commit into
andy-stark-redis wants to merge 1 commit into
Conversation
Adds a "Connect using client-side caching" section to dotnet/connect.md (after SCH), a production-usage checklist stub, and a StackExchange.Redis row plus relatedPages entry on the client-side caching overview. Written against the 4.0.127-alpha pre-release and the upstream draft docs/ClientSideCaching.md at v4 commit cc2c362466; option names and defaults were cross-checked against src/StackExchange.Redis/Caching/*.cs at the 4.0.127-alpha tag (CacheOptions, CachePolicy, CacheAdmission, CacheTrackingMode). None of the caching types carry [Experimental], so unlike the SCH section there is no SERxxx suppression note. The example deliberately reads the key three times. SE.Redis admits a reply on its second miss by default (OnRepeatedMiss, a TinyLFU doorkeeper), so the two-read MONITOR demo every other client page uses would show both GETs reaching the server. The overview page's sentence about clients differing exists for the same reason: its "first access hits the server, later ones don't" MONITOR advice and its "HSCAN is never cached" claim are both false for SE.Redis. The page uses the existing IDatabase style (Andy's call), which the cache supports because it sits below the API. The one exception is the WithMaxCacheAge/WithoutCache subsection: those exist only on RespDatabaseContext, so it uses the v4 command-group API and says so. Nothing here was run. NuGet is on the sandbox denylist, so the alpha package could not be restored, and the snippets are unverified. Learned: SE.Redis v4 caches on the second read by default, so CSC demos need three reads or OnFirstMiss Rejected: db.Context.WithMaxCacheAge(...).AsDatabase(muxer) to keep IDatabase style | AsDatabase is documented upstream as a transitional database whose unmigrated commands throw Constraint: the connect example must keep three StringGet calls unless it also sets Admission = CacheAdmission.OnFirstMiss Gaps: no snippet compiled or run; verify against the released 4.x package before merge Recheck: when the first non-alpha 4.x release ships (version note, TODO comment, overview row, option names/defaults) Ticket: DOC-7175 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
andy-stark-redis
added
do not merge yet
parked
Contributor
Contributor
Contributor
🧠 Redis MemoryFound 5 related items from repository history (5 new this commit):
Memory updated at 4060876 |
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
1 participant
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.
Adds client-side caching (CSC) docs for StackExchange.Redis v4, which introduces server-assisted CSC in the
4.0.127-alphapre-release.dotnet/connect.md: new Connect using client-side caching section (after SCH), covering the connection example, tracking modes,CacheOptions/CachePolicytables, bypassing the cache, which commands are cached, consistency, and monitoring.dotnet/produsage.md: checklist item and Client-side caching stub, matching redis-py and Jedis.client-side-caching.md: StackExchange.Redis version-table row, arelatedPagesentry, and one sentence noting that cached commands andMONITORbehavior vary by client.Warning
Do not merge. This documents a pre-release API: StackExchange.Redis 4.0.127-alpha, tracked upstream in draft PR #3262 (
v4→main). Merge only after the first non-prerelease 4.x release, once/unparkhas reconciled the docs.No page-level
bannerTextis used: the section lives on the shared .NET connect page, so the pre-release status is stated in the section's own note instead.Park manifest
Ticket: DOC-7175
Parked at: 2026-10-13
Trigger to pick up: a non-prerelease StackExchange.Redis 4.x tag exists whose history contains the CSC code, checked by ancestry (
gh api repos/StackExchange/StackExchange.Redis/compare/2b05b06bec03f3e4069ea8163f3e5c9491c7dbc4...<tag>returnsbehind_by: 0). PR #3262 merging intomainis the expected route, but the tag is what counts. Alpha, beta, preview and rc tags do not qualify.Labels: parked, do not merge yet
Pinned sources (state observed at park time)
open, draft, mergedfalse, headv4@3cf425d01da6e65161637afb745d622d2dcd1884, basemain, milestone none, updated 2026-10-12T16:07:14Zgh api repos/StackExchange/StackExchange.Redis/pulls/3262 --jq '{state, merged, draft, head_sha: .head.sha, base: .base.ref, milestone: .milestone.title, updated_at}'4.0.127-alpha2b05b06bec03f3e4069ea8163f3e5c9491c7dbc4gh api repos/StackExchange/StackExchange.Redis/releases --jq '.[] | {tag_name, prerelease, published_at}'docs/ClientSideCaching.md(upstream draft the page is based on)cc2c362466aee4a4d352e38ede5458033e6e094d(2026-10-10); same content at the alpha tag and atv4headgh api "repos/StackExchange/StackExchange.Redis/commits?sha=<ref>&path=docs/ClientSideCaching.md&per_page=1" --jq '.[0].sha'src/StackExchange.Redis/Caching/*.cs(public API)v4head is 9 commits ahead and touchesCacheAdmission.cs,CacheOptions.cs,RespClientCache.cs. Eviction changed from sampling the oldest by fill time to a fill-order queue with a second-chance window, andMaxBytesnow evicts whole slabs, oldest first. No public member was renamed.gh api repos/StackExchange/StackExchange.Redis/compare/2b05b06bec03f3e4069ea8163f3e5c9491c7dbc4...<tag> --jq '[.files[].filename | select(test("Caching|CommandFlags|ConfigurationOptions|Contexts/RespDatabaseContext"))]'Observed shape the page assumes
Semantics: MEDIUM. The upstream draft is detailed and matches the alpha source, but it's an alpha branch under active change.
ConfigurationOptions.ClientCachein code only; there's no configuration-string key.CLIENT TRACKINGare required. Without them the connection fails; it doesn't silently do nothing.PerKeycan't be combined withPrefixes; prefixes must not overlap.HSCAN/SSCAN/ZSCANpages, nil replies, andEVAL_RO/EVALSHA_ROon declared keys. Never cached: writes, keyless commands, random reads, time/access reads, transaction reads, fire-and-forget, errors, and replies overMaxPayloadBytes.FLUSHDB/FLUSHALLempties the cache; key expiry is not announced.IDatabasemethods, both sync and async.[Experimental], so there's noSERxxxsuppression note (unlike SCH).Identifiers: LOW. Each is listed with where I saw it at
4.0.127-alpha:ConfigurationOptions.ClientCache(CacheOptions?):ConfigurationOptions.csConfigurationOptions.Protocol/RedisProtocol.Resp3:ConfigurationOptions.csStackExchange.Redis.Caching:Caching/*.csCacheOptions:Enabled(true),TrackingMode(Default→Broadcast),Prefixes(empty),MaxBytes(null/unbounded),MaxEntries(null/unbounded),MaxPayloadBytes(1 MiB),EvictionSampleSize(8),SweepInterval(10 s),DefaultPolicy(CachePolicy.Default),Admission(Default→OnRepeatedMiss):Caching/CacheOptions.csCachePolicy:TimeToLive(1 min),RefreshAfter(zero/off),InvalidationGracePeriod(zero/off):Caching/CachePolicy.csCacheAdmission:Default,OnFirstMiss,OnRepeatedMiss:Caching/CacheAdmission.csCacheTrackingMode:Default,Broadcast,PerKey:Caching/CacheTrackingMode.csCommandFlags.NoClientCache(1 << 19):Enums/CommandFlags.csIDatabase.Context→RespDatabaseContext, withWithMaxCacheAge(TimeSpan)andWithoutCache():Contexts/RespDatabaseContext.cs(public wrappers over internalRespContextmethods)RespDatabaseContext.Strings.GetAsync(key): used in the context example; not checked in the source, taken from the upstream draft anddocs/LegacyApi.mdWithKeyPrefix(): named in the Tracking modes prose; taken from the draft, not checkedRe-check checklist
MONITORclaim (the server sees the first twoStringGetcalls but not the third) still holds at the default admission. If the default changes, change the example and the paragraph together.TODOHTML comment and replace "currently available as the4.0.127-alphapre-release" in the note with the released version.v4.0 (pre-release)to the released version.CacheOptions.csalready changed after the alpha (eviction behavior only, not defaults).MaxBytes("evicts the oldest entries") andEvictionSampleSize("considers … each time it chooses one to remove") against the releasedCacheOptions.cs. This is what changed between the alpha andv4head.WithMaxCacheAge/WithoutCacheare now reachable throughIDatabasedirectly. If they are, convert that subsection to the existingIDatabasestyle. Don't useRespDatabaseContext.AsDatabase(): at the alpha it's documented as a transitional database whose unmigrated commands throw.[Experimental]. If so, add theSERxxxsuppression note, following the SCH section.docs/ClientSideCaching.mdagainstcc2c362466for new limitations, especially cluster, Sentinel and replica behavior, which the draft doesn't cover.client-side-caching.md: Rust is missing from its table andrelatedPages, and its## Referenceheading is indented inside a list item. Out of scope here; mention them rather than fix them in this PR.On unpark, then
Run
/unpark <this PR>. Its Steps 4–5 are the authoritative closing sequence. Thedo not merge yetguard holds until/finalizecompletes./finalizeis deliberately deferred until then, so the episodic commit trailers survive.🤖 Generated with Claude Code
Note
Low Risk
Documentation-only changes with no runtime impact; content targets a pre-release API and is explicitly marked do-not-merge until 4.x GA.
Overview
Adds documentation for StackExchange.Redis v4 client-side caching (CSC), aligned with the other Redis client guides. The PR is parked until a non-prerelease 4.x ships; the connect page calls out the
4.0.127-alphaAPI and RESP3 /CLIENT TRACKINGrequirements.On
dotnet/connect.md, a new Connect using client-side caching section explains enabling CSC viaConfigurationOptions.ClientCacheandRedisProtocol.Resp3, default second-read admission, broadcast vs per-key tracking,CacheOptions/CachePolicy, bypassing withCommandFlags.NoClientCacheand v4 context helpers, cached vs excluded commands, consistency guarantees, and server-side monitoring.The client-side caching overview gains a StackExchange.Redis table row and related link, plus a note that behavior (e.g. caching
HSCANpages, second-read admission) differs by client.dotnet/produsage.mdadds a checklist item and a short recommendation that points to the connect guide.Reviewed by Cursor Bugbot for commit 4060876. Bugbot is set up for automated code reviews on this repo. Configure here.