Skip to content

docs: distributed-locking.md wrongly says HTTP backends skip locking; omits sync/async split #238

Description

@27Bslash6

docs/features/distributed-locking.md makes two claims that don't match the code (checked at v0.14.0):

  1. "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.io has no stampede protection; it does, on the async path.

  2. 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).

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions