Skip to main content

Module lock

Module lock 

Source
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§

PageLock

Enums§

AcquireOutcome
Outcome of an acquire attempt. Acquired means we now hold the lock (new row, or refreshed our own row). Held means someone else holds an unexpired lock; the caller should render the read-only banner. Stolen is the result when force=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_SECS if shorter sessions are needed.
HEARTBEAT_INTERVAL_SECS
Heartbeat cadence the editor JS uses to refresh the lock. Set well under DEFAULT_TTL_SECS / 2 so a missed ping doesn’t drop the lock mid-session.

Functions§

acquire
Best-effort acquire: returns Acquired if the page is free or already owned by user_id, else Held with the other user’s row. Refreshes expires_at on every call when we own the lock.
current
Look up the current lock on a page without mutating it. Returns None if no row exists OR the row is stale. The admin page_edit_form calls 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}/unlock admin handler. Returns the row that was deleted (so the caller can audit-log who held it), or None if 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).