You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The page never mentions the sync/async split. The distributed miss-path lock is only wired into async_wrapper (decorators/wrapper.py:1704). sync_wrapper deliberately skips it — its own comment: "Sync wrappers don't support distributed locking (backend protocol is async-only). For thundering herd protection, use async decorators instead" (wrapper.py:1327-1329). The docs' TL;DR ("only one pod calls the function; others wait") is silently untrue for every sync decorated function, and the Troubleshooting answer ("Verify your backend implements LockableBackend") sends sync users down the wrong path entirely.
Real-world cost: this page was cited in an incident discussion (internal LAB-605, a hard-miss stampede that OOM'd a Cloud Run instance) and produced a wrong root-cause claim — "the .io backend doesn't implement locking" — when the actual gap was sync-wrapper coverage.
Suggested fix: correct the backend list in the note (CachekitIO implements locking; FileBackend/Memcached do not), and add a prominent "Sync vs async" section stating the miss-path lock is async-only, with the sync fallback behavior (no lock, per-process SWR single-flight only).
docs/features/distributed-locking.mdmakes two claims that don't match the code (checked at v0.14.0):"Backends that don't support locking (HTTP, FileBackend) silently skip lock acquisition" — wrong for the CachekitIO backend: it has implemented
acquire_lock(LockableBackend protocol,POST /v1/cache/{key}/lock) since the backend was introduced (feat: add CachekitIO SaaS backend with SSRF protection #60), conformed in fix: conform CachekitIOBackend.acquire_lock to LockableBackend protocol #130. Readers of this page conclude@cache.iohas no stampede protection; it does, on the async path.The page never mentions the sync/async split. The distributed miss-path lock is only wired into
async_wrapper(decorators/wrapper.py:1704).sync_wrapperdeliberately skips it — its own comment: "Sync wrappers don't support distributed locking (backend protocol is async-only). For thundering herd protection, use async decorators instead" (wrapper.py:1327-1329). The docs' TL;DR ("only one pod calls the function; others wait") is silently untrue for every sync decorated function, and the Troubleshooting answer ("Verify your backend implements LockableBackend") sends sync users down the wrong path entirely.Real-world cost: this page was cited in an incident discussion (internal LAB-605, a hard-miss stampede that OOM'd a Cloud Run instance) and produced a wrong root-cause claim — "the .io backend doesn't implement locking" — when the actual gap was sync-wrapper coverage.
Suggested fix: correct the backend list in the note (CachekitIO implements locking; FileBackend/Memcached do not), and add a prominent "Sync vs async" section stating the miss-path lock is async-only, with the sync fallback behavior (no lock, per-process SWR single-flight only).