Table locking

Table locks enforce exclusive access at the table level. Before a terminal can open or edit a table’s order, it must hold the lock for that table. Table locks operate independently from order leases. A lease governs write access to a specific order (snapshot level); a table lock governs who may navigate to a table at all (floor plan level). In practice, a terminal acquires the table lock first (on the floor plan), then acquires the order lease when editing.

How it works

Acquiring a lock

Terminal taps a table on the floor plan
Frontend sends TABLE_LOCK_ACQUIRE { tableId } via WebSocket
Hub checks if the table is already locked:
- Not locked — Grant. Returns TABLE_LOCK_GRANTED { tableId }
- Locked by same terminal — Grant (re-entrant, extends TTL)
- Locked by another terminal — Deny. Returns TABLE_LOCK_DENIED { tableId, lockedBy }
- Locked but expired — Clean up expired lock, then grant
On grant, hub broadcasts TABLE_LOCKS_STATE to all other terminals

Maintaining a lock

Locks expire after 45 seconds (TABLE_LOCK_TTL_MS) without renewal
Terminals send TABLE_LOCK_HEARTBEAT every 15 seconds
Each heartbeat resets the expiry to now + 45s
If a terminal crashes or loses connection, the lock auto-expires after the grace period

Releasing a lock

Terminal sends TABLE_LOCK_RELEASE { tableId } when navigating away
Hub broadcasts TABLE_LOCK_RELEASED { tableId } to all terminals
The TableLockGuard component releases the lock automatically on unmount

Lock expiry (tick)

The hub runs a periodic tick every 15 seconds (matching the heartbeat interval):

Query all locks where expires_at <= now
For each expired lock:
- Send TABLE_LOCK_REVOKED { tableId, reason: "Lock expired" } to the holding terminal
- Delete the lock from storage

Disconnect grace period

When a terminal’s WebSocket disconnects:

Hub shortens lock expiry to now + 10s (grace period)
If the terminal reconnects within 10 seconds, it can re-acquire
If grace period expires, the normal tick process revokes the lock

  Terminal                              Hub
     │                                   │
     ├──── WS Disconnect ───────────────►│  (unexpected close)
     │                                   │
     │                                   │  lock.expires_at = now + 10s
     │                                   │
     │      (reconnects within 10s)      │
     ├──── WS Connect ──────────────────►│
     │◄─── AUTH_OK ──────────────────────┤
     │◄─── TABLE_LOCKS_STATE ────────────┤  (current lock state)
     │                                   │
     │      (TableLockGuard re-acquires) │
     ├──── TABLE_LOCK_ACQUIRE { id } ───►│
     │◄─── TABLE_LOCK_GRANTED { id } ────┤  resume editing

Manager override (force acquire)

Managers can forcibly take over a table locked by another terminal:

Request

Manager terminal sends TABLE_LOCK_FORCE_ACQUIRE { tableId }

Validate

Hub validates that the requesting terminal has manager or group_pos_manager role (server-side check)

Revoke current holder

Hub sends TABLE_LOCK_REVOKED { tableId, reason: "Manager override" } to the current holder

Grant to manager

Manager receives TABLE_LOCK_GRANTED { tableId }. Hub broadcasts updated TABLE_LOCKS_STATE

The handler is the single authority for revoke notifications during force-acquire. The onRevoke callback is only for async events (TTL tick expiry) — never both, to prevent duplicate notifications.

Non-managers see a “Table Locked” dialog with only a “Dismiss” button. Managers see an additional “Take Over” button.

Protocol messages

Terminal to hub (4 message types)

Type	Purpose	Key fields
`TABLE_LOCK_ACQUIRE`	Request table lock	`tableId`
`TABLE_LOCK_RELEASE`	Release table lock	`tableId`
`TABLE_LOCK_HEARTBEAT`	Keep lock alive	`tableId`
`TABLE_LOCK_FORCE_ACQUIRE`	Manager override	`tableId`

Hub to terminal (5 message types)

