loopcaptain 0.3.1__py3-none-any.whl

loopcaptain/protocol/store.py

@@ -0,0 +1,275 @@
+"""Reading and writing a loop's folder, `.loops/<loop-id>/` in its repository.
+
+The files are the truth; nothing here keeps state. A line the models refuse is reported, never
+fatal: a loop that writes one bad line must not blank its own page.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+
+from loopcaptain.protocol.models import (
+    EVENT,
+    EVENTS_FILE,
+    FOLDER,
+    INBOX_FILE,
+    MANIFEST_FILE,
+    AnyEvent,
+    InboxEntry,
+    InboxKind,
+    InboxRead,
+    Manifest,
+    is_slug,
+    now,
+)
+from loopcaptain.protocol.signing import sign
+
+#: The most the board reads of one file. A summary log of a long loop is a few hundred kilobytes.
+MAX_LOG_BYTES = 20_000_000
+MAX_MANIFEST_BYTES = 1_000_000
+
+
+class StoreError(Exception):
+    """A loop folder that cannot be read or written as asked."""
+
+
+@dataclass(frozen=True)
+class Problem:
+    """One thing in a loop's folder the board could not read."""
+
+    file: str
+    line: int  # 0 for the whole file
+    message: str
+
+    def __str__(self) -> str:
+        where = f"{self.file}:{self.line}" if self.line else self.file
+        return f"{where}: {self.message}"
+
+
+def loop_dir(repo: Path, loop_id: str) -> Path:
+    if not is_slug(loop_id):
+        raise StoreError(f"{loop_id!r} is not a loop id")
+    return repo / FOLDER / loop_id
+
+
+def speaks_protocol(manifest: Path) -> bool:
+    """Whether a loop.json is this protocol's: it carries the `protocol` field.
+
+    Other tools keep their own files in a folder called `.loops/`; those are skipped quietly.
+    """
+    try:
+        data = json.loads(read_bounded(manifest, MAX_MANIFEST_BYTES))
+    except (FileNotFoundError, StoreError, ValueError):
+        return False
+    return isinstance(data, dict) and "protocol" in data
+
+
+def loop_ids(repo: Path) -> list[str]:
+    """The loops a repository holds: every sub-folder of `.loops/` whose loop.json speaks the protocol."""
+    folder = repo / FOLDER
+    if folder.is_symlink() or not folder.is_dir():
+        return []  # a `.loops` that is a link could show another repository's loops as this one's
+    return sorted(
+        child.name
+        for child in folder.iterdir()
+        if is_slug(child.name) and not child.is_symlink() and speaks_protocol(child / MANIFEST_FILE)
+    )
+
+
+def short_error(error: ValidationError) -> str:
+    """A validation error in one line, naming the field."""
+    parts = []
+    for item in error.errors()[:3]:
+        where = ".".join(str(part) for part in item["loc"])
+        parts.append(f"{where}: {item['msg']}" if where else item["msg"])
+    return "; ".join(parts)
+
+
+# ---- the manifest ----
+
+
+def read_manifest(repo: Path, loop_id: str) -> Manifest:
+    path = loop_dir(repo, loop_id) / MANIFEST_FILE
+    try:
+        manifest = Manifest.model_validate_json(read_bounded(path, MAX_MANIFEST_BYTES))
+    except FileNotFoundError as error:
+        raise StoreError(f"{MANIFEST_FILE}: {error.strerror or error}") from error
+    except ValidationError as error:
+        raise StoreError(f"{MANIFEST_FILE}: {short_error(error)}") from error
+    if manifest.id != loop_id:
+        raise StoreError(f"{MANIFEST_FILE}: id {manifest.id!r} does not match its folder {loop_id!r}")
+    return manifest
+
+
+def contained(repo: Path, folder: Path, loop_id: str) -> None:
+    """Refuse a loop folder that resolves outside its repository, through a link on the way."""
+    if not folder.resolve().is_relative_to(repo.resolve()):
+        raise StoreError(f"the folder of {loop_id!r} leads out of {repo.name}")
+
+
+def write_manifest(repo: Path, manifest: Manifest) -> Path:
+    """Write `loop.json` whole or not at all: a reader never sees half a file."""
+    folder = loop_dir(repo, manifest.id)
+    contained(repo, folder, manifest.id)
+    folder.mkdir(parents=True, exist_ok=True)
+    contained(repo, folder, manifest.id)
+    path = folder / MANIFEST_FILE
+    tmp = folder / f"{MANIFEST_FILE}.{secrets.token_hex(4)}.tmp"
+    tmp.write_text(manifest.model_dump_json(indent=2, exclude_none=True) + "\n", encoding="utf-8")
+    os.replace(tmp, path)
+    return path
+
+
+# ---- events and inbox: one JSON object per line ----
+
+
+def append_line(path: Path, payload: str) -> None:
+    """One write call on a file opened for append: lines from two writers do not interleave.
+
+    A symbolic link is refused: a repository must not be able to point its inbox at another file.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        descriptor = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_CREAT | os.O_NOFOLLOW, 0o600)
+    except OSError as error:
+        raise StoreError(f"{path.name}: cannot be written ({error.strerror or error})") from error
+    try:
+        os.write(descriptor, (payload + "\n").encode("utf-8"))
+    finally:
+        os.close(descriptor)
+
+
+def read_bounded(path: Path, limit: int) -> str:
+    """A regular file's text, up to `limit` bytes; anything else, a link too, is refused before it is opened.
+
+    The board reads these files on every request, so a pipe that never ends or a log of gigabytes
+    in one repository must not stall or fill it.
+    """
+    try:
+        info = path.lstat()
+    except FileNotFoundError:
+        raise
+    except OSError as error:
+        raise StoreError(f"{path.name}: {error.strerror or error}") from error
+    if not stat.S_ISREG(info.st_mode):
+        raise StoreError(f"{path.name}: not a regular file")
+    if info.st_size > limit:
+        raise StoreError(
+            f"{path.name}: {info.st_size // 1_000_000} MB, over the {limit // 1_000_000} MB the board reads"
+        )
+    try:
+        # Bytes that are not text become a marker, so one bad line is reported and the rest reads.
+        return path.read_bytes().decode("utf-8", errors="replace")
+    except OSError as error:
+        raise StoreError(f"{path.name}: {error.strerror or error}") from error
+
+
+def complete_lines(path: Path) -> list[tuple[int, str]]:
+    """The complete lines of a file with their numbers. A last line still being written is left out."""
+    try:
+        text = read_bounded(path, MAX_LOG_BYTES)
+    except FileNotFoundError:
+        return []
+    whole = text if text.endswith("\n") else text[: text.rfind("\n") + 1]
+    return [(n, line) for n, line in enumerate(whole.splitlines(), start=1) if line.strip()]
+
+
+def parse_event(data: dict[str, Any]) -> AnyEvent:
+    return EVENT.validate_python(data)
+
+
+def append_event(repo: Path, loop_id: str, event: AnyEvent) -> None:
+    append_line(loop_dir(repo, loop_id) / EVENTS_FILE, event.model_dump_json(exclude_none=True))
+
+
+def read_events(repo: Path, loop_id: str) -> tuple[list[AnyEvent], list[Problem]]:
+    events: list[AnyEvent] = []
+    problems: list[Problem] = []
+    for number, line in complete_lines(loop_dir(repo, loop_id) / EVENTS_FILE):
+        try:
+            events.append(EVENT.validate_json(line))
+        except ValidationError as error:
+            problems.append(Problem(EVENTS_FILE, number, short_error(error)))
+    return events, problems
+
+
+def append_inbox(
+    repo: Path,
+    loop_id: str,
+    kind: InboxKind,
+    text: str = "",
+    round_: int | None = None,
+    key: bytes | None = None,
+    question: str | None = None,
+    choice: str | None = None,
+) -> InboxEntry:
+    """What the person sends, signed with `key` when given. The loop's folder must exist: the board
+    never creates a loop."""
+    folder = loop_dir(repo, loop_id)
+    if not (folder / MANIFEST_FILE).is_file():
+        raise StoreError(f"no loop {loop_id!r} in {repo.name}")
+    contained(repo, folder, loop_id)
+    stamp = now()
+    entry = InboxEntry(
+        id=f"{stamp:%Y%m%dT%H%M%S}-{secrets.token_hex(2)}",
+        ts=stamp,
+        kind=kind,
+        text=text.strip(),
+        round=round_,
+        question=question,
+        choice=choice,
+        loop=loop_id,
+    )
+    if key is not None:
+        entry = entry.model_copy(update={"sig": sign(entry.body(), key)})
+    append_line(folder / INBOX_FILE, entry.model_dump_json(exclude_none=True))
+    return entry
+
+
+def read_inbox(repo: Path, loop_id: str) -> tuple[list[InboxEntry], list[Problem]]:
+    entries: list[InboxEntry] = []
+    problems: list[Problem] = []
+    for number, line in complete_lines(loop_dir(repo, loop_id) / INBOX_FILE):
+        try:
+            entries.append(InboxEntry.model_validate_json(line))
+        except ValidationError as error:
+            problems.append(Problem(INBOX_FILE, number, short_error(error)))
+    return entries, problems
+
+
+def take_inbox(repo: Path, loop_id: str) -> list[InboxEntry]:
+    """What the person sent that the loop has not taken yet, oldest first; marks it read.
+
+    The loop's side of the inbox: it appends `inbox_read` to the loop's own events.
+    """
+    events, _ = read_events(repo, loop_id)
+    taken = {entry_id for event in events if isinstance(event, InboxRead) for entry_id in event.ids}
+    entries, _ = read_inbox(repo, loop_id)
+    fresh = [entry for entry in entries if entry.id not in taken]
+    if fresh:
+        append_event(repo, loop_id, InboxRead(ts=now(), ids=[entry.id for entry in fresh]))
+    return fresh
+
+
+def fingerprint(repo: Path, loop_id: str) -> str:
+    """Changes whenever any of the loop's files does; the page polls it to know when to reload."""
+    parts = []
+    for name in (MANIFEST_FILE, EVENTS_FILE, INBOX_FILE):
+        try:
+            stat = (loop_dir(repo, loop_id) / name).stat()
+            parts.append(f"{stat.st_mtime_ns}-{stat.st_size}")
+        except OSError:
+            parts.append("0")
+    return ".".join(parts)
+
+
+def dump(data: object) -> str:
+    return json.dumps(data, ensure_ascii=False)

