docs(serializers): scope cache_clear's pre-upgrade claim, pin the hashed legacy key (LAB-6361) by 27Bslash6 · Pull Request #452 · cachekit-io/cachekit-py

27Bslash6 · 2026-10-02T16:29:58Z

Three follow-ups to the v0.20.0 legacy-key work. One README sentence is corrected. A test now pins the hashed legacy key to cachekit 0.19.0's exact bytes. Two stale comments are fixed. No runtime line changes.

Changes

docs/serializers/README.md, the retention warning. It said cache_clear() "reaches only keys this release tracked, never a pre-upgrade one". That is false in two cases. On a function with no parameters, cache_clear() takes the single-key path and deletes the :{ic}s twin. And a twin whose invalidate_cache(args) delete failed is re-tracked in that process's memory, so that process's next no-argument call retries it; a restart or another process does not. The sentence is now scoped to the :{integrity_flag}s twin on "a function that takes parameters", matching the "What still needs a backend flush" paragraph above it, and it states both cases. It also names a second way a parameterized function's twin is reached: on the tenant-scoped Redis backend the key registry is named per function and namespace, not per serializer, so a key a v0.20.0 default-serializer decorator registered is drained by an "auto" decorator's cache_clear(). The zero-parameter guarantee is the sync one: on an async function with a backend cache_clear() raises TypeError, and await fn.ainvalidate_cache() deletes both keys. I checked the zero-parameter case by hand: seed :1a and :1s, call cache_clear(), and the backend is empty. The retry case is already covered by test_failed_legacy_delete_is_retried_by_no_args_invalidation.

tests/unit/test_key_serializer_suffix.py, new class TestHashedLegacyKeyMatchesV019. _pre_020_key derives the legacy key by swapping the current key's suffix. A raw key over 250 characters is stored as a prefix plus a hash of the whole key, so it has no suffix to swap. As a result, a get_legacy_cache_key rewritten as a suffix swap passed every existing test. The new sync and async tests use a 300-character namespace and serializer="auto". They fix the function's __module__ and __qualname__ so the key does not depend on how pytest imports the file. Each test seeds the backend with a hard-coded key that cachekit 0.19.0 wrote, then asserts that invalidate_cache(1) / ainvalidate_cache(1) deletes it. The default serializer cannot exercise this: on it the legacy key equals the current key and no twin is computed. Both tests disable L1, because they share one pinned key and the second would otherwise hit the first test's process-wide L1 entry.

src/cachekit/decorators/wrapper.py, _resolve_cache_key comments. "Interop mode takes priority" sat below the generated-key branch, which runs first. The comment now says that decoration rejects interop together with key= or fast_mode. The final fast_mode return is commented as the only mode _generated_key_mode leaves. This is a comment-only change: ast.dump(ast.parse(...)) of the file is identical before and after.

Re-deriving the 0.19.0 literal

From a directory outside the repo, using the PyPI 0.19.0 wheel:

cat > derive.py <<'PY'
from cachekit import cache
from cachekit.key_generator import CacheKeyGenerator

NS = "lab6361_" + "n" * 292

class B:
    def __init__(self): self.store = {}
    def get(self, k): return self.store.get(k)
    def set(self, k, v, ttl=None): self.store[k] = v
    def delete(self, k): return self.store.pop(k, None) is not None
    def exists(self, k): return k in self.store
    def health_check(self): return True, {}

def fn(x):
    return {"v": x}
fn.__module__ = "lab6361"
fn.__qualname__ = "fn"

print("generate_key:", CacheKeyGenerator().generate_key(fn, (1,), {}, NS, True))
b = B()
cache(backend=b, ttl=None, namespace=NS, serializer="auto")(fn)(1)
print("decorator wrote:", list(b.store))
PY
uv run --no-project --isolated --with cachekit==0.19.0 python derive.py

generate_key: ns:lab6361_nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn:8c42af11facf9cd7e05b02ead5c9bdfc
decorator wrote: ['ns:lab6361_nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn:8c42af11facf9cd7e05b02ead5c9bdfc']

0.19.0's generate_key and its decorator write path agree. At this head, get_legacy_cache_key returns the same string, and the current key is …:bcc66513af19ec921928b20ad2f12a40.

Mutation run

I rewrote get_legacy_cache_key as the suffix swap the test exists to catch, then restored it:

