refactor(cache)!: add CacheKey as the one encoder and parser of HTTP keys - #405
Merged
Merged
Conversation
…keys The key format was built in build_cache_key but parsed separately in the monitoring routes, memory clear_path and the Redis clear_path glob. Add a public frozen CacheKey (from_request, to_str, parse, path_glob) and route all of them through it. The stored format does not change: the upcoming 0.4.0 key changes (#271, #266, #265, #269, #72) then touch one module. The method is now percent-encoded like host and path, so a method token containing "|" cannot shift the components; real methods are unchanged. BREAKING CHANGE: CACHE_KEY_MIN_PARTS, CACHE_KEY_MAX_SPLIT and CACHE_KEY_MAX_PARTS are removed from fastapi_cachex.routes; use CacheKey.parse(key). Closes #270
This was referenced Sep 29, 2026
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
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.
Closes #270. This is step 1 of the 0.4.0 cache-key work (#271, #266, #265, #269, #72 follow).
What changes
CacheKey(fastapi_cachex.CacheKey, modulefastapi_cachex/cache_key.py), a frozen dataclass with:from_request(request, *components, sort_query=...): the key@cachestores a request under;to_str(): the single encoder;parse(key): the single decoder. It returnsNonefor keys that are not HTTP keys;path_glob(path): the Redis glob for "every key with this path".build_cache_key()is nowCacheKey.from_request(...).to_str(). The monitoring routes,MemoryBackend.clear_pathandAsyncRedisCacheBackend.clear_pathuseCacheKey.parse/path_globinstead of splitting keys themselves.CACHE_KEY_MIN_PARTS,CACHE_KEY_MAX_SPLITandCACHE_KEY_MAX_PARTSfromfastapi_cachex.routes(maintainer decision: remove outright in 0.4.0).The stored format does not change
Keys stay
method|||host|||path|||query|||extra...andsort_querystill defaults toFalse. A golden-string test pins the format, so the follow-up PRs change it on purpose. There are three small deltas:|. Without the encoding,build_cache_key()/invalidate()on such a request would produce an unparseable key, and with the new validation would raise. Real methods (GET, ...) are unaffected.CacheKey.querymay not contain the separator (ValueError). A query taken from a request never does, because Starlette encodes|.clear_pathcompares the decoded path rather than the escaped one, and no longer treats a key with an empty method as an HTTP key. This makes no difference for keys written bybuild_cache_key. Only hand-written, non-canonically escaped keys could behave differently.Tests and docs
tests/test_cache_key_type.py: round trips, non-HTTP keys, escaping, validation,path_glob, the pinned format. Each assertion was checked by breaking the code it guards.routes._parse_cache_key/_split_cache_keynow useCacheKey.parse.HTTP_CACHING.md(newCacheKeyparagraph),MIGRATING_0_4.md, API reference, and the zh-TW counterparts.changelog.d/270.added.md,changelog.d/270.removed.md.Checks: pre-commit,
mypy tests,mypy scripts, both strict docs builds, and the full suite with live Redis and Memcached (99.82% coverage).