Expand description
PageLock — best-effort editor lock on a cms_page row.
Two editors opening the same page in a page-tree CMS expect a “Page X is being edited by Y” banner instead of a silent last-write-wins clobber. This module is the foundational lock primitive; multi-step workflows, inline comments, and editing-session tracking (B11) all sit on top of it.
§Semantics
- One lock row per page (UNIQUE on
page_id). - Lock is advisory: acquired on edit-form open, refreshed by the
editor’s heartbeat ping, released on a successful POST. A stale
lock (no heartbeat past
expires_at) is treated as released — the next editor reuses the row in place. - Force-unlock is allowed for anyone with the page’s Edit permission; it deletes the row and is audit-logged.
Why best-effort + TTL instead of a hard SQL lock: editors close browser tabs all the time; we can’t tell the difference between “closed the tab” and “still editing.” A 30-minute sliding TTL gives the owner room to be away from keyboard without permanently jamming the page for everyone else.
§Lock kinds
This is the basic editor lock. Workflow-driven locks
(WorkflowLock, ScheduledForPublishLock) ship with workflows.
See src/admin/handlers.rs::page_edit_form for the acquire site
and src/admin/handlers.rs::page_edit_submit for the release site.
Structs§
Enums§
- Acquire
Outcome - Outcome of an acquire attempt.
Acquiredmeans we now hold the lock (new row, or refreshed our own row).Heldmeans someone else holds an unexpired lock; the caller should render the read-only banner.Stolenis the result whenforce=true— previous holder’s row was deleted and we own the new one.
Constants§
- DEFAULT_
TTL_ SECS - How long a lock survives without a heartbeat refresh. Tune via
RUSTANGO_CMS_LOCK_TTL_SECSif shorter sessions are needed. - HEARTBEAT_
INTERVAL_ SECS - Heartbeat cadence the editor JS uses to refresh the lock. Set
well under
DEFAULT_TTL_SECS / 2so a missed ping doesn’t drop the lock mid-session.
Functions§
- acquire
- Best-effort acquire: returns
Acquiredif the page is free or already owned byuser_id, elseHeldwith the other user’s row. Refreshesexpires_aton every call when we own the lock. - current
- Look up the current lock on a page without mutating it. Returns
Noneif no row exists OR the row is stale. The adminpage_edit_formcalls this before deciding whether to render the banner. - force_
release - Force-release a lock regardless of ownership. Used by the
POST /cms-admin/pages/{id}/unlockadmin handler. Returns the row that was deleted (so the caller can audit-log who held it), orNoneif the row was already gone. - release
- Release a lock owned by
user_id. No-op if the row is missing, stale, or owned by someone else (the caller’s session ended; we shouldn’t silently unlock another user’s edit).