current = self.get_cache_key(func, args, kwargs, namespace, integrity_checking)
head, suffix = current.rsplit(":", 1)
return f"{head}:{suffix[0]}s"

$ uv run pytest tests/unit/test_key_serializer_suffix.py -q -p no:randomly
E       AssertionError: the key 0.19.0 wrote survived invalidation
E       AssertionError: the key 0.19.0 wrote survived invalidation
FAILED tests/unit/test_key_serializer_suffix.py::TestHashedLegacyKeyMatchesV019::test_sync_invalidate_deletes_the_v019_hashed_key
FAILED tests/unit/test_key_serializer_suffix.py::TestHashedLegacyKeyMatchesV019::test_async_invalidate_deletes_the_v019_hashed_key
========================= 2 failed, 30 passed in 0.69s =========================

Only the two new tests fail. The 30 existing ones pass under the mutation, which is exactly the gap this closes.

Verification

uv run ruff check src/ tests/: all checks passed
uv run ruff format --check src/ tests/: 309 files already formatted
uv run pytest tests/unit tests/critical -m "not slow": 4049 passed, 25 skipped
uv run pytest --markdown-docs README.md docs/: 130 passed

Closes LAB-6361

…hed legacy key (LAB-6361) The retention warning said cache_clear() never reaches a pre-upgrade key. That is false on a zero-parameter function, where it takes the single-key path and deletes the twin, and for a twin whose delete failed, which stays tracked and is retried. No test pinned the legacy key for raw keys over 250 characters: _pre_020_key swaps the current key's suffix, which a hashed key does not have. The new sync and async tests seed the literal key cachekit 0.19.0 wrote and fail if get_legacy_cache_key ever derives it some other way. The _resolve_cache_key comments now describe the branch order the code runs. Comment-only change; the module's AST is unchanged.

coderabbitai · 2026-10-02T16:30:08Z

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 59 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository: cachekit-io/cachekit-py/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 364cf758-bdf4-413e-a9b9-0a5f34b98600

📥 Commits

Reviewing files that changed from the base of the PR and between b9ad394 and 92603ba.

📒 Files selected for processing (3)

docs/serializers/README.md
src/cachekit/decorators/wrapper.py
tests/unit/test_key_serializer_suffix.py

Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

kodus-27b · 2026-10-02T16:30:16Z

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration

Interacting with Kody

Request a Review: Ask Kody to review your PR manually by adding a comment with the `@kody start-review` command at the root of your PR.
Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Providing Context (Files & MCPs)

Add these hints in your PR description (or a comment) to unlock deeper checks:

Ticket / Acceptance Criteria: `Refs: ABC-123` (Linear/Jira/Asana/ClickUp/Trello) or a direct ticket link.
Bugfix Validation: a Sentry/Datadog/Bugsnag event link (or paste the stack trace/error message).
Endpoint Risk: mention the route (e.g., `POST /api/payments`) or controller/action name.
Attach a repo file as context: use an explicit marker like `@file:docs/guide.mdx#L10-L50` (replace with your real path).
API Contract Docs: include `@file:openapi.yaml` or `@file:swagger.json` when changing routes/schemas.
Definition of Done / Standards: include `@file:DOD.md` or `@file:CONTRIBUTING.md` if your repo has them.
Design System Source of Truth: include `@file:ui/index.ts` (replace with your DS entrypoint path).
Feature Flags: include the flag key/name and `@file:flags.ts` / `@file:config.json` (and optionally the PostHog flag name).
Edge/CDN Rules: link the Cloudflare rule/zone or describe the intended redirect/header behavior.
Attach an MCP tool output: use `@mcp<provider|tool>` (replace with an installed MCP provider + tool, e.g., `@mcp<sentry|events.search>`).

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

Kody Code Review — 1 suggested fix.
Paste the prompt below to your agent and all review fixed at once!

🛠️ Open Agent Prompt

A code review identified the following issues in this pull request.
Each section describes what was found and includes a reference implementation where available.

Files involved:
- tests/unit/test_key_serializer_suffix.py:511

---

