Skip to content

feat(cache)!: tag HTTP cache keys http:v2 and separate them with one | - #406

Merged
allen0099 merged 1 commit into
masterfrom
feat/271-266-key-separator-tag
Sep 29, 2026
Merged

allen0099 merged 1 commit into
masterfrom
feat/271-266-key-separator-tag

Conversation

@allen0099

Copy link
Copy Markdown
Owner

Second of the 0.4.0 cache-key changes, on top of CacheKey (#405).

What changes

  • CACHE_KEY_SEPARATOR is "|". Method, host, path and extra components are percent-encoded and the query is URL-encoded, so none of them can contain it (0.4.0: use a single | as the cache-key separator #271).
  • Every HTTP key starts with the format tag http:v2 (CacheKey.FORMAT_TAG): http:v2|method|host|path|query|extra.... A later format gets another tag, and clear_pattern("http:v2|*") removes every key of this one (Cache key: add a format version tag to HTTP keys #266).
  • CacheKey.parse() returns None for untagged keys. clear_path() and the monitoring routes therefore skip 0.3.x keys and keys from a key_builder that builds its own string instead of calling build_cache_key(). Such builders still cache, invalidate() and clear_pattern(); the docs say so.
  • CacheKey.path_glob() includes the tag.
  • The path-shaped clear_pattern warning now suggests http:v2|GET|*|<pattern>|*, which also matches a path with no glob.

Docs

  • CACHE_FLOW.md, HTTP_CACHING.md and MIGRATING_0_4.md, in English and zh-TW:
    • new format and examples;
    • the untagged custom key note;
    • "exact tag not final" removed;
    • the Redis clear_pattern example is now "http:v2|GET|*";
    • a caution that the *|||* cleanup pattern matches any key containing |||.
  • changelog.d/125.removed.md now gives the 0.4.0 pattern.

Tests

  • Key literals across the suite are moved to the new format.
  • New cases for parse() rejecting 0.3.x, other-tag, untagged, query-less and method-less keys.
  • path_glob matches only tagged keys.
  • The pattern the warning suggests actually clears the entries.
  • clear_pattern("*|||*") removes 0.3.x keys and leaves current ones.

Closes #271
Closes #266

Every client-controlled component is percent-encoded, so a single `|` is
enough to separate them. Keys now start with the format tag `http:v2`
(`CacheKey.FORMAT_TAG`), so a later format never collides with this one
and `clear_pattern("http:v2|*")` removes every key of it.

`CacheKey.parse()` only reads tagged keys, so `clear_path()` and the
monitoring routes skip 0.3.x keys and keys from a key builder that does
not use `build_cache_key()`. The path-shaped `clear_pattern` warning now
suggests a pattern that also matches a path with no glob.

BREAKING CHANGE: HTTP cache keys change from `method|||host|||path|||query`
to `http:v2|method|host|path|query`, and `CACHE_KEY_SEPARATOR` is `"|"`.
Entries written by 0.3.x are not read.

Closes #271
Closes #266
@allen0099 allen0099 added this to the 0.4.0 milestone Sep 29, 2026
@allen0099 allen0099 added enhancement New feature or request http-cache The @cache decorator, cache keys and Cache-Control handling breaking-change Changes public behaviour or API; needs a minor/major release labels Sep 29, 2026
@allen0099
allen0099 merged commit 0796987 into master Sep 29, 2026
15 checks passed
@allen0099
allen0099 deleted the feat/271-266-key-separator-tag branch September 29, 2026 16:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking-change Changes public behaviour or API; needs a minor/major release enhancement New feature or request http-cache The @cache decorator, cache keys and Cache-Control handling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0.4.0: use a single | as the cache-key separator Cache key: add a format version tag to HTTP keys

1 participant