"""
# ── Idempotency store ─────────────────────────────────────────────────
_PENDING = object() # sentinel: a request for this key is currently in-flight
# Fallback TTL only for pending files that contain no parseable PID (e.g. empty
# files written by an older deployment before this fix). Long-running operations
# (advance, run_to_completion) can exceed 60 s, so this guard is NOT used as the
# primary staleness check — PID liveness is used instead.
_PENDING_STALE_SECS = 300
def _pid_is_running(pid: int) -> bool:
"""Return True if the process with the given PID is still running."""
try:
os.kill(pid, 0) # signal 0: check existence, don't send a signal
return True
except ProcessLookupError:
return False
except PermissionError:
return True # process exists but we can't signal it — treat as running
class _IdempotencyStore:
"""Cache last result per X-Request-Id so a network retry doesn't re-execute.
claim() atomically checks and reserves a key in one lock acquisition,
preventing the TOCTOU window where two concurrent requests with the same
X-Request-Id could both see a cache miss and both execute the operation.
SINGLE-PROCESS LIMITATION: This store is in-memory only. Idempotency
guarantees hold within one server process (single uvicorn worker) and
within the TTL window. After a server restart, or across multiple workers,
the cache is empty and a client retry with the same X-Request-Id will re-
execute the action. The task state machine (state checks + task lock)
provides the safety net: a re-executed transition either succeeds (state
is valid) or raises 409 (InvalidTransition / TaskBusy). This is acceptable
for the intended single-worker personal-project deployment.
"""
TTL = 300 # seconds; covers typical mobile network timeout-and-retry windows
def __init__(self) -> None:
self._store: dict[str, dict] = {}
self._lock = threading.Lock()
def claim(self, key: str):
"""Atomically check and claim a request key.
Returns:
None – key was unclaimed; caller now owns it (in-flight marker set)
_PENDING – another call with this key is currently executing