### [1/1] tests/unit/test_key_serializer_suffix.py:511
Issue identified during code review:
Type erasure in `_pin_identity`: the decorator is annotated `Any -> Any` even though it returns the same object it receives, so it discards the decorated function's type. Every function wrapped by `_pin_identity` loses its signature, and type checkers stop flagging calls with wrong arguments or misuse of the return value. Fix: declare `F = TypeVar("F", bound=Callable[..., Any])` and annotate as `def _pin_identity(fn: F) -> F:`.

---

Review each issue in context, use the reference implementations as guidance, and apply fixes that are consistent with the surrounding codebase.

codecov · 2026-10-02T16:34:30Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

The re-track after a failed twin delete lives in process memory only, so a restart or another process's no-argument call does not retry it. Scope the exception to the `:{integrity_flag}s` twin rather than to every tracked key, which on the default serializer includes the pre-upgrade key itself, and state the zero-parameter case as a fact rather than an aside. The hashed-key tests drop the call counter and recompute: with L1 off, an empty store already proves the next call misses.

kodus-27b · 2026-10-02T16:43:24Z

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration

Interacting with Kody

Request a Review: Ask Kody to review your PR manually by adding a comment with the `@kody start-review` command at the root of your PR.
Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Providing Context (Files & MCPs)

Add these hints in your PR description (or a comment) to unlock deeper checks:

Ticket / Acceptance Criteria: `Refs: ABC-123` (Linear/Jira/Asana/ClickUp/Trello) or a direct ticket link.
Bugfix Validation: a Sentry/Datadog/Bugsnag event link (or paste the stack trace/error message).
Endpoint Risk: mention the route (e.g., `POST /api/payments`) or controller/action name.
Attach a repo file as context: use an explicit marker like `@file:docs/guide.mdx#L10-L50` (replace with your real path).
API Contract Docs: include `@file:openapi.yaml` or `@file:swagger.json` when changing routes/schemas.
Definition of Done / Standards: include `@file:DOD.md` or `@file:CONTRIBUTING.md` if your repo has them.
Design System Source of Truth: include `@file:ui/index.ts` (replace with your DS entrypoint path).
Feature Flags: include the flag key/name and `@file:flags.ts` / `@file:config.json` (and optionally the PostHog flag name).
Edge/CDN Rules: link the Cloudflare rule/zone or describe the intended redirect/header behavior.
Attach an MCP tool output: use `@mcp<provider|tool>` (replace with an installed MCP provider + tool, e.g., `@mcp<sentry|events.search>`).

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

On the tenant-scoped Redis backend the key registry is named per function and namespace, not per serializer, so a default-serializer decorator's registered key is drained by an `"auto"` decorator's cache_clear() too: a second way a parameterized function's pre-upgrade twin is reached. And on an async function with a backend cache_clear() raises TypeError, so the zero-parameter guarantee is the sync one; `await fn.ainvalidate_cache()` is the async equivalent.

kodus-27b · 2026-10-02T16:51:24Z

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration

Interacting with Kody

Request a Review: Ask Kody to review your PR manually by adding a comment with the `@kody start-review` command at the root of your PR.
Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Providing Context (Files & MCPs)

Add these hints in your PR description (or a comment) to unlock deeper checks:

Ticket / Acceptance Criteria: `Refs: ABC-123` (Linear/Jira/Asana/ClickUp/Trello) or a direct ticket link.
Bugfix Validation: a Sentry/Datadog/Bugsnag event link (or paste the stack trace/error message).
Endpoint Risk: mention the route (e.g., `POST /api/payments`) or controller/action name.
Attach a repo file as context: use an explicit marker like `@file:docs/guide.mdx#L10-L50` (replace with your real path).
API Contract Docs: include `@file:openapi.yaml` or `@file:swagger.json` when changing routes/schemas.
Definition of Done / Standards: include `@file:DOD.md` or `@file:CONTRIBUTING.md` if your repo has them.
Design System Source of Truth: include `@file:ui/index.ts` (replace with your DS entrypoint path).
Feature Flags: include the flag key/name and `@file:flags.ts` / `@file:config.json` (and optionally the PostHog flag name).
Edge/CDN Rules: link the Cloudflare rule/zone or describe the intended redirect/header behavior.
Attach an MCP tool output: use `@mcp<provider|tool>` (replace with an installed MCP provider + tool, e.g., `@mcp<sentry|events.search>`).

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

_pin_identity returns the function it is given, but its Any -> Any annotation typed every decorated test function as Any, so a bad call or a misused return went unflagged. A Callable-bound TypeVar passes the signature through.

