Source code for osprey_connectors.session_hold

"""The session hold record: one durable file per session that holds its writes.

A *hold* is a set of open flags on one session. While any flag is open the
session is held, and every write execution site refuses the session's writes
(``session_held``). A flag is closed only by an answer that names it. This
module owns the record's format, its reader and its writer; it knows nothing
about who opens a flag — a flag carries an opaque ``source`` and ``reason``.

**The store.** Every call takes ``root``; ``None`` reads
:data:`HOLD_DIR_ENV_VAR` (``OSPREY_SESSION_HOLD_DIR``). An unset or empty root
is *no hold store*: nothing is written and nothing is ever held. Under a root,
one session's record is ``<root>/<session_key>/record.json``.

**Fail closed under a root.** :func:`is_held` answers ``True`` for an open
flag, and equally for a missing session directory, a missing record, a record
that cannot be read or parsed, a record of another schema, a symbolic link at
the session directory or the record, and an unsafe session key. It never
raises. :func:`open_flags` reports an unreadable record as the one synthetic
flag :data:`UNREADABLE_FLAG_ID`; answering that flag rewrites a fresh record
(with the synthetic flag kept, closed, for audit). Nothing else rewrites an
unreadable record: :func:`ensure_session` is create-if-absent and leaves an
existing file alone, readable or not.

**Writes.** Every write is a read-modify-write under an exclusive ``flock`` on
``<session dir>/record.json.lock`` and lands through
:func:`~osprey_connectors.safety_file.atomic_replace`, so a reader sees the
old record or the new one and two writers in two processes never lose each
other's flag. Answered flags stay in the record, closed, with the answer, the
operator and the time.

**Reads** follow no symbolic link: the session directory is checked with
:func:`os.lstat` and the record is opened ``O_NOFOLLOW`` and bounded, the same
reader the posture store uses for its tree.

This module imports only :mod:`~osprey_connectors.safety_file` from the
package, so the posture store can import it.
"""

from __future__ import annotations

import contextlib
import errno
import fcntl
import json
import logging
import os
import re
import stat
import time
from collections.abc import Iterable, Iterator
from dataclasses import dataclass
from datetime import UTC, datetime
from pathlib import Path
from typing import Final, Literal, NotRequired, TypedDict, TypeGuard

from osprey_connectors.safety_file import atomic_replace

__all__ = [
    "HOLD_DIR_ENV_VAR",
    "RECORD_NAME",
    "UNREADABLE_FLAG_ID",
    "HoldFlag",
    "answer_flags",
    "ensure_session",
    "has_no_record",
    "hold_root",
    "is_held",
    "is_safe_session_key",
    "mark_stop_unconfirmed",
    "open_flag",
    "open_flags",
]

logger = logging.getLogger(__name__)

#: The environment variable naming the hold root when no ``root`` is passed.
HOLD_DIR_ENV_VAR: Final = "OSPREY_SESSION_HOLD_DIR"

#: The record's file name inside a session's directory.
RECORD_NAME: Final = "record.json"

#: The record format. A record of any other schema is unreadable, and holds.
_SCHEMA_VERSION: Final = 1

#: The id of the one flag reported for a missing or unreadable record.
UNREADABLE_FLAG_ID: Final = "hold-record-unreadable"

#: The longest prompt excerpt a flag stores; the writer truncates.
_EXCERPT_LIMIT: Final = 200

#: The source of the synthetic flag.
_UNREADABLE_SOURCE: Final = "session_hold"
_UNREADABLE_REASON: Final = (
    "The session's hold record is missing or unreadable, so the session is held "
    "until an operator answers."
)

#: A session key is one path segment: a UUID, or a name of the same alphabet.
_SAFE_KEY: Final = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}")

#: Records are a few hundred bytes per flag; an over-long file is refused
#: rather than truncated into a parse.
_RECORD_READ_LIMIT: Final = 1024 * 1024

_LOCK_TIMEOUT_S: Final = 5.0
_LOCK_POLL_S: Final = 0.01
_DIR_MODE: Final = 0o750
_RECORD_MODE: Final = 0o640
_LOCK_MODE: Final = 0o640

_ANSWERS: Final = frozenset({"stop", "continue"})
_STR_FIELDS: Final = ("flag_id", "source", "reason", "prompt_ref", "prompt_excerpt", "opened_at")


