perf: skip unused variant hashes when purging cached documents

[loks0n]

Document purges currently compute a selection/filter variant hash and immediately discard it. Extract getCacheBaseKeys() for the collection/document keys and call it directly from purgeCachedDocumentInternal(), skipping filter-signature assembly, sorting, JSON encoding and MD5 on every document invalidation.

getCacheKeys() keeps its existing signature and three-key result, using getCacheBaseKeys() before computing the variant hash. Purges retain the hostname/namespace/tenant/global-collection key logic and both cache purge calls, including invalidation of every document variant and its cache leases.

Validation:

• 464 unit tests, 2,387 assertions pass on PHP 8.5.9 / PHPUnit 9.6.34, using a local bootstrap pointing at this checkout and installed Cloud cache/pools/telemetry dependencies.
• New tests cover scoped keys without hashes, fresh reads after public document purges, removal of legacy and variant cache entries, and rejection of stale leased writes. The new key test fails on the baseline; deliberately disabling document invalidation makes the outcome tests fail on stale data and leftover cache entries.
• Targeted Pint and git diff --check pass.
• Seven alternating rounds of 100,000 public purgeCachedDocument() calls against Memory/None adapters: median 301.90 ms before, 72.60 ms after (76.0% reduction). This measures PHP overhead only, not Redis latency or end-to-end production CPU savings.

Motivation: fresh Cloud 1.50.6 samples showed cache-key generation in 6.5–9.0% of non-scheduler samples across API, database and usage workers. These are wall-stack samples, not on-CPU attribution; only the purge subset benefits here. No production changes or Redis-backed E2E drill were performed for this PR; lease coverage uses the existing generation-aware in-memory cache adapter.

Summary by CodeRabbit

• Bug Fixes

  • Improved cache invalidation so purging a document removes all relevant cached versions.
  • Subsequent reads now return fresh data after a cached document is purged.
  • Prevented outdated writes from restoring stale data after cache invalidation.
  • Improved consistency for cached data across different selections and configuration settings.

• Tests

  • Added coverage for cache key consistency, document purging, fresh reads, and stale-write prevention.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 06186748-9c02-446d-9e6d-3ba9b9b3fa0c

📥 Commits

Reviewing files that changed from the base of the PR and between debef42 and 210498a.

📒 Files selected for processing (4)

• src/Database/Database.php
• tests/unit/CacheKeyTest.php
• tests/unit/ForUpdateCacheTest.php
• tests/unit/WithCacheLeaseTest.php

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The cache-key API now separates base keys from selection-aware hashes. Document purging uses base keys to invalidate cached variants. Tests cover scoped key consistency, fresh reads after purge, variant removal, and stale lease rejection.

Changes

Cache purge key handling

Layer / File(s)	Summary
Base and selection-aware cache keys src/Database/Database.php, tests/unit/CacheKeyTest.php	Adds getCacheBaseKeys() and makes getCacheKeys() build selection-aware hashes from the base keys. Tests verify consistent scoped key components for regular and metadata collections.
Document purge validation src/Database/Database.php, tests/unit/ForUpdateCacheTest.php, tests/unit/WithCacheLeaseTest.php	Document purging uses base keys. Tests verify fresh reads, removal of cache variants, and rejection of stale lease writes.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 21049

Document cache purges now avoid unnecessary selection-hash work while retaining scoped key behavior and invalidating cached variants. No concrete current-head merge risk remains.

Suggested reviewers: abnegate

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 12 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main performance optimization: avoiding unused variant-hash computation during cached document purges.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/skip-purge-cache-hashes

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[greptile-apps]

Greptile Summary

This PR avoids computing an unused document-variant hash during cache invalidation while preserving the existing cache-key scope and purge operations.

• Extracts collection and document keys into getCacheBaseKeys().
• Keeps getCacheKeys() compatible and continues deriving variant keys from the same base keys.
• Adds coverage for scoped key equivalence, fresh reads after purging, complete variant removal, and stale lease rejection.

Confidence Score: 5/5

The PR appears safe to merge because it preserves cache-key construction and invalidation behavior while removing only unused computation.

Document reads and purges continue to share identical collection and document base keys, and the existing two purge operations and their arguments are unchanged; no concrete regression remains.

Important Files Changed

Filename	Overview
src/Database/Database.php	Extracts base cache-key generation and uses it to avoid unnecessary variant-hash computation during document purges.
tests/unit/CacheKeyTest.php	Verifies that scoped base keys exactly match the collection and document portions of variant keys.
tests/unit/ForUpdateCacheTest.php	Confirms that a public document purge makes the next read return authoritative fresh data.
tests/unit/WithCacheLeaseTest.php	Confirms that purging removes legacy and selected-field variants and rejects stale leased writes.

_{Reviews (1): Last reviewed commit: "refactor: separate base cache keys from ..." | Re-trigger Greptile}