27Bslash6 · 2026-10-02T17:05:44Z

@kody start-review

kodus-27b · 2026-10-02T17:06:27Z

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration

Interacting with Kody

Request a Review: Ask Kody to review your PR manually by adding a comment with the `@kody start-review` command at the root of your PR.
Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Providing Context (Files & MCPs)

Add these hints in your PR description (or a comment) to unlock deeper checks:

Ticket / Acceptance Criteria: `Refs: ABC-123` (Linear/Jira/Asana/ClickUp/Trello) or a direct ticket link.
Bugfix Validation: a Sentry/Datadog/Bugsnag event link (or paste the stack trace/error message).
Endpoint Risk: mention the route (e.g., `POST /api/payments`) or controller/action name.
Attach a repo file as context: use an explicit marker like `@file:docs/guide.mdx#L10-L50` (replace with your real path).
API Contract Docs: include `@file:openapi.yaml` or `@file:swagger.json` when changing routes/schemas.
Definition of Done / Standards: include `@file:DOD.md` or `@file:CONTRIBUTING.md` if your repo has them.
Design System Source of Truth: include `@file:ui/index.ts` (replace with your DS entrypoint path).
Feature Flags: include the flag key/name and `@file:flags.ts` / `@file:config.json` (and optionally the PostHog flag name).
Edge/CDN Rules: link the Cloudflare rule/zone or describe the intended redirect/header behavior.
Attach an MCP tool output: use `@mcp<provider|tool>` (replace with an installed MCP provider + tool, e.g., `@mcp<sentry|events.search>`).

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

kodus-27b Bot reviewed Oct 2, 2026

View reviewed changes

Comment thread tests/unit/test_key_serializer_suffix.py Outdated

kodus-27b Bot previously approved these changes Oct 2, 2026

View reviewed changes

27Bslash6 dismissed kodus-27b[bot]’s stale review via 288ddcc October 2, 2026 16:49

kodus-27b Bot previously approved these changes Oct 2, 2026

View reviewed changes

27Bslash6 dismissed kodus-27b[bot]’s stale review via cbba40c October 2, 2026 17:05

kodus-27b Bot approved these changes Oct 2, 2026

View reviewed changes

Merge branch 'main' into lab-6361-legacy-key-followups

92603ba

27Bslash6 merged commit 8f7c773 into main Oct 2, 2026
36 checks passed

27Bslash6 deleted the lab-6361-legacy-key-followups branch October 2, 2026 18:56

Navigation Menu

Repository navigation

docs(serializers): scope cache_clear's pre-upgrade claim, pin the hashed legacy key (LAB-6361) - #452

docs(serializers): scope cache_clear's pre-upgrade claim, pin the hashed legacy key (LAB-6361)#452
27Bslash6 merged 5 commits into
mainfrom
lab-6361-legacy-key-followups

27Bslash6 commented Oct 2, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Oct 2, 2026 •

edited

Loading

Review limit reached

Uh oh!

kodus-27b Bot commented Oct 2, 2026 •

edited

Loading

Uh oh!

Uh oh!

codecov Bot commented Oct 2, 2026

Uh oh!

kodus-27b Bot commented Oct 2, 2026

Uh oh!

kodus-27b Bot commented Oct 2, 2026

Uh oh!

27Bslash6 commented Oct 2, 2026

Uh oh!

kodus-27b Bot commented Oct 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

27Bslash6 commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Re-deriving the 0.19.0 literal

Mutation run

Verification

Uh oh!

coderabbitai Bot commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Uh oh!

kodus-27b Bot commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review Completed! 🔥

Uh oh!

Uh oh!

codecov Bot commented Oct 2, 2026

Codecov Report

Uh oh!

kodus-27b Bot commented Oct 2, 2026

Code Review Completed! 🔥

Uh oh!

kodus-27b Bot commented Oct 2, 2026

Code Review Completed! 🔥

Uh oh!

27Bslash6 commented Oct 2, 2026

Uh oh!

kodus-27b Bot commented Oct 2, 2026

Code Review Completed! 🔥

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

27Bslash6 commented Oct 2, 2026 •

edited

Loading

coderabbitai Bot commented Oct 2, 2026 •

edited

Loading

kodus-27b Bot commented Oct 2, 2026 •

edited

Loading