loopcaptain/protocol/validate.py

@@ -0,0 +1,199 @@
+"""`loopcaptain validate`: check a repository's `.loops` folders against the protocol.
+
+A problem breaks the text of LOOPS.md or makes the board show something false; a warning is a sign
+that a loop is wired in a way that hides what really happens (a round written after the fact, an
+inbox nobody reads). `--strict` counts warnings as problems.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+from loopcaptain.protocol import store
+from loopcaptain.protocol.models import (
+    FOLDER,
+    MANIFEST_FILE,
+    AnyEvent,
+    InboxEntry,
+    InboxRead,
+    Manifest,
+    RoundFinished,
+    RoundStarted,
+    StepFinished,
+    StepStarted,
+)
+from loopcaptain.protocol.store import StoreError
+
+
+@dataclass
+class Report:
+    """What `validate` found, problems and warnings apart, one line each."""
+
+    problems: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    def extend(self, prefix: str, other: Report) -> None:
+        self.problems.extend(f"{prefix}{line}" for line in other.problems)
+        self.warnings.extend(f"{prefix}{line}" for line in other.warnings)
+
+
+def validate_repo(repo: Path) -> list[str]:
+    """Every problem found, one line each; empty when the folders are sound."""
+    return validate_report(repo).problems
+
+
+def validate_report(repo: Path) -> Report:
+    """Problems and warnings of every loop in a repository.
+
+    Only folders whose loop.json carries the `protocol` field are loops; anything else another
+    tool keeps under the same name is not this protocol's business.
+    """
+    folder = repo / FOLDER
+    if not folder.is_dir():
+        return Report(problems=[f"{repo}: no {FOLDER} folder"])
+    loops = store.loop_ids(repo)
+    if not loops:
+        return Report(
+            problems=[
+                f"{FOLDER}: no loop inside "
+                f"(a loop is a sub-folder whose {MANIFEST_FILE} has a protocol field)"
+            ]
+        )
+    report = Report()
+    for loop_id in loops:
+        report.extend(f"{loop_id}/", validate_loop(repo, loop_id))
+    return report
+
+
+def validate_loop(repo: Path, loop_id: str) -> Report:
+    try:
+        manifest = store.read_manifest(repo, loop_id)
+        events, event_problems = store.read_events(repo, loop_id)
+        inbox, inbox_problems = store.read_inbox(repo, loop_id)
+    except StoreError as error:
+        return Report(problems=[str(error)])
+    report = Report(problems=[str(problem) for problem in (*event_problems, *inbox_problems)])
+    report.problems += order_problems(manifest, events)
+    report.problems += missing_paths(repo, manifest, events)
+    report.problems += time_problems(events)
+    report.problems += verdict_problems(events)
+    report.warnings += back_produced(events)
+    report.warnings += missing_outputs(repo, manifest)
+    report.warnings += unread_inbox(events, inbox)
+    report.warnings += restarted_count(events)
+    return Report(list(dict.fromkeys(report.problems)), list(dict.fromkeys(report.warnings)))
+
+
+def unread_inbox(events: list[AnyEvent], inbox: list[InboxEntry]) -> list[str]:
+    """Entries the person sent before a round began that the loop never took: it does not listen."""
+    taken = {entry_id for event in events if isinstance(event, InboxRead) for entry_id in event.ids}
+    starts = [event.ts for event in events if isinstance(event, RoundStarted)]
+    missed = [entry for entry in inbox if entry.id not in taken and starts and entry.ts < max(starts)]
+    if not missed:
+        return []
+    count = f"{len(missed)} entr{'y' if len(missed) == 1 else 'ies'}"
+    return [f"inbox.jsonl: {count} sent before a round began and never taken; does the loop read it?"]
+
+
+def order_problems(manifest: Manifest, events: list[AnyEvent]) -> list[str]:
+    declared = {step.id for step in manifest.steps}
+    started: set[int] = set()
+    problems: list[str] = []
+    unknown: list[str] = []
+    for event in events:
+        if isinstance(event, RoundStarted):
+            started.add(event.round)
+        elif isinstance(event, RoundFinished):
+            if event.round not in started:
+                problems.append(f"events.jsonl: round {event.round} finished without round_started")
+        elif isinstance(event, StepStarted | StepFinished):
+            if event.round not in started:
+                problems.append(
+                    f"events.jsonl: step {event.step!r} reported for round {event.round} before it started"
+                )
+            if declared and event.step not in declared and event.step not in unknown:
+                unknown.append(event.step)
+    return problems + [f"events.jsonl: step {step!r} is not in loop.json" for step in unknown]
+
+
+def missing_paths(repo: Path, manifest: Manifest, events: list[AnyEvent]) -> list[str]:
+    """Paths the loop names as written that are not there: the board would link to nothing."""
+    problems = [
+        f"loop.json: {path} does not exist"
+        for path in (manifest.brief.path, *(step.prompt for step in manifest.steps))
+        if path and not (repo / path).exists()
+    ]
+    for event in events:
+        if isinstance(event, StepFinished) and event.artifact and not (repo / event.artifact).exists():
+            problems.append(
+                f"events.jsonl: round {event.round} step {event.step!r}: {event.artifact} does not exist"
+            )
+    return problems
+
+
+def missing_outputs(repo: Path, manifest: Manifest) -> list[str]:
+    """Outputs may not exist before the loop is done, so a missing one is a warning."""
+    return [
+        f"loop.json: output {output.name!r} at {output.path} does not exist yet"
+        for output in manifest.outputs
+        if not (repo / output.path).exists()
+    ]
+
+
+def time_problems(events: list[AnyEvent]) -> list[str]:
+    problems = []
+    latest: datetime | None = None
+    for number, event in enumerate(events, start=1):
+        if latest and event.ts < latest:
+            problems.append(f"events.jsonl: event {number} ({event.event}) is earlier than the one before it")
+        latest = max(latest, event.ts) if latest else event.ts
+    return problems
+
+
+def verdict_problems(events: list[AnyEvent]) -> list[str]:
+    verdicts: dict[int, str] = {}
+    problems = []
+    for event in events:
+        if not isinstance(event, RoundFinished):
+            continue
+        earlier = verdicts.get(event.round)
+        verdicts[event.round] = event.verdict
+        # `wait` is a pause, not an outcome: a round that waited may finish again.
+        if earlier and earlier != "wait" and earlier != event.verdict:
+            problems.append(
+                f"events.jsonl: round {event.round} finished twice, as {earlier} and as {event.verdict}"
+            )
+    return problems
+
+
+def back_produced(events: list[AnyEvent]) -> list[str]:
+    """A round whose steps all carry one time was written after the fact: its durations are invented."""
+    times: dict[int, set[datetime]] = {}
+    counts: dict[int, int] = {}
+    for event in events:
+        if isinstance(event, StepFinished):
+            times.setdefault(event.round, set()).add(event.when)
+            counts[event.round] = counts.get(event.round, 0) + 1
+    return [
+        f"events.jsonl: round {number}: all {counts[number]} steps share one time; written after the fact?"
+        for number, stamps in sorted(times.items())
+        if counts[number] > 1 and len(stamps) == 1
+    ]
+
+
+def restarted_count(events: list[AnyEvent]) -> list[str]:
+    """A round started below one already started: a second run counting from the start in one folder."""
+    highest = 0
+    warnings = []
+    for event in events:
+        if not isinstance(event, RoundStarted):
+            continue
+        if event.round < highest:
+            warnings.append(
+                f"events.jsonl: round {event.round} started after round {highest}; "
+                "a new run? give each run its own loop id"
+            )
+        highest = max(highest, event.round)
+    return warnings