class _FlagEntry(TypedDict):
    """One flag as the record holds it; :func:`_valid_flag` checks the required keys."""

    flag_id: str
    source: str
    reason: str
    prompt_ref: str
    prompt_excerpt: str
    opened_at: str
    state: Literal["open", "closed"]
    stop_unconfirmed: bool
    started: list[str]
    answer: NotRequired[Literal["stop", "continue"]]
    operator: NotRequired[str]
    answered_at: NotRequired[str]
    stop_operator: NotRequired[str]
    stop_marked_at: NotRequired[str]


[docs] @dataclass(frozen=True) class HoldFlag: """One open flag on a session, as :func:`open_flags` reports it.""" flag_id: str source: str reason: str prompt_ref: str prompt_excerpt: str opened_at: str stop_unconfirmed: bool = False started: tuple[str, ...] = ()
# -- paths -----------------------------------------------------------------------
[docs] def hold_root(root: Path | str | None = None) -> Path | None: """The hold root: *root* when given, else :data:`HOLD_DIR_ENV_VAR`; ``None`` is no store.""" text = str(root) if root is not None else os.environ.get(HOLD_DIR_ENV_VAR, "") if not text.strip(): return None return Path(text)
[docs] def is_safe_session_key(session_key: object) -> TypeGuard[str]: """Whether *session_key* is one safe path segment (no separator, no dot-name).""" return isinstance(session_key, str) and _SAFE_KEY.fullmatch(session_key) is not None
def _checked_key(session_key: object) -> str: if not is_safe_session_key(session_key): raise ValueError(f"unsafe session key {session_key!r}: not a safe file name") return session_key def _now() -> str: return datetime.now(UTC).isoformat(timespec="seconds").replace("+00:00", "Z") # -- reading --------------------------------------------------------------------- def _read_no_follow(path: Path) -> str: """*path*'s text, bounded, refusing a symbolic link at its last component.""" fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW) try: with os.fdopen(fd, encoding="utf-8", closefd=False) as handle: text = handle.read(_RECORD_READ_LIMIT + 1) finally: os.close(fd) if len(text) > _RECORD_READ_LIMIT: raise OSError(errno.EFBIG, f"{path} is larger than a hold record may be") return text def _valid_flag(entry: object) -> TypeGuard[_FlagEntry]: if not isinstance(entry, dict): return False if not all(isinstance(entry.get(name), str) for name in _STR_FIELDS): return False if entry.get("state") not in ("open", "closed"): return False if not isinstance(entry.get("stop_unconfirmed"), bool): return False started = entry.get("started") return isinstance(started, list) and all(isinstance(s, str) for s in started) def _read_record(root: Path, session_key: str) -> list[_FlagEntry] | None: """The session's flag entries, or ``None`` when the record is missing or unreadable. ``None`` covers every failure: a missing or non-directory session dir, a link at the dir or the record, an absent, unreadable, over-long or malformed file, another schema, another session's key. """ directory = root / session_key try: mode = os.lstat(directory).st_mode except OSError: return None if not stat.S_ISDIR(mode): return None try: payload: object = json.loads(_read_no_follow(directory / RECORD_NAME)) except (OSError, ValueError): return None if not isinstance(payload, dict): return None if payload.get("schema") != _SCHEMA_VERSION or payload.get("session_key") != session_key: return None flags: object = payload.get("flags") if not isinstance(flags, list): return None entries = [entry for entry in flags if _valid_flag(entry)] return entries if len(entries) == len(flags) else None def _to_flag(entry: _FlagEntry) -> HoldFlag: return HoldFlag( flag_id=entry["flag_id"], source=entry["source"], reason=entry["reason"], prompt_ref=entry["prompt_ref"], prompt_excerpt=entry["prompt_excerpt"], opened_at=entry["opened_at"], stop_unconfirmed=entry["stop_unconfirmed"], started=tuple(entry["started"]), ) _SYNTHETIC: Final = HoldFlag( flag_id=UNREADABLE_FLAG_ID, source=_UNREADABLE_SOURCE, reason=_UNREADABLE_REASON, prompt_ref="", prompt_excerpt="", opened_at="", )
[docs] def is_held(session_key: str, *, root: Path | str | None = None) -> bool: """Whether *session_key* is held. Never raises. No root: ``False``. Under a root: ``True`` for an open flag and for every way the record can fail to be read (see the module doc), including an unsafe key. """ try: resolved = hold_root(root) if resolved is None: return False if not is_safe_session_key(session_key): return True flags = _read_record(resolved, session_key) if flags is None: return True return any(entry["state"] == "open" for entry in flags) except Exception: # a write-path reader fails closed logger.warning("session hold for %r could not be read; held", session_key, exc_info=True) try: return hold_root(root) is not None except Exception: return True
[docs] def open_flags(session_key: str, *, root: Path | str | None = None) -> list[HoldFlag]: """The session's open flags, in the order they were opened. No root: ``[]``. A missing or unreadable record under a root: the one synthetic :data:`UNREADABLE_FLAG_ID` flag. Raises: ValueError: *session_key* is not a safe file name. """ resolved = hold_root(root) if resolved is None: return [] key = _checked_key(session_key) flags = _read_record(resolved, key) if flags is None: return [_SYNTHETIC] return [_to_flag(entry) for entry in flags if entry["state"] == "open"]
[docs] def has_no_record(session_key: str, *, root: Path | str | None = None) -> bool: """Whether nothing at all is on disk for this session under a root. The one question :func:`is_held` and :func:`open_flags` deliberately do not separate from an unreadable record: a caller that knows no session runs under this key can tell "never started" from "lost". It changes no answer of theirs. A session directory of any kind, even empty or a dangling link, is ``False``, and so is a path that cannot be examined. Raises: ValueError: *session_key* is not a safe file name. """ resolved = hold_root(root) key = _checked_key(session_key) if resolved is None: return False try: os.lstat(resolved / key) except FileNotFoundError: return True except OSError: return False return False
# -- writing --------------------------------------------------------------------- def _session_dir(root: Path, session_key: str) -> Path: """The session's directory, created when absent; never a symbolic link.""" root.mkdir(parents=True, exist_ok=True) directory = root / session_key with contextlib.suppress(FileExistsError): os.mkdir(directory, _DIR_MODE) mode = os.lstat(directory).st_mode if stat.S_ISLNK(mode) or not stat.S_ISDIR(mode): raise OSError(errno.ELOOP, f"{directory} is not a plain directory; nothing was written") return directory @contextlib.contextmanager def _locked(root: Path, session_key: str) -> Iterator[Path]: """Hold the session's record lock; yields the record path.""" directory = _session_dir(root, session_key) lock = directory / (RECORD_NAME + ".lock") fd = os.open(lock, os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW, _LOCK_MODE) try: deadline = time.monotonic() + _LOCK_TIMEOUT_S while True: try: fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB) break except BlockingIOError: if time.monotonic() >= deadline: raise RuntimeError( f"The session hold record at {directory} stayed locked for " f"{_LOCK_TIMEOUT_S:g} s; nothing was written" ) from None time.sleep(_LOCK_POLL_S) try: yield directory / RECORD_NAME finally: fcntl.flock(fd, fcntl.LOCK_UN) finally: os.close(fd) def _write(path: Path, session_key: str, flags: list[_FlagEntry]) -> None: payload = {"schema": _SCHEMA_VERSION, "session_key": session_key, "flags": flags} data = (json.dumps(payload, indent=2, sort_keys=True) + "\n").encode("utf-8") atomic_replace(path, data, mode=_RECORD_MODE) def _ids(flag_ids: Iterable[str]) -> frozenset[str]: if isinstance(flag_ids, (str, bytes)): raise TypeError("flag_ids is a collection of ids, not one string") return frozenset(flag_ids) def _open_entry( *, flag_id: str, source: str, reason: str, prompt_ref: str, prompt_excerpt: str, opened_at: str, ) -> _FlagEntry: """A new flag's record entry, with every field :func:`_valid_flag` requires.""" return { "flag_id": flag_id, "source": source, "reason": reason, "prompt_ref": prompt_ref, "prompt_excerpt": prompt_excerpt, "opened_at": opened_at, "state": "open", "stop_unconfirmed": False, "started": [], }
[docs] def ensure_session(session_key: str, *, root: Path | str | None = None) -> None: """Create the session's empty record when none exists. No root: nothing. Never rewrites an existing file, readable or not. Raises: ValueError: *session_key* is not a safe file name. OSError: The session directory is a link or could not be created. RuntimeError: The lock was not acquired in time. """ resolved = hold_root(root) if resolved is None: return key = _checked_key(session_key) with _locked(resolved, key) as path: if os.path.lexists(path): return _write(path, key, [])
[docs] def open_flag( session_key: str, *, flag_id: str, source: str, reason: str, prompt_ref: str, prompt_excerpt: str, root: Path | str | None = None, ) -> bool: """Open one flag; ``True`` when it was opened. ``False`` when there is no root, when a flag with the same ``(source, prompt_ref)`` or the same ``flag_id`` exists (open or closed), or when the record exists and is unreadable — that session is already held by the synthetic flag, and only its answer rewrites the record. A missing record is created with the flag. Raises: ValueError: *session_key* is not a safe file name. OSError: The session directory is a link, or the write failed. RuntimeError: The lock was not acquired in time. """ resolved = hold_root(root) if resolved is None: return False key = _checked_key(session_key) if len(prompt_excerpt) > _EXCERPT_LIMIT: prompt_excerpt = prompt_excerpt[: _EXCERPT_LIMIT - 1] + "…" with _locked(resolved, key) as path: flags = _read_record(resolved, key) if flags is None: if os.path.lexists(path): logger.warning( "session hold record %s is unreadable; flag %s not added", path, flag_id ) return False flags = [] for entry in flags: if entry["flag_id"] == flag_id or ( entry["source"] == source and entry["prompt_ref"] == prompt_ref ): return False flags.append( _open_entry( flag_id=flag_id, source=source, reason=reason, prompt_ref=prompt_ref, prompt_excerpt=prompt_excerpt, opened_at=_now(), ) ) _write(path, key, flags) return True
def _close(entry: _FlagEntry, answer: Literal["stop", "continue"], operator: str, at: str) -> None: """Mark *entry* closed with *answer*, by *operator*, at *at*.""" entry["state"] = "closed" entry["answer"] = answer entry["operator"] = operator entry["answered_at"] = at
[docs] def answer_flags( session_key: str, flag_ids: Iterable[str], *, answer: Literal["stop", "continue"], operator: str, root: Path | str | None = None, ) -> tuple[str, ...]: """Close the named open flags with *answer*; the ids released, in record order. Unknown and already-closed ids are ignored. Against a missing or unreadable record only :data:`UNREADABLE_FLAG_ID` can be answered, and answering it writes a fresh record holding that flag, closed. No root: ``()``. Raises: ValueError: An unsafe *session_key*, or an *answer* that is neither ``"stop"`` nor ``"continue"``. TypeError: *flag_ids* is a single string. OSError: The session directory is a link, or the write failed. RuntimeError: The lock was not acquired in time. """ if answer not in _ANSWERS: raise ValueError(f"answer must be 'stop' or 'continue', not {answer!r}") wanted = _ids(flag_ids) resolved = hold_root(root) if resolved is None: return () key = _checked_key(session_key) if not wanted: return () with _locked(resolved, key) as path: flags = _read_record(resolved, key) if flags is None: if UNREADABLE_FLAG_ID not in wanted: return () entry = _open_entry( flag_id=_SYNTHETIC.flag_id, source=_SYNTHETIC.source, reason=_SYNTHETIC.reason, prompt_ref=_SYNTHETIC.prompt_ref, prompt_excerpt=_SYNTHETIC.prompt_excerpt, opened_at=_SYNTHETIC.opened_at, ) _close(entry, answer, operator, _now()) _write(path, key, [entry]) return (UNREADABLE_FLAG_ID,) released: list[str] = [] stamp = _now() for entry in flags: if entry["state"] == "open" and entry["flag_id"] in wanted: _close(entry, answer, operator, stamp) released.append(str(entry["flag_id"])) if released: _write(path, key, flags) return tuple(released)
[docs] def mark_stop_unconfirmed( session_key: str, flag_ids: Iterable[str], *, operator: str, started: tuple[str, ...], root: Path | str | None = None, ) -> tuple[str, ...]: """Mark the named open flags as stopped-but-unconfirmed; the ids marked. The flags stay open — the turn did not stop — and record *started*, the commands still running, with the operator and the time. Closed and unknown ids are ignored; an unreadable record marks nothing. No root: ``()``. Raises: ValueError: *session_key* is not a safe file name. TypeError: *flag_ids* is a single string. OSError: The session directory is a link, or the write failed. RuntimeError: The lock was not acquired in time. """ wanted = _ids(flag_ids) resolved = hold_root(root) if resolved is None: return () key = _checked_key(session_key) if not wanted: return () with _locked(resolved, key) as path: flags = _read_record(resolved, key) if flags is None: return () marked: list[str] = [] stamp = _now() for entry in flags: if entry["state"] == "open" and entry["flag_id"] in wanted: entry["stop_unconfirmed"] = True entry["started"] = [str(command) for command in started] entry["stop_operator"] = operator entry["stop_marked_at"] = stamp marked.append(entry["flag_id"]) if marked: _write(path, key, flags) return tuple(marked)