Fence document cache fills

[ChiragAgg5k]

What

Uses the fenced cache lease API from utopia-php/cache to guard document cache fills in Database::getDocument().

Depends on: utopia-php/cache#74

Why

A cache-miss read can race with a concurrent writer purge: the reader fetches an older DB row, the writer commits and purges, then the reader saves the older document back into cache. The database layer then serves that poisoned document to whole-document read-modify-write callers, which can permanently overwrite fields with stale values.

Changes

• Acquire a cache lease before backend document reads for plain cacheable getDocument() calls.
• Save document cache entries through saveLease() so a purge between read and save makes the fill a no-op.
• Keep collection membership updates only when the fenced document save succeeds.
• Point utopia-php/cache at dev-cache-lease-fence from the cache PR branch and update the lockfile.

Validation

• php -l src/Database/Database.php
• composer validate --strict --no-check-publish
• php -d memory_limit=2G vendor/bin/pint --test composer.json src/Database/Database.php tests/unit/ForUpdateCacheTest.php
• vendor/bin/phpunit --configuration phpunit.xml tests/unit/ForUpdateCacheTest.php
• vendor/bin/phpstan analyse --level 7 src/Database/Database.php --memory-limit 2G

Note: Composer update required --ignore-platform-req=ext-pcov locally because ext-pcov is not installed in this environment.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b58514ce-0e5c-40c3-9cef-fc9335cbdef4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch database-cache-lease-fence

---

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 and usage tips.}

[ChiragAgg5k]

Closing this draft because the fix now lives in utopia-php/cache as hidden cache fencing; this database branch only updates the dev dependency and no longer carries a meaningful library change.