Type	Purpose	Key fields
`TABLE_LOCK_GRANTED`	Lock acquired	`tableId`
`TABLE_LOCK_DENIED`	Lock rejected	`tableId`, `lockedBy: { userId, userName }`
`TABLE_LOCK_RELEASED`	Lock released by holder	`tableId`
`TABLE_LOCK_REVOKED`	Lock taken away	`tableId`, `reason`
`TABLE_LOCKS_STATE`	Full lock snapshot	`locks: [{ tableId, terminalId, userId, userName }]`

Frontend lock handling

Hub transport

heldTableLocks: Set<number> — Table IDs currently locked by this terminal
pendingTableLocks: Map<number, { resolve, timer }> — In-flight acquire requests
Separate heartbeat timer: sends TABLE_LOCK_HEARTBEAT for all held locks every 15s

acquireTableLock() and forceAcquireTableLock() return a Promise<TableLockResult> that resolves on TABLE_LOCK_GRANTED or TABLE_LOCK_DENIED, or returns { granted: false } on timeout (fail-closed).

Direct transport

In direct mode, table locking is disabled. All acquireTableLock() calls return { granted: true } immediately.

TableLockGuard

Renderless component on the order page (realtime/TableLockGuard.tsx):

Responsibility	How
Release on unmount	`useEffect` cleanup calls `releaseTableLock(tableId)`
Re-acquire on reconnect	`onStateChange("connected")` triggers `acquireTableLock(tableId)`
Redirect on revocation	`onTableLockRevoked(tableId)` calls `router.replace("/")`

FloorPlanScreen

Double-tap guard — pendingLockTableRef cancels stale in-flight acquires on new table tap
Acquire before navigate — Lock acquired, then navigate to order page on success
TableLockedDialog — Shown on deny with the holder’s name. Managers see “Take Over”
Cancel cleanup — Dismissing modals releases any pending lock
Transfer mode — Destination table lock acquired before transfer navigation
Lock state subscription — Locked tables show amber label text on the floor plan

Table locks vs order leases

Aspect	Table lock	Order lease
Scope	Table (floor plan level)	Order (snapshot level)
When acquired	Tapping a table on the floor plan	Opening an order for editing
TTL	45s	60s
Heartbeat	15s	20s
Force acquire	Requires `manager` role (server-enforced)	`force: true` flag in `LEASE_ACQUIRE`
Fail-closed timeout	Yes — deny on timeout	No — deny on timeout
Offline behavior	Disabled (returns `granted: true`)	Denied (returns `granted: false`)

Timing summary

Parameter	Value	Defined in
Lock TTL	45s	`TABLE_LOCK_TTL_MS` in `constants.ts`
Heartbeat interval	15s	`TABLE_LOCK_HEARTBEAT_MS` in `constants.ts`
Disconnect grace	10s	`GRACE_MS` in `constants.ts` (shared with leases)
Acquire timeout (frontend)	10s	`LEASE_TIMEOUT_MS` in `hubTransport.ts`
Tick interval (hub)	15s	`TABLE_LOCK_HEARTBEAT_MS` in `index.ts`

Overview

Core concepts

Implementation

Operations

How it works

Acquiring a lock

Maintaining a lock

Releasing a lock

Lock expiry (tick)

Disconnect grace period

Manager override (force acquire)

Protocol messages

Terminal to hub (4 message types)

Hub to terminal (5 message types)

Frontend lock handling

Hub transport

Direct transport

TableLockGuard

FloorPlanScreen

Table locks vs order leases

Timing summary

​How it works

​Acquiring a lock

​Maintaining a lock

​Releasing a lock

​Lock expiry (tick)

​Disconnect grace period

​Manager override (force acquire)

​Protocol messages

​Terminal to hub (4 message types)

​Hub to terminal (5 message types)

​Frontend lock handling

​Hub transport

​Direct transport

​TableLockGuard

​FloorPlanScreen

​Table locks vs order leases

​Timing summary

How it works

Acquiring a lock

Maintaining a lock

Releasing a lock

Lock expiry (tick)

Disconnect grace period

Manager override (force acquire)

Protocol messages

Terminal to hub (4 message types)

Hub to terminal (5 message types)

Frontend lock handling

Hub transport

Direct transport

TableLockGuard

FloorPlanScreen

Table locks vs order leases

Timing summary