mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/visual_run/transport.py

@@ -0,0 +1,239 @@
+"""Cursor-aware transport projection for a durable visual run."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.visual_run.contracts import (
+    MAX_EVENT_BYTES,
+    VisualRunError,
+    VisualRunEvent,
+    canonical_event_bytes,
+    parse_event,
+)
+from mostlyright.data_harness.visual_run.reducer import ReducedRun, apply_event
+from mostlyright.data_harness.visual_run.store import (
+    LOG_NAME,
+    MAX_LOG_BYTES,
+    EventPage,
+    VisualRunStore,
+)
+
+VISUAL_RUN_DIR = "visual-run"
+SNAPSHOT_SCHEMA_VERSION = "visual-run-snapshot.v1"
+
+
+@dataclass(frozen=True)
+class TransportSnapshot:
+    """One reduced state paired with the exact durable cursor that produced it."""
+
+    cursor: int
+    state: ReducedRun
+
+    def to_mapping(self) -> dict[str, Any]:
+        terminal = self.state.terminal_error
+        return {
+            "schema_version": SNAPSHOT_SCHEMA_VERSION,
+            "cursor": self.cursor,
+            "run_id": self.state.run_id,
+            "lifecycle": self.state.lifecycle,
+            "active_object_id": self.state.active_object_id,
+            "cells": [
+                {
+                    "cell_id": cell.cell_id,
+                    "cell_type": cell.cell_type,
+                    "version": cell.version,
+                    "phase": cell.phase,
+                    "stage": cell.stage,
+                    "status": cell.status,
+                    "source_length": cell.source_length,
+                    "source": cell.source.to_mapping() if cell.source is not None else None,
+                    "execution_count": cell.execution_count,
+                    "outputs": [artifact.to_mapping() for artifact in cell.outputs],
+                    "error": cell.error.to_mapping() if cell.error is not None else None,
+                }
+                for cell in self.state.cells.values()
+            ],
+            "observations": [item.to_mapping() for item in self.state.observations],
+            "objects": [
+                {
+                    "object_id": item.object_id,
+                    "kind": item.kind,
+                    "version": item.version,
+                    "phase": item.phase,
+                    "stage": item.stage,
+                    "status": item.status,
+                    "payload": dict(item.payload),
+                    "artifact": item.artifact.to_mapping() if item.artifact is not None else None,
+                    "error": item.error.to_mapping() if item.error is not None else None,
+                }
+                for item in self.state.objects.values()
+            ],
+            "quality": (
+                {
+                    "checks_passed": self.state.quality[0],
+                    "checks_total": self.state.quality[1],
+                }
+                if self.state.quality is not None
+                else None
+            ),
+            "candidate_digest": self.state.candidate_digest,
+            # This is narration only. Candidate admission remains an independent viewer concern.
+            "table_narrated_ready": self.state.table_ready,
+            "terminal_error": terminal.to_mapping() if terminal is not None else None,
+        }
+
+
+class VisualRunTransport:
+    """Bounded incremental projection over a :class:`VisualRunStore`.
+
+    A transport instance reduces each durable event at most once. Reconnects page from the store
+    using their durable sequence cursor, while a process restart reconstructs the same state by
+    replaying the append-only log.
+    """
+
+    def __init__(self, store: VisualRunStore) -> None:
+        self.store = store
+        self._lock = threading.Lock()
+        self._state = ReducedRun()
+
+    @property
+    def cursor(self) -> int:
+        with self._lock:
+            return self._state.cursor
+
+    def snapshot(self) -> TransportSnapshot:
+        with self._lock:
+            while True:
+                page = self.store.page_after(self._state.cursor)
+                for event in page.events:
+                    self._state = apply_event(self._state, event)
+                if not page.truncated:
+                    break
+            return TransportSnapshot(self._state.cursor, self._state)
+
+    def events_after(self, cursor: int, *, limit: int = 256) -> EventPage:
+        return self.store.page_after(cursor, limit=limit)
+
+    def snapshot_bytes(self) -> bytes:
+        return (
+            json.dumps(
+                self.snapshot().to_mapping(),
+                ensure_ascii=False,
+                allow_nan=False,
+                sort_keys=True,
+                separators=(",", ":"),
+            )
+            + "\n"
+        ).encode("utf-8")
+
+    def sse_after(self, last_event_id: str | None, *, limit: int = 256) -> bytes:
+        cursor = parse_last_event_id(last_event_id)
+        page = self.events_after(cursor, limit=limit)
+        chunks: list[bytes] = []
+        for event in page.events:
+            chunks.extend(
+                (
+                    f"id: {event.sequence}\n".encode(),
+                    f"event: {event.event_type}\n".encode(),
+                    b"data: " + canonical_event_bytes(event).rstrip(b"\n") + b"\n\n",
+                )
+            )
+        return b"".join(chunks)
+
+
+def parse_last_event_id(value: str | None) -> int:
+    if value is None or value == "":
+        return 0
+    if not value.isascii() or not value.isdecimal() or len(value) > 12:
+        raise VisualRunError("VISUAL_RUN_CURSOR_INVALID", "Last-Event-ID is not a valid cursor")
+    cursor = int(value)
+    if cursor > 100_000:
+        raise VisualRunError("VISUAL_RUN_CURSOR_INVALID", "Last-Event-ID exceeds the event ceiling")
+    return cursor
+
+
+def discover_visual_transport(
+    research_dir: Path, *, directory_fd: int | None = None
+) -> VisualRunTransport | None:
+    """Discover a visual log by fixed research-relative name without event-supplied paths."""
+
+    root = Path(research_dir) / VISUAL_RUN_DIR
+    owned_directory = directory_fd is None
+    if directory_fd is None:
+        try:
+            directory_fd = os.open(
+                research_dir,
+                os.O_RDONLY | os.O_DIRECTORY | os.O_CLOEXEC | os.O_NOFOLLOW,
+            )
+        except OSError as exc:
+            raise VisualRunError(
+                "VISUAL_RUN_STORE_IDENTITY",
+                "visual run research root is not a stable real directory",
+            ) from exc
+    try:
+        try:
+            root_fd = os.open(
+                VISUAL_RUN_DIR,
+                os.O_RDONLY | os.O_DIRECTORY | os.O_CLOEXEC | os.O_NOFOLLOW,
+                dir_fd=directory_fd,
+            )
+        except FileNotFoundError:
+            return None
+        except OSError as exc:
+            raise VisualRunError(
+                "VISUAL_RUN_STORE_IDENTITY",
+                "visual run root is not a stable real directory",
+            ) from exc
+        try:
+            try:
+                log_fd = os.open(
+                    LOG_NAME,
+                    os.O_RDONLY | os.O_NONBLOCK | os.O_CLOEXEC | os.O_NOFOLLOW,
+                    dir_fd=root_fd,
+                )
+            except FileNotFoundError:
+                # Store construction durably installs the directory before the first append.
+                # A process may stop in that valid pre-start state; callers can safely reopen
+                # the descriptor-pinned root and create the same fenced run.
+                return None
+            except OSError as exc:
+                raise VisualRunError(
+                    "VISUAL_RUN_STORE_IDENTITY",
+                    "visual run log is not a stable real file",
+                ) from exc
+            try:
+                identity = os.fstat(log_fd)
+                if not stat.S_ISREG(identity.st_mode) or identity.st_nlink != 1:
+                    raise VisualRunError(
+                        "VISUAL_RUN_STORE_IDENTITY",
+                        "visual run log is not a single-link regular file",
+                    )
+                if identity.st_size > MAX_LOG_BYTES:
+                    raise VisualRunError(
+                        "VISUAL_RUN_LOG_LIMIT", "visual run log exceeds its byte ceiling"
+                    )
+                prefix = os.read(log_fd, MAX_EVENT_BYTES + 1)
+            finally:
+                os.close(log_fd)
+            newline = prefix.find(b"\n")
+            if newline < 0:
+                code = (
+                    "VISUAL_RUN_EVENT_LIMIT"
+                    if len(prefix) > MAX_EVENT_BYTES
+                    else "VISUAL_RUN_LOG_TRUNCATED"
+                )
+                raise VisualRunError(code, "visual run log has no bounded complete record")
+            event: VisualRunEvent = parse_event(prefix[:newline])
+            return VisualRunTransport(VisualRunStore(root, event.run_id, root_fd=root_fd))
+        finally:
+            os.close(root_fd)
+    finally:
+        if owned_directory:
+            os.close(directory_fd)