build_tools.syllable_walk_web.api.walker_lock

Lock-related helper functions for walker API handlers.

This module isolates cooperative session-lock logic used by walker endpoints. It keeps the lock behavior in one place so api/walker.py can focus on endpoint orchestration.

Important: - These helpers implement single-user multi-tab consistency behavior. - They are not an authentication or security boundary.

Functions

coerce_lock_holder_id(body)	Extract optional lock_holder_id from request payload.
lock_conflict_error(*, active_session_id, lock_payload)	Build one deterministic lock-conflict response payload.
enforce_active_session_lock(body, state)	Enforce active-session lock ownership for mutating requests.
clear_active_session_context(state)	Clear active loaded-session metadata from server state.

Module Contents

build_tools.syllable_walk_web.api.walker_lock.coerce_lock_holder_id(body)

Extract optional lock_holder_id from request payload.

Parameters:

body (dict[str, Any]) – Request JSON payload.

Returns:

Tuple of (holder_id, error_message). holder_id is stripped when present and valid. error_message is populated when input is present but invalid.

Return type:

tuple[str | None, str | None]

build_tools.syllable_walk_web.api.walker_lock.lock_conflict_error(*, active_session_id, lock_payload)

Build one deterministic lock-conflict response payload.

build_tools.syllable_walk_web.api.walker_lock.enforce_active_session_lock(body, state)

Enforce active-session lock ownership for mutating requests.

Behavior: - If no active session lock context exists, request is allowed. - If active lock exists, caller must provide matching lock_holder_id. - Lock is refreshed via cooperative lock service when holder matches.

build_tools.syllable_walk_web.api.walker_lock.clear_active_session_context(state)

Clear active loaded-session metadata from server state.