From 27a597b88c128c0d7bc0a7251d6600a60c0e4a2c Mon Sep 17 00:00:00 2001 From: dayfine Date: Sat, 14 Nov 2026 02:36:52 -0800 Subject: [PATCH 1/3] lab/server: Slice 2 attach-only read server (#131) MCP over Streamable HTTP on 127.0.0.1 (stdlib http.server): bearer token, Host/Origin checks, sessions, size caps, and a config that serves only console B. Resources console://B/state and console://B/save from strict reads of Lab/state.json and Lab/save.json; missing, partial, malformed, unsupported-schema, dead-pid and stale-heartbeat files are explicit unavailable states. Tools: ensure_game (verification only) and shot, which waits for a frame newer than the call before asking the app's read-only shot line. Fake-lab tests cover partial writes, stale files, sequence resets, app restarts, timeouts and concurrent readers. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- lab/server/README.md | 80 +++++- lab/server/pa_lab/__init__.py | 2 +- lab/server/pa_lab/__main__.py | 45 ++- lab/server/pa_lab/config.py | 111 ++++++++ lab/server/pa_lab/lab_reader.py | 232 ++++++++++++++++ lab/server/pa_lab/mcp_server.py | 393 +++++++++++++++++++++++++++ lab/server/pa_lab/shot.py | 203 ++++++++++++++ lab/server/pa_lab/timestamps.py | 24 ++ lab/server/pa_lab/tools.py | 99 +++++++ lab/server/tests/fake_lab.py | 131 +++++++++ lab/server/tests/test_config.py | 74 +++++ lab/server/tests/test_ensure_game.py | 80 ++++++ lab/server/tests/test_lab_reader.py | 163 +++++++++++ lab/server/tests/test_mcp_server.py | 263 ++++++++++++++++++ lab/server/tests/test_shot.py | 142 ++++++++++ 15 files changed, 2035 insertions(+), 7 deletions(-) create mode 100644 lab/server/pa_lab/config.py create mode 100644 lab/server/pa_lab/lab_reader.py create mode 100644 lab/server/pa_lab/mcp_server.py create mode 100644 lab/server/pa_lab/shot.py create mode 100644 lab/server/pa_lab/timestamps.py create mode 100644 lab/server/pa_lab/tools.py create mode 100644 lab/server/tests/fake_lab.py create mode 100644 lab/server/tests/test_config.py create mode 100644 lab/server/tests/test_ensure_game.py create mode 100644 lab/server/tests/test_lab_reader.py create mode 100644 lab/server/tests/test_mcp_server.py create mode 100644 lab/server/tests/test_shot.py diff --git a/lab/server/README.md b/lab/server/README.md index 44dcbd5918..c96683bfb0 100644 --- a/lab/server/README.md +++ b/lab/server/README.md @@ -1,8 +1,9 @@ # pa-lab console daemon (`lab/server`) The local server designed in `docs/design/Agent-Integration.md` (fork #131, branch -`design/agent-integration`). This directory is Slice 0 only: the version-1 contracts, golden -examples and a parser. There is no server, no network code and no app change here yet. +`design/agent-integration`). Slice 0: the version-1 contracts, golden examples and a parser. +Slice 2: the attach-only read server ([below](#slice-2-the-attach-only-read-server)). It has no +lease store, no write path and no press: those are Slices 3 and 5. | Path | What | |---|---| @@ -13,9 +14,15 @@ examples and a parser. There is no server, no network code and no app change her | `contracts/v1/legacy/*.state` | Legacy `Lab/state` twins of three `app_state` goldens (`stopped_ui` is the real lab-B file of 2026-11-14) | | `contracts/v1/invalid_cases.json` | Documents that must fail: name, kind, input, expected field path and message | | `tests/test_contracts.py` | Golden parse, round-trip, invalid-case and legacy-mapping tests | +| `pa_lab/config.py` | Server config: the one-entry allowlist (B), loopback port, owner-only token file | +| `pa_lab/lab_reader.py` | Strict reads of `Lab/state.json` and `Lab/save.json`; `console://B/state` and `/save` | +| `pa_lab/tools.py`, `pa_lab/shot.py` | `ensure_game` (verification only) and `shot` (newer than the call) | +| `pa_lab/mcp_server.py` | MCP over Streamable HTTP on `127.0.0.1`: bearer, Host/Origin, sessions, size caps | +| `tests/fake_lab.py` | A fake `Lab/` folder and a fake app answering `shot` requests, in temp dirs | +| `tests/test_{lab_reader,ensure_game,shot,config,mcp_server}.py` | Slice 2's fake-lab tests | -Stdlib only (Python 3.8+), so no venv yet; Slice 2 adds `requirements.txt` and a venv -(`~/.venvs/pa-lab`) for the MCP server. Run the tests from the repo root: +Stdlib only (Python 3.8+), so no venv: the MCP transport is small enough to write on +`http.server`. Run the tests from the repo root: ```sh python3 -m unittest discover -s lab/server/tests -t lab/server -v @@ -110,3 +117,68 @@ New in `state.json`: `written_at` (heartbeat), `instance.{id,pid,profile}`, `pan - Lower-case enums exactly as listed by `python3 -m pa_lab describe app_state`. - Checked by `python3 -m pa_lab check app_state ` and by a native serialization test against the goldens in `contracts/v1/app_state/`. + +## Slice 2: the attach-only read server + +```sh +python3 -m pa_lab init-token ~/.config/pa-lab/token # 0600; never overwritten +python3 -m pa_lab serve --config ~/.config/pa-lab/server.json +``` + +```json +{"schema": 1, "host": "127.0.0.1", "port": 8765, "token_file": "~/.config/pa-lab/token", + "consoles": {"B": {"lab_dir": "~/Library/Application Support/SerialPrograms/Profiles/lab-B/Lab", + "profile": "lab-B"}}} +``` + +The config is the server's own, closed, and must list exactly `B`; it never reads +`~/BDSPLab/consoles.json`. A Claude Code client adds it as an HTTP MCP server at +`http://127.0.0.1:8765/mcp` with the header `Authorization: Bearer `. + +**Transport.** One endpoint, `POST /mcp`, JSON-RPC answered as `application/json` (MCP +2025-06-18 or 2025-03-26). `GET` is 405 (nothing is pushed), `DELETE` ends a session. Each request +needs the bearer token (compared in constant time, never logged), a `Host` of +`127.0.0.1:` or `localhost:` (DNS rebinding), and no `Origin` but the server's own; +bodies over 1 MiB are refused. `initialize` opens an `Mcp-Session-Id` session and records the +client's name, which the log carries with each call. + +**Resources.** `console://B/state` is `console_state`: the app's `Lab/state.json` exactly as +parsed, availability, the reported lease and `blocked`. `console://B/save` is `save_resource`. +A console id is looked up in the allowlist, never turned into a path. + +| What the daemon finds | `console://B/state` | +|---|---| +| no `Lab/state.json` | `unavailable`, `no_state_file` | +| torn/partial file, duplicate key, `NaN`, > 1 MiB, a contract break, another profile's app | `unavailable`, `malformed` (the message names the field) | +| `schema` it does not read | `unavailable`, `unsupported_schema` | +| `instance.pid` not running | `unavailable`, `app_not_running` | +| `written_at` older than 10 s | `unavailable`, `stale_heartbeat` | + +The heartbeat limit is 10 s, not 1 s, because the app writes `state.json` between channel +requests and a long request (`walk`) holds it. A new `instance.id` is the new app: the resource +shows it with its own `frame_seq`; `shot` refuses a call that spans the restart. + +`save.json` missing is `unknown` / `no_fact`. A save fact is `known` / `hooked_save` until the +app shows a UI Start/Stop after `saved_at`, then `stale` / `user_lease`. A `save.json` that +exists but cannot be read is a JSON-RPC error (`-32001`, the refusal in `data`), not `unknown`. + +**Lease, reported only.** With no lease store yet, the lease comes from the app's last +transition: a UI Start/Stop means `user` (no timeout), otherwise `free`. A user lease is not +remembered across an app restart until Slice 3's store. + +**`ensure_game(console, expected, allowed_screens?, max_age_ms=5000)`** reads the app's +`observation.game` / `.screen` and returns them with their ages and `verified` with a `reason` +(`game_unknown`, `game_mismatch`, `screen_unknown`, `screen_not_allowed`, `observation_stale`). +`unknown` never verifies; until the app has detectors, every call says `game_unknown`. + +**`shot(console, max_age_ms=2000, timeout_ms=5000)`** returns the PNG (MCP image content), its +path and `frame_seq_at_least`. The app has no snapshot command yet (#481), so the daemon reads +`(instance.id, frame_seq)` at call start, waits until `state.json` shows a strictly greater +`frame_seq` from the same instance, and only then writes the fixed request `request ` / +`shot frame` into `Lab/inbox` (a read-only line: no owner token). The saved PNG is that frame or +a later one. It is opened only at the path the daemon chose, and only when complete (signature +and `IEND`). Refusals: `timeout` (no newer frame, or the app did not answer; the request is then +withdrawn from the inbox), `video_stale`, `video_bad_signal`, `panel_not_program` and +`controller_not_ready` (the channel's `shot` needs both today), `app_unavailable` (journal +error, incomplete PNG, `instance_replaced`). The exact frame token of the PNG and a snapshot +without a ready controller wait for the app's snapshot command (#131 Slice 1). diff --git a/lab/server/pa_lab/__init__.py b/lab/server/pa_lab/__init__.py index 2d3734198a..40fcaafd67 100644 --- a/lab/server/pa_lab/__init__.py +++ b/lab/server/pa_lab/__init__.py @@ -1 +1 @@ -"""pa-lab console daemon (docs/design/Agent-Integration.md, fork #131). Slice 0: contracts only.""" +"""pa-lab console daemon (docs/design/Agent-Integration.md, fork #131). Slice 0: contracts; Slice 2: the read server.""" diff --git a/lab/server/pa_lab/__main__.py b/lab/server/pa_lab/__main__.py index b59678a0f8..181b7ea5c8 100644 --- a/lab/server/pa_lab/__main__.py +++ b/lab/server/pa_lab/__main__.py @@ -1,8 +1,10 @@ -"""Check or describe version-1 lab contract documents. +"""Check or describe version-1 lab contract documents, or run the read-only lab server. python3 -m pa_lab check app_state ~/Library/Application\\ Support/SerialPrograms/Profiles/lab-B/Lab/state.json python3 -m pa_lab describe app_state python3 -m pa_lab kinds + python3 -m pa_lab init-token ~/.config/pa-lab/token + python3 -m pa_lab serve --config ~/.config/pa-lab/server.json Run from lab/server (or with lab/server on PYTHONPATH). Exit 0 valid, 1 invalid, 2 usage. """ @@ -10,9 +12,10 @@ from __future__ import annotations import argparse +import logging import sys -from pa_lab import contracts +from pa_lab import config, contracts def main(argv=None) -> int: @@ -24,6 +27,10 @@ def main(argv=None) -> int: describe = sub.add_parser('describe', help='print the fields of a kind') describe.add_argument('kind', choices=contracts.KINDS) sub.add_parser('kinds', help='list kinds and who writes them') + init_token = sub.add_parser('init-token', help='write a new owner-only bearer token file') + init_token.add_argument('path') + serve = sub.add_parser('serve', help='run the read-only MCP server (Streamable HTTP on 127.0.0.1)') + serve.add_argument('--config', required=True) args = parser.parse_args(argv) if args.command == 'check': @@ -46,9 +53,43 @@ def main(argv=None) -> int: for kind in contracts.KINDS: print('{:15} {}'.format(kind, contracts.AUTHORS[kind])) return 0 + if args.command == 'init-token': + try: + config.create_token(args.path) + except config.ConfigError as e: + print('error {}'.format(e)) + return 1 + print('wrote {}'.format(args.path)) + return 0 + if args.command == 'serve': + return _serve(args.config) parser.print_help() return 2 +def _serve(path: str) -> int: + from pa_lab import lab_reader, mcp_server + try: + cfg = config.load(path) + token = config.read_token(cfg.token_file) + except config.ConfigError as e: + print('error {}'.format(e)) + return 1 + logging.basicConfig(level=logging.INFO, format='%(asctime)s %(name)s %(message)s') + readers = {name: lab_reader.ConsoleReader(name, entry.lab_dir, profile=entry.profile) + for name, entry in cfg.consoles.items()} + server = mcp_server.make_server(cfg.port, token, readers) + logging.getLogger('pa_lab.server').info('serving %s on http://127.0.0.1:%d%s', + ', '.join(sorted(readers)), server.server_address[1], + mcp_server.ENDPOINT) + try: + server.serve_forever() + except KeyboardInterrupt: + pass + finally: + server.server_close() + return 0 + + if __name__ == '__main__': sys.exit(main()) diff --git a/lab/server/pa_lab/config.py b/lab/server/pa_lab/config.py new file mode 100644 index 0000000000..ed7cf89d4f --- /dev/null +++ b/lab/server/pa_lab/config.py @@ -0,0 +1,111 @@ +"""The daemon's own config (Slice 2 of fork #131): a one-entry allowlist (console B), the loopback +port and the bearer token file. It never reads `~/BDSPLab/consoles.json`, which also lists A. + + {"schema": 1, "host": "127.0.0.1", "port": 8765, "token_file": "~/.config/pa-lab/token", + "consoles": {"B": {"lab_dir": "~/Library/Application Support/SerialPrograms/Profiles/lab-B/Lab", + "profile": "lab-B"}}} +""" + +from __future__ import annotations + +import json +import os +from pathlib import Path +import secrets +import stat +from typing import Dict, Optional + +ALLOWED_CONSOLES = ('B',) +LOOPBACK_HOSTS = ('127.0.0.1',) +TOP_KEYS = ('schema', 'host', 'port', 'token_file', 'consoles') +CONSOLE_KEYS = ('lab_dir', 'profile') + + +class ConfigError(ValueError): + pass + + +class ConsoleConfig: + def __init__(self, lab_dir: Path, profile: Optional[str]): + self.lab_dir = lab_dir + self.profile = profile + + +class Config: + def __init__(self, host: str, port: int, token_file: Path, consoles: Dict[str, ConsoleConfig]): + self.host = host + self.port = port + self.token_file = token_file + self.consoles = consoles + + +def _path(value, field: str) -> Path: + if not isinstance(value, str) or not value: + raise ConfigError('{}: expected a path'.format(field)) + path = Path(os.path.expanduser(value)) + if not path.is_absolute(): + raise ConfigError('{}: {!r} is not an absolute path'.format(field, value)) + return path + + +def load(path: Path) -> Config: + try: + doc = json.loads(Path(path).read_text(encoding='utf-8')) + except (OSError, ValueError) as e: + raise ConfigError('{}: {}'.format(path, e)) + if not isinstance(doc, dict): + raise ConfigError('$: expected an object') + for key in doc: + if key not in TOP_KEYS: + raise ConfigError('{}: unknown key (the config is closed)'.format(key)) + if doc.get('schema') != 1: + raise ConfigError('schema: expected 1, got {!r}'.format(doc.get('schema'))) + host = doc.get('host', '127.0.0.1') + if host not in LOOPBACK_HOSTS: + raise ConfigError('host: {!r} is not loopback; the daemon binds only to 127.0.0.1'.format(host)) + port = doc.get('port') + if isinstance(port, bool) or not isinstance(port, int) or not 0 <= port <= 65535: + raise ConfigError('port: expected 0..65535, got {!r}'.format(port)) + consoles = doc.get('consoles') + if not isinstance(consoles, dict) or sorted(consoles) != sorted(ALLOWED_CONSOLES): + raise ConfigError('consoles: must list exactly {} (console A is never exposed), got {}'.format( + ', '.join(ALLOWED_CONSOLES), sorted(consoles) if isinstance(consoles, dict) else consoles)) + out = {} + for name, entry in consoles.items(): + field = 'consoles.' + name + if not isinstance(entry, dict): + raise ConfigError('{}: expected an object'.format(field)) + for key in entry: + if key not in CONSOLE_KEYS: + raise ConfigError('{}.{}: unknown key'.format(field, key)) + profile = entry.get('profile') + if profile is not None and (not isinstance(profile, str) or not profile): + raise ConfigError('{}.profile: expected a profile name'.format(field)) + out[name] = ConsoleConfig(_path(entry.get('lab_dir'), field + '.lab_dir'), profile) + return Config(host, port, _path(doc.get('token_file'), 'token_file'), out) + + +def read_token(path: Path) -> str: + """The bearer token; refused unless only the owner can read the file.""" + try: + mode = stat.S_IMODE(os.stat(path).st_mode) + token = Path(path).read_text(encoding='utf-8').strip() + except OSError as e: + raise ConfigError('token_file: {}'.format(e)) + if mode & 0o077: + raise ConfigError('token_file: {} has mode {:04o}; it must be owner-only (0600)'.format(path, mode)) + if len(token) < 32: + raise ConfigError('token_file: the token is shorter than 32 characters') + return token + + +def create_token(path: Path) -> None: + """Writes a new random token readable only by the owner. Never overwrites.""" + path = Path(path) + path.parent.mkdir(parents=True, exist_ok=True) + try: + fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600) + except FileExistsError: + raise ConfigError('token_file: {} already exists'.format(path)) + with os.fdopen(fd, 'w') as f: + f.write(secrets.token_urlsafe(32) + '\n') diff --git a/lab/server/pa_lab/lab_reader.py b/lab/server/pa_lab/lab_reader.py new file mode 100644 index 0000000000..0ec55ec185 --- /dev/null +++ b/lab/server/pa_lab/lab_reader.py @@ -0,0 +1,232 @@ +"""Read-only view of one console's `Lab/` folder: `console://B/state` and `console://B/save`. + +Slice 2 of docs/design/Agent-Integration.md (fork #131). The app writes `Lab/state.json` (and a +program that saved writes `Lab/save.json`); this module parses them strictly and builds the +daemon's resources around them, never editing the app's document. Anything it cannot trust +(no file, a torn or malformed file, an unsupported schema, another profile's app, a dead pid, a +stale heartbeat) is an explicit `unavailable` state with the reason, never a guess. + +Slice 2 has no lease store (that is Slice 3), so the lease is only reported: the app's last +transition from a UI Start/Stop means the user holds the console, with no timeout. +""" + +from __future__ import annotations + +import json +import os +from pathlib import Path +from typing import Any, Callable, Dict, List, Optional + +from pa_lab import contracts, timestamps + +MAX_FILE_BYTES = 1 << 20 + +# The app rewrites state.json every 500 ms, but not while it runs a channel request (a `walk` +# can take 5 s), so the heartbeat is judged against a generous limit. +HEARTBEAT_TIMEOUT_S = 10.0 + +BAD_SIGNALS = ('black', 'colour_bars') + + +class Unavailable(Exception): + """A file the daemon cannot use. `reason` is a console_state availability.reason.""" + + def __init__(self, reason: str, message: str, evidence: Optional[Dict[str, Any]] = None): + super().__init__(message) + self.reason = reason + self.message = message + self.evidence = evidence + + def refusal(self) -> Dict[str, Any]: + out = {'code': 'unsupported_schema' if self.reason == 'unsupported_schema' else 'app_unavailable', + 'message': self.message} + if self.evidence is not None: + out['evidence'] = self.evidence + return out + + +def _no_duplicate_keys(pairs): + out = {} + for key, value in pairs: + if key in out: + raise ValueError('duplicate key {!r}'.format(key)) + out[key] = value + return out + + +def _no_constants(name): + raise ValueError('{} is not JSON'.format(name)) + + +def load_strict(path: Path, kind: str) -> Dict[str, Any]: + """One read of a whole file, parsed strictly and checked against the version-1 contract. + + Raises Unavailable with reason no_state_file, malformed or unsupported_schema. + """ + name = 'Lab/' + path.name + try: + with open(path, 'rb') as f: + data = f.read(MAX_FILE_BYTES + 1) + except FileNotFoundError: + raise Unavailable('no_state_file', '{} does not exist.'.format(name)) + except OSError as e: + raise Unavailable('malformed', '{} cannot be read: {}.'.format(name, e.strerror)) + if len(data) > MAX_FILE_BYTES: + raise Unavailable('malformed', '{} is larger than {} bytes.'.format(name, MAX_FILE_BYTES)) + try: + value = json.loads(data.decode('utf-8'), object_pairs_hook=_no_duplicate_keys, + parse_constant=_no_constants) + except (UnicodeDecodeError, ValueError) as e: + raise Unavailable('malformed', '{} is not complete JSON (a partial write?): {}.'.format(name, e)) + if isinstance(value, dict) and 'schema' in value and value['schema'] not in contracts.SUPPORTED_VERSIONS \ + and isinstance(value['schema'], int) and not isinstance(value['schema'], bool): + raise Unavailable('unsupported_schema', '{} has schema {}; this daemon reads {}.'.format( + name, value['schema'], ', '.join(str(v) for v in contracts.SUPPORTED_VERSIONS)), + {'schema': value['schema']}) + try: + return contracts.validate(kind, value).data + except contracts.ContractError as e: + raise Unavailable('malformed', '{} breaks the {} contract: {}.'.format( + name, kind, '; '.join(str(err) for err in e.errors)), {'fields': e.paths()}) + + +def pid_alive(pid: int) -> bool: + try: + os.kill(pid, 0) + except ProcessLookupError: + return False + except PermissionError: + return True + return True + + +def _clock_time(at: str) -> str: + return at[11:16] + + +class ConsoleReader: + """Reads one allowlisted console's `Lab/` folder. Safe to share between threads: it keeps no + state between calls except the last app instance it saw.""" + + def __init__(self, console: str, lab_dir: Path, profile: Optional[str] = None, + now: Callable[[], float] = timestamps.wall_clock, + pid_alive: Callable[[int], bool] = pid_alive, + heartbeat_timeout_s: float = HEARTBEAT_TIMEOUT_S): + self.console = console + self.lab_dir = Path(lab_dir) + self.profile = profile + self.now = now + self.pid_alive = pid_alive + self.heartbeat_timeout_s = heartbeat_timeout_s + + @property + def state_path(self) -> Path: + return self.lab_dir / 'state.json' + + @property + def save_path(self) -> Path: + return self.lab_dir / 'save.json' + + def app_state(self) -> Dict[str, Any]: + """The parsed `Lab/state.json` of a live app, or Unavailable.""" + app = load_strict(self.state_path, 'app_state') + profile = app['instance'].get('profile') + if self.profile is not None and profile is not None and profile != self.profile: + raise Unavailable('malformed', 'Lab/state.json is from profile {!r}, not {!r}.'.format( + profile, self.profile), {'profile': profile}) + pid = app['instance']['pid'] + if not self.pid_alive(pid): + raise Unavailable('app_not_running', 'The app that wrote Lab/state.json (pid {}) is not running.'.format( + pid), {'pid': pid, 'instance_id': app['instance']['id']}) + age = self.now() - timestamps.parse(app['written_at']) + if age > self.heartbeat_timeout_s: + raise Unavailable('stale_heartbeat', 'Lab/state.json was last written {:.1f} s ago (limit {:g} s).'.format( + age, self.heartbeat_timeout_s), {'written_at': app['written_at'], + 'instance_id': app['instance']['id']}) + return app + + def console_state(self) -> Dict[str, Any]: + observed_at = timestamps.format(self.now()) + try: + app = self.app_state() + except Unavailable as e: + doc = {'schema': 1, 'console': self.console, 'observed_at': observed_at, + 'availability': {'state': 'unavailable', 'reason': e.reason}, + 'app': None, 'lease': free_lease(), 'blocked': [_app_unavailable(e)]} + return contracts.validate('console_state', doc).data + lease = reported_lease(app) + doc = {'schema': 1, 'console': self.console, 'observed_at': observed_at, + 'availability': {'state': 'available', 'reason': None}, + 'app': app, 'lease': lease, 'blocked': blocked(self.console, app, lease)} + return contracts.validate('console_state', doc).data + + def save_resource(self) -> Dict[str, Any]: + """`console://B/save`: the last program-authored save fact and whether it still holds. + + A save.json that exists but cannot be read raises Unavailable: it is not "no fact". + """ + if not self.save_path.exists(): + doc = {'schema': 1, 'console': self.console, 'status': 'unknown', 'reason': 'no_fact', + 'since': None, 'fact': None} + return contracts.validate('save_resource', doc).data + fact = load_strict(self.save_path, 'save_fact') + doc = {'schema': 1, 'console': self.console, 'status': 'known', 'reason': 'hooked_save', + 'since': fact['saved_at'], 'fact': fact} + try: + app = self.app_state() + except Unavailable: + app = None + transition = app['program']['last_transition'] if app is not None else None + if transition is not None and transition['source'] == 'ui' and \ + timestamps.parse(transition['at']) > timestamps.parse(fact['saved_at']): + doc.update(status='stale', reason='user_lease', since=transition['at']) + return contracts.validate('save_resource', doc).data + + +def _app_unavailable(e: Unavailable) -> Dict[str, Any]: + out = {'code': 'app_unavailable', 'message': e.message} + if e.evidence is not None: + out['evidence'] = e.evidence + return out + + +def free_lease() -> Dict[str, Any]: + return {'state': 'free', 'owner': None, 'acquired_at': None, 'expires_at': None} + + +def reported_lease(app: Dict[str, Any]) -> Dict[str, Any]: + """The lease as far as this instance's state shows it: a UI Start/Stop hands the console to + the user, with no timeout. Without the Slice 3 store a user lease from before an app restart + is not remembered.""" + transition = app['program']['last_transition'] + if transition is not None and transition['source'] == 'ui': + return {'state': 'user', 'owner': 'user', 'acquired_at': transition['at'], 'expires_at': None} + return free_lease() + + +def blocked(console: str, app: Dict[str, Any], lease: Dict[str, Any]) -> List[Dict[str, Any]]: + """The refusals a leased run_program would get right now, in the order it would check them.""" + out = [] + if lease['state'] == 'user': + transition = app['program']['last_transition'] + out.append({'code': 'console_held_by_user', 'message': + 'The user clicked {} in the app at {}; console {} is theirs until they release it.'.format( + transition['action'].capitalize(), _clock_time(transition['at']), console)}) + state = app['program']['state'] + panel = app['panel']['id'] + if state == 'no_program': + out.append({'code': 'panel_not_program', 'message': 'The selected panel is not a program.'}) + elif state in ('running', 'stopping'): + out.append({'code': 'program_running', 'message': '{} is {}.'.format(panel, state)}) + elif state == 'not_ready': + out.append({'code': 'program_not_stopped', 'message': '{} is still loading.'.format(panel)}) + if app['controller']['state'] != 'ready' and state != 'no_program': + out.append({'code': 'controller_not_ready', 'message': 'The controller is {}.'.format( + app['controller']['state'].replace('_', ' '))}) + video = app['video'] + if video['state'] != 'live': + out.append({'code': 'video_stale', 'message': 'The video is {}.'.format(video['state'])}) + elif video['signal'] in BAD_SIGNALS: + out.append({'code': 'video_bad_signal', 'message': 'The video shows {}.'.format( + video['signal'].replace('_', ' '))}) + return out diff --git a/lab/server/pa_lab/mcp_server.py b/lab/server/pa_lab/mcp_server.py new file mode 100644 index 0000000000..66d3dccbc0 --- /dev/null +++ b/lab/server/pa_lab/mcp_server.py @@ -0,0 +1,393 @@ +"""The attach-only read server: MCP over Streamable HTTP on 127.0.0.1 (Slice 2 of fork #131). + +One POST endpoint, `/mcp`, answering JSON-RPC with `application/json` (no SSE stream: nothing +here pushes). Every request must carry `Authorization: Bearer `, a loopback `Host`, and no +`Origin` other than this server's own; bodies are capped. Sessions follow the spec's +`Mcp-Session-Id`. The bearer token is never logged or returned. + +Resources: `console://B/state` (console_state), `console://B/save` (save_resource). +Tools: `shot`, `ensure_game`. Nothing here presses a button, starts or stops a program, or +holds a lease: those arrive in Slices 3 and 5. +""" + +from __future__ import annotations + +import base64 +from collections import OrderedDict +import hmac +import socketserver +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +import json +import logging +import re +import secrets +import threading +from typing import Any, Callable, Dict, Optional, Tuple + +from pa_lab import contracts, shot, tools +from pa_lab.lab_reader import ConsoleReader, Unavailable + +LOG = logging.getLogger('pa_lab.server') + +ENDPOINT = '/mcp' +MAX_BODY_BYTES = 1 << 20 +MAX_SESSIONS = 64 +PROTOCOL_VERSIONS = ('2025-06-18', '2025-03-26') +SERVER_INFO = {'name': 'pa-lab', 'version': '0.2.0'} +RESOURCE_URI_RE = re.compile(r'^console://([A-Za-z0-9]{1,8})/(state|save)$') + +# JSON-RPC error codes +PARSE_ERROR = -32700 +INVALID_REQUEST = -32600 +METHOD_NOT_FOUND = -32601 +INVALID_PARAMS = -32602 +RESOURCE_UNAVAILABLE = -32001 +RESOURCE_NOT_FOUND = -32002 + +INSTRUCTIONS = ( + 'Read-only view of lab console B. Read console://B/state before acting on the console and ' + 'console://B/save for the last known save. shot returns a PNG newer than the call; ensure_game ' + 'only verifies, it never navigates. Unknown observations are never success.') + +TOOL_LIST = [ + { + 'name': 'shot', + 'title': 'Console screenshot', + 'description': 'A PNG of the console strictly newer than this call. Read-only; needs no lease. ' + 'Refuses on timeout, stale video or a classified bad signal.', + 'inputSchema': { + 'type': 'object', + 'properties': { + 'console': {'type': 'string', 'enum': ['B']}, + 'max_age_ms': {'type': 'integer', 'minimum': 100, 'maximum': 60000, 'default': 2000}, + 'timeout_ms': {'type': 'integer', 'minimum': 100, 'maximum': 60000, 'default': 5000}, + }, + 'required': ['console'], + 'additionalProperties': False, + }, + 'annotations': {'readOnlyHint': True, 'destructiveHint': False, 'idempotentHint': False}, + }, + { + 'name': 'ensure_game', + 'title': 'Verify the game in front', + 'description': "Checks the app's game (and screen) observations against what is expected and " + 'returns them with their age. Verification only: it never goes HOME or launches ' + 'a title. An unknown observation does not verify.', + 'inputSchema': { + 'type': 'object', + 'properties': { + 'console': {'type': 'string', 'enum': ['B']}, + 'expected': {'type': 'string', 'description': "game id, e.g. 'PokemonFRLG'"}, + 'allowed_screens': {'type': 'array', 'items': {'type': 'string'}, 'minItems': 1}, + 'max_age_ms': {'type': 'integer', 'minimum': 100, 'maximum': 600000, 'default': 5000}, + }, + 'required': ['console', 'expected'], + 'additionalProperties': False, + }, + 'annotations': {'readOnlyHint': True, 'destructiveHint': False, 'idempotentHint': True}, + }, +] + + +class RpcError(Exception): + def __init__(self, code: int, message: str, data: Any = None): + super().__init__(message) + self.code = code + self.message = message + self.data = data + + +def refusal_doc(tool: str, refusal: Dict[str, Any]) -> Dict[str, Any]: + return contracts.validate('refusal', {'schema': 1, 'request_id': None, 'tool': tool, + 'refusal': refusal}).data + + +def _json_text(value: Any) -> str: + return json.dumps(value, indent=2, ensure_ascii=False) + + +class LabMcp: + """JSON-RPC methods, without the transport. `consoles` is the allowlist: console id -> reader.""" + + def __init__(self, consoles: Dict[str, ConsoleReader], + take_shot: Callable[..., Dict[str, Any]] = shot.take_shot): + self.consoles = consoles + self.take_shot = take_shot + + def call(self, method: str, params: Dict[str, Any]) -> Dict[str, Any]: + if method == 'ping': + return {} + if method == 'resources/list': + return {'resources': [r for c in sorted(self.consoles) for r in self._resources(c)]} + if method == 'resources/templates/list': + return {'resourceTemplates': []} + if method == 'resources/read': + return self._read_resource(params.get('uri')) + if method == 'tools/list': + return {'tools': TOOL_LIST} + if method == 'tools/call': + return self._call_tool(params.get('name'), params.get('arguments', {})) + raise RpcError(METHOD_NOT_FOUND, 'method not found: {}'.format(method)) + + @staticmethod + def initialize_result(params: Dict[str, Any]) -> Dict[str, Any]: + asked = params.get('protocolVersion') + version = asked if asked in PROTOCOL_VERSIONS else PROTOCOL_VERSIONS[0] + return {'protocolVersion': version, 'capabilities': {'resources': {}, 'tools': {}}, + 'serverInfo': SERVER_INFO, 'instructions': INSTRUCTIONS} + + @staticmethod + def _resources(console: str): + return [ + {'uri': 'console://{}/state'.format(console), 'name': 'console-{}-state'.format(console), + 'title': 'Console {} state'.format(console), 'mimeType': 'application/json', + 'description': "The app's Lab/state.json with availability, the reported lease and what " + 'blocks a run.'}, + {'uri': 'console://{}/save'.format(console), 'name': 'console-{}-save'.format(console), + 'title': 'Console {} save'.format(console), 'mimeType': 'application/json', + 'description': 'The last program-authored save fact: known, stale or unknown.'}, + ] + + def _console(self, console: Any) -> Optional[ConsoleReader]: + # An id is looked up in the allowlist, never turned into a path. + return self.consoles.get(console) if isinstance(console, str) else None + + def _read_resource(self, uri: Any) -> Dict[str, Any]: + match = RESOURCE_URI_RE.match(uri) if isinstance(uri, str) else None + if match is None: + raise RpcError(RESOURCE_NOT_FOUND, 'Resource not found', {'uri': uri}) + reader = self._console(match.group(1)) + if reader is None: + raise RpcError(RESOURCE_NOT_FOUND, 'Resource not found', { + 'uri': uri, 'refusal': {'code': 'console_not_allowed', + 'message': 'Console {} is not served.'.format(match.group(1))}}) + if match.group(2) == 'state': + doc = reader.console_state() + else: + try: + doc = reader.save_resource() + except Unavailable as e: + raise RpcError(RESOURCE_UNAVAILABLE, e.message, {'uri': uri, 'refusal': e.refusal()}) + return {'contents': [{'uri': uri, 'mimeType': 'application/json', 'text': _json_text(doc)}]} + + def _call_tool(self, name: Any, arguments: Any) -> Dict[str, Any]: + if name not in ('shot', 'ensure_game'): + raise RpcError(INVALID_PARAMS, 'Unknown tool: {}'.format(name)) + if not isinstance(arguments, dict): + return self._refused(name, {'code': 'invalid_arguments', 'field': 'arguments', + 'message': 'expected an object'}) + reader = self._console(arguments.get('console')) + if reader is None: + return self._refused(name, {'code': 'console_not_allowed', 'message': + 'Console {!r} is not served; only {}.'.format( + arguments.get('console'), ', '.join(sorted(self.consoles)))}) + try: + if name == 'ensure_game': + result = tools.ensure_game(reader, arguments) + return {'content': [{'type': 'text', 'text': _json_text(result)}], + 'structuredContent': result, 'isError': not result['verified']} + result = self.take_shot(reader, arguments) + except tools.InvalidArguments as e: + return self._refused(name, e.refusal()) + except Unavailable as e: + return self._refused(name, e.refusal()) + except shot.Refused as e: + return self._refused(name, e.refusal) + png = result.pop('png') + return {'content': [{'type': 'image', 'data': base64.b64encode(png).decode('ascii'), + 'mimeType': 'image/png'}, + {'type': 'text', 'text': _json_text(result)}], + 'structuredContent': result, 'isError': False} + + @staticmethod + def _refused(tool: str, refusal: Dict[str, Any]) -> Dict[str, Any]: + doc = refusal_doc(tool, refusal) + return {'content': [{'type': 'text', 'text': _json_text(doc)}], 'structuredContent': doc, + 'isError': True} + + +class Sessions: + def __init__(self): + self._lock = threading.Lock() + self._clients: 'OrderedDict[str, str]' = OrderedDict() + + def open(self, client: str) -> str: + session = secrets.token_hex(16) + with self._lock: + self._clients[session] = client + while len(self._clients) > MAX_SESSIONS: + self._clients.popitem(last=False) + return session + + def client(self, session: str) -> Optional[str]: + with self._lock: + return self._clients.get(session) + + def close(self, session: str) -> bool: + with self._lock: + return self._clients.pop(session, None) is not None + + +class LabHttpServer(ThreadingHTTPServer): + daemon_threads = True + + def __init__(self, address: Tuple[str, int], token: str, mcp: LabMcp): + super().__init__(address, _Handler) + self.token = token + self.mcp = mcp + self.sessions = Sessions() + + def server_bind(self): + # HTTPServer.server_bind looks up the host's FQDN, a reverse DNS call that can hang for + # half a minute on macOS; the name is never used here. + socketserver.TCPServer.server_bind(self) + self.server_name, self.server_port = self.server_address[:2] + + def allowed_authorities(self): + port = self.server_address[1] + return ('127.0.0.1:{}'.format(port), 'localhost:{}'.format(port)) + + +class _Handler(BaseHTTPRequestHandler): + server: LabHttpServer + protocol_version = 'HTTP/1.1' + + def log_message(self, format, *args): # the default writes every request to stderr + LOG.debug('%s %s', self.address_string(), format % args) + + # ---- responses + + def _send(self, status: int, body: Optional[Dict[str, Any]] = None, + headers: Optional[Dict[str, str]] = None) -> None: + data = json.dumps(body).encode('utf-8') if body is not None else b'' + self.send_response(status) + for key, value in (headers or {}).items(): + self.send_header(key, value) + if body is not None: + self.send_header('Content-Type', 'application/json') + self.send_header('Content-Length', str(len(data))) + self.end_headers() + self.wfile.write(data) + + def _http_error(self, status: int, message: str, headers: Optional[Dict[str, str]] = None) -> None: + self._send(status, {'jsonrpc': '2.0', 'id': None, 'error': {'code': INVALID_REQUEST, 'message': message}}, + headers) + + # ---- checks every method shares + + def _gate(self) -> bool: + if self.path != ENDPOINT: + self._http_error(404, 'Not found; the endpoint is {}'.format(ENDPOINT)) + return False + authorities = self.server.allowed_authorities() + if self.headers.get('Host') not in authorities: + self._http_error(403, 'Host must be a loopback address of this server') + return False + origin = self.headers.get('Origin') + if origin is not None and origin not in ['http://' + a for a in authorities]: + self._http_error(403, 'Origin not allowed') + return False + auth = self.headers.get('Authorization', '') + given = auth[len('Bearer '):] if auth.startswith('Bearer ') else '' + if not hmac.compare_digest(given.encode('utf-8'), self.server.token.encode('utf-8')): + self._http_error(401, 'Missing or wrong bearer token', {'WWW-Authenticate': 'Bearer'}) + return False + version = self.headers.get('MCP-Protocol-Version') + if version is not None and version not in PROTOCOL_VERSIONS: + self._http_error(400, 'Unsupported MCP-Protocol-Version {}'.format(version)) + return False + return True + + def _session(self) -> Optional[Tuple[str, str]]: + session = self.headers.get('Mcp-Session-Id') + if session is None: + self._http_error(400, 'Missing Mcp-Session-Id; send initialize first') + return None + client = self.server.sessions.client(session) + if client is None: + self._http_error(404, 'Unknown or ended session') + return None + return session, client + + # ---- methods + + def do_GET(self): + if self._gate(): + self._send(405, None, {'Allow': 'POST, DELETE'}) + + def do_DELETE(self): + if not self._gate(): + return + found = self._session() + if found is not None: + self.server.sessions.close(found[0]) + self._send(200) + + def do_POST(self): + if not self._gate(): + return + length = self.headers.get('Content-Length') + if length is None or not length.isdigit(): + self._http_error(411, 'Content-Length required') + return + if int(length) > MAX_BODY_BYTES: + self.close_connection = True + self._http_error(413, 'Body larger than {} bytes'.format(MAX_BODY_BYTES)) + return + raw = self.rfile.read(int(length)) + if not self.headers.get('Content-Type', '').startswith('application/json'): + self._http_error(415, 'Content-Type must be application/json') + return + try: + message = json.loads(raw.decode('utf-8')) + except (UnicodeDecodeError, ValueError): + self._send(400, {'jsonrpc': '2.0', 'id': None, 'error': {'code': PARSE_ERROR, 'message': 'Parse error'}}) + return + if not isinstance(message, dict) or message.get('jsonrpc') != '2.0': + self._http_error(400, 'Expected one JSON-RPC 2.0 message (batches are not supported)') + return + if 'method' not in message: # a response from the client: nothing asked for one + self._send(202) + return + method = message['method'] + params = message.get('params') or {} + if method == 'initialize': + self._initialize(message, params) + return + found = self._session() + if found is None: + return + if 'id' not in message: # notifications (notifications/initialized, cancelled) + self._send(202) + return + LOG.info('client=%s method=%s tool=%s', found[1], method, + params.get('name') if method == 'tools/call' else '-') + try: + if not isinstance(params, dict): + raise RpcError(INVALID_PARAMS, 'params must be an object') + reply = {'jsonrpc': '2.0', 'id': message['id'], 'result': self.server.mcp.call(method, params)} + except RpcError as e: + error = {'code': e.code, 'message': e.message} + if e.data is not None: + error['data'] = e.data + reply = {'jsonrpc': '2.0', 'id': message['id'], 'error': error} + except Exception: + LOG.exception('method %s failed', method) + reply = {'jsonrpc': '2.0', 'id': message['id'], 'error': {'code': -32603, 'message': 'Internal error'}} + self._send(200, reply) + + def _initialize(self, message: Dict[str, Any], params: Any) -> None: + if 'id' not in message or not isinstance(params, dict): + self._http_error(400, 'initialize must be a request with params') + return + info = params.get('clientInfo') if isinstance(params.get('clientInfo'), dict) else {} + client = str(info.get('name') or 'unnamed')[:64] + session = self.server.sessions.open(client) + LOG.info('client=%s initialize', client) + self._send(200, {'jsonrpc': '2.0', 'id': message['id'], 'result': LabMcp.initialize_result(params)}, + {'Mcp-Session-Id': session}) + + +def make_server(port: int, token: str, consoles: Dict[str, ConsoleReader], **mcp_options) -> LabHttpServer: + """Binds 127.0.0.1 only; port 0 picks a free one (tests).""" + return LabHttpServer(('127.0.0.1', port), token, LabMcp(consoles, **mcp_options)) diff --git a/lab/server/pa_lab/shot.py b/lab/server/pa_lab/shot.py new file mode 100644 index 0000000000..844d5edb80 --- /dev/null +++ b/lab/server/pa_lab/shot.py @@ -0,0 +1,203 @@ +"""`shot`: a console screenshot strictly newer than the call (Slice 2 of fork #131). + +What the app offers today (#481, lab/observation-seam) is the channel's read-only `shot LABEL` +line: it needs no owner token, but it runs only on a console program panel with a ready +controller, and its journal does not name the frame it saved. So the newer-than-call-start rule +is kept this way: + +1. Read `(instance.id, frame_seq)` from `Lab/state.json` at call start. +2. Wait until state.json shows the same instance with a strictly greater `frame_seq` (a new + instance is refused: its sequence restarted). That frame arrived before step 3. +3. Only then write the request `request ` / `shot frame` into `Lab/inbox`; the app saves + its current frame, which is that frame or a later one. +4. Read the journal, check the PNG is complete, and return it with `frame_seq_at_least`. + +The app's frame token for the exact PNG, and a snapshot without a ready controller, wait for +#131 Slice 1's snapshot command. The request is fixed text; no caller input reaches the inbox. +""" + +from __future__ import annotations + +import os +import re +import time +import uuid +from pathlib import Path +from typing import Any, Callable, Dict, Optional, Tuple + +from pa_lab import timestamps +from pa_lab.lab_reader import BAD_SIGNALS, ConsoleReader, Unavailable +from pa_lab.tools import InvalidArguments, check_arguments + +DEFAULT_MAX_AGE_MS = 2000 +DEFAULT_TIMEOUT_MS = 5000 +POLL_S = 0.05 +MAX_PNG_BYTES = 32 << 20 +LABEL = 'frame' +PNG_SIGNATURE = b'\x89PNG\r\n\x1a\n' +PNG_END = b'\x00\x00\x00\x00IEND\xaeB`\x82' +JOURNAL_ERROR_RE = re.compile(r'^error \d+ \([^)]*\): (.*)$') +JOURNAL_OK_RE = re.compile(r'^ok \d+ shot ' + LABEL + r'\b') + +__all__ = ['take_shot', 'Refused', 'InvalidArguments'] + + +class Refused(Exception): + def __init__(self, code: str, message: str, evidence: Optional[Dict[str, Any]] = None): + super().__init__(message) + self.refusal: Dict[str, Any] = {'code': code, 'message': message} + if evidence is not None: + self.refusal['evidence'] = evidence + + +def _check_start(app: Dict[str, Any]) -> None: + video = app['video'] + if video['state'] == 'missing' or video['frame_seq'] is None: + raise Refused('video_stale', 'The app has no video frame (video.state {}).'.format(video['state'])) + if video['signal'] in BAD_SIGNALS: + raise Refused('video_bad_signal', 'The video shows {}.'.format(video['signal'].replace('_', ' '))) + if app['panel']['kind'] != 'program': + raise Refused('panel_not_program', "The selected panel is not a program; the app's shot line " + 'needs a console program panel (no snapshot command yet).') + if app['controller']['state'] != 'ready': + raise Refused('controller_not_ready', "The controller is {}; the app's shot line needs a ready " + 'controller (no snapshot command yet).'.format(app['controller']['state'].replace('_', ' '))) + + +class _Call: + def __init__(self, console: ConsoleReader, timeout_ms: int, sleep: Callable[[float], None]): + self.console = console + self.sleep = sleep + self.started = console.now() + self.deadline = self.started + timeout_ms / 1000.0 + self.timeout_ms = timeout_ms + + def expired(self) -> bool: + return self.console.now() >= self.deadline + + def app_or_none(self) -> Tuple[Optional[Dict[str, Any]], Optional[Unavailable]]: + try: + return self.console.app_state(), None + except Unavailable as e: + return None, e + + +def _wait_for_newer_frame(call: _Call, instance_id: str, start_seq: int) -> Dict[str, Any]: + last_error = None + last_app = None + while True: + app, error = call.app_or_none() + if app is not None: + last_app = app + if app['instance']['id'] != instance_id: + raise Refused('app_unavailable', 'The app restarted during the call; its frames are not ' + 'comparable with the old instance.', { + 'reason': 'instance_replaced', 'instance_id': instance_id, + 'new_instance_id': app['instance']['id']}) + seq = app['video']['frame_seq'] + if seq is not None and seq > start_seq: + return app + else: + last_error = error + if call.expired(): + break + call.sleep(POLL_S) + if last_app is None and last_error is not None: + raise Refused(last_error.refusal()['code'], last_error.message, last_error.evidence) + raise Refused('timeout', 'No frame newer than seq {} within {} ms.'.format(start_seq, call.timeout_ms), + {'instance_id': instance_id, 'frame_seq': start_seq}) + + +def _write_request(lab_dir: Path, name: str, request_id: str) -> Path: + part = lab_dir / 'outbox' / (name + '.part') + inbox = lab_dir / 'inbox' / (name + '.txt') + part.write_text('request {}\nshot {}\n'.format(request_id, LABEL), encoding='utf-8') + os.replace(part, inbox) + return inbox + + +def _withdraw(inbox: Path) -> None: + try: + os.remove(inbox) + except FileNotFoundError: + pass + + +def _wait_for_journal(call: _Call, lab_dir: Path, name: str, inbox: Path) -> str: + journal = lab_dir / 'outbox' / (name + '.out') + while True: + if journal.exists(): + return journal.read_text(encoding='utf-8', errors='replace') + if call.expired(): + break + call.sleep(POLL_S) + _withdraw(inbox) + raise Refused('timeout', 'The app did not answer the shot request within {} ms (busy with another ' + 'request?).'.format(call.timeout_ms), {'request': name}) + + +def _read_png(journal: str, expected: Path) -> bytes: + lines = journal.splitlines() + for line in lines: + match = JOURNAL_ERROR_RE.match(line) + if match: + raise Refused('app_unavailable', "The app's shot line failed: {}".format(match.group(1)), + {'journal': lines}) + if not any(JOURNAL_OK_RE.match(line) for line in lines): + raise Refused('app_unavailable', 'The shot journal has no ok line.', {'journal': lines}) + printed = [line[len('shot '):] for line in lines if line.startswith('shot ')] + if printed == ['(no video frame)']: + raise Refused('video_stale', 'The app had no video frame to save.', {'journal': lines}) + # Only the file this call asked for is opened, never a path read from the journal. + if len(printed) != 1 or Path(printed[0]).name != expected.name: + raise Refused('app_unavailable', 'The shot journal names {!r}, not {}.'.format(printed, expected.name), + {'journal': lines}) + try: + with open(expected, 'rb') as f: + data = f.read(MAX_PNG_BYTES + 1) + except OSError as e: + raise Refused('app_unavailable', 'The saved shot cannot be read: {}.'.format(e.strerror)) + if len(data) > MAX_PNG_BYTES or not data.startswith(PNG_SIGNATURE) or not data.endswith(PNG_END): + raise Refused('app_unavailable', 'The saved shot is not a complete PNG ({} bytes).'.format(len(data))) + return data + + +def take_shot(console: ConsoleReader, arguments: Dict[str, Any], + sleep: Callable[[float], None] = time.sleep, + new_uuid: Callable[[], uuid.UUID] = uuid.uuid4) -> Dict[str, Any]: + """Raises InvalidArguments or Refused (with a contract refusal object).""" + args = check_arguments('shot', arguments) + max_age_ms = args.get('max_age_ms', DEFAULT_MAX_AGE_MS) + call = _Call(console, args.get('timeout_ms', DEFAULT_TIMEOUT_MS), sleep) + try: + app = console.app_state() + except Unavailable as e: + raise Refused(e.refusal()['code'], e.message, e.evidence) + _check_start(app) + instance_id = app['instance']['id'] + start_seq = app['video']['frame_seq'] + + newer = _wait_for_newer_frame(call, instance_id, start_seq) + captured_at = newer['video']['captured_at'] + age_ms = int(round((console.now() - timestamps.parse(captured_at)) * 1000)) + if age_ms > max_age_ms: + raise Refused('video_stale', 'The newest frame is {} ms old (max_age_ms {}).'.format(age_ms, max_age_ms), + {'instance_id': instance_id, 'frame_seq': newer['video']['frame_seq'], + 'captured_at': captured_at}) + + request_id = str(new_uuid()) + name = 'palab_shot_' + request_id.replace('-', '') + inbox = _write_request(console.lab_dir, name, request_id) + journal = _wait_for_journal(call, console.lab_dir, name, inbox) + png_path = console.lab_dir / 'outbox' / '{}_{}.png'.format(name, LABEL) + png = _read_png(journal, png_path) + return { + 'console': console.console, + 'path': str(png_path), + 'png': png, + 'instance_id': instance_id, + 'frame_seq_at_least': newer['video']['frame_seq'], + 'captured_at_at_least': captured_at, + 'call_started_at': timestamps.format(call.started), + 'request': name, + } diff --git a/lab/server/pa_lab/timestamps.py b/lab/server/pa_lab/timestamps.py new file mode 100644 index 0000000000..700af55176 --- /dev/null +++ b/lab/server/pa_lab/timestamps.py @@ -0,0 +1,24 @@ +"""The contract's UTC timestamps (`2026-11-14T06:10:12.124Z`) to and from epoch seconds.""" + +from __future__ import annotations + +import calendar +import datetime +import time + +FORMAT = '%Y-%m-%dT%H:%M:%S.%fZ' + + +def parse(text: str) -> float: + moment = datetime.datetime.strptime(text, FORMAT) + return calendar.timegm(moment.timetuple()) + moment.microsecond / 1e6 + + +def format(epoch: float) -> str: + millis = int(round(epoch * 1000)) + moment = datetime.datetime.utcfromtimestamp(millis // 1000) + return moment.strftime('%Y-%m-%dT%H:%M:%S') + '.{:03d}Z'.format(millis % 1000) + + +def wall_clock() -> float: + return time.time() diff --git a/lab/server/pa_lab/tools.py b/lab/server/pa_lab/tools.py new file mode 100644 index 0000000000..39a13f4dea --- /dev/null +++ b/lab/server/pa_lab/tools.py @@ -0,0 +1,99 @@ +"""The read-only tools of Slice 2 (fork #131): argument checks and `ensure_game`. + +`shot` lives in pa_lab/shot.py. No tool here presses a button, starts or stops a program, or +changes what the app shows; mutating tools arrive with leases (Slices 3 and 5). +""" + +from __future__ import annotations + +from typing import Any, Dict, Optional + +from pa_lab import contracts, timestamps +from pa_lab.contracts import F, Int, ListOf, Obj, Str +from pa_lab.lab_reader import ConsoleReader + +ENSURE_GAME_DEFAULT_MAX_AGE_MS = 5000 + +ARGUMENTS: Dict[str, Obj] = { + 'shot': Obj([ + F('console', Str()), + F('max_age_ms', Int(minimum=100, maximum=60000), required=False, doc='default 2000'), + F('timeout_ms', Int(minimum=100, maximum=60000), required=False, doc='default 5000'), + ], open=False), + 'ensure_game': Obj([ + F('console', Str()), + F('expected', Str(contracts.GAME_ID_RE, 'game id'), doc="e.g. 'PokemonFRLG'"), + F('allowed_screens', ListOf(Str(contracts.GAME_ID_RE, 'screen id'), min_items=1, max_items=32), + required=False), + F('max_age_ms', Int(minimum=100, maximum=600000), required=False, doc='default 5000'), + ], open=False), +} + + +class InvalidArguments(Exception): + def __init__(self, field: str, message: str): + super().__init__('{}: {}'.format(field, message)) + self.field = field + self.message = message + + def refusal(self) -> Dict[str, Any]: + return {'code': 'invalid_arguments', 'field': self.field, 'message': self.message} + + +def check_arguments(tool: str, arguments: Any) -> Dict[str, Any]: + """Closed argument objects: an unknown key is refused, as for every request (README).""" + ctx = contracts._Ctx() + if not isinstance(arguments, dict): + raise InvalidArguments('arguments', 'expected an object') + out = ARGUMENTS[tool].check(arguments, '', ctx) + if ctx.errors: + first = ctx.errors[0] + raise InvalidArguments(first.path, first.message) + return out + + +def _age_ms(observation: Dict[str, Any], now: float) -> Optional[int]: + if observation['observed_at'] is None: + return None + return int(round((now - timestamps.parse(observation['observed_at'])) * 1000)) + + +def ensure_game(console: ConsoleReader, arguments: Dict[str, Any]) -> Dict[str, Any]: + """Verifies, from the app's own observations, that the expected game (and one of the allowed + screens) is in front. Never navigates HOME or launches a title. `unknown` never verifies. + + Raises InvalidArguments, or lab_reader.Unavailable when the app state cannot be trusted. + """ + args = check_arguments('ensure_game', dict(arguments, console=arguments.get('console', console.console))) + max_age_ms = args.get('max_age_ms', ENSURE_GAME_DEFAULT_MAX_AGE_MS) + app = console.app_state() + now = console.now() + game = app['observation']['game'] + screen = app['observation']['screen'] + game_age = _age_ms(game, now) + reason = None + if game['value'] == contracts.UNKNOWN: + reason = 'game_unknown' + elif game_age > max_age_ms: + reason = 'observation_stale' + elif game['value'] != args['expected']: + reason = 'game_mismatch' + elif 'allowed_screens' in args: + screen_age = _age_ms(screen, now) + if screen['value'] == contracts.UNKNOWN: + reason = 'screen_unknown' + elif screen_age > max_age_ms: + reason = 'observation_stale' + elif screen['value'] not in args['allowed_screens']: + reason = 'screen_not_allowed' + return { + 'console': console.console, + 'verified': reason is None, + 'reason': reason, + 'expected': args['expected'], + 'instance_id': app['instance']['id'], + 'game': game, + 'game_age_ms': game_age, + 'screen': screen, + 'screen_age_ms': _age_ms(screen, now), + } diff --git a/lab/server/tests/fake_lab.py b/lab/server/tests/fake_lab.py new file mode 100644 index 0000000000..26534c0785 --- /dev/null +++ b/lab/server/tests/fake_lab.py @@ -0,0 +1,131 @@ +"""A fake lab-B profile folder for the Slice 2 tests: what the app writes into `Lab/`, by hand. + +Everything lives in a temp dir; nothing here touches a real profile or console. +""" + +import copy +import json +import os +from pathlib import Path +import tempfile + +from pa_lab import timestamps + +FIXTURES = Path(__file__).resolve().parent.parent / 'contracts' / 'v1' + + +def golden(kind, name): + return json.loads((FIXTURES / kind / (name + '.json')).read_text(encoding='utf-8')) + + +class FakeClock: + """Epoch seconds the test moves by hand; `sleep` advances it instead of waiting.""" + + def __init__(self, at): + self.t = timestamps.parse(at) + self.on_sleep = [] + + def now(self): + return self.t + + def sleep(self, seconds): + self.t += seconds + for hook in list(self.on_sleep): + hook() + + +class FakeLab: + def __init__(self, test): + self._tmp = tempfile.TemporaryDirectory(prefix='pa-lab-test-') + test.addCleanup(self._tmp.cleanup) + self.dir = Path(self._tmp.name) / 'Lab' + for sub in ('inbox', 'outbox', 'done'): + (self.dir / sub).mkdir(parents=True) + self.state = None + + @property + def state_path(self): + return self.dir / 'state.json' + + @property + def save_path(self): + return self.dir / 'save.json' + + def write_state(self, doc): + """Atomic, as the app does: write beside, then rename.""" + self.state = copy.deepcopy(doc) + self._atomic(self.state_path, json.dumps(doc, indent=2) + '\n') + + def write_save(self, doc): + self._atomic(self.save_path, json.dumps(doc, indent=2) + '\n') + + def write_raw(self, path, text): + """A torn or hand-made file: written in place, not atomically.""" + Path(path).write_text(text, encoding='utf-8') + + def update_state(self, **changes): + """Rewrite state.json with dotted-path changes: update_state(**{'video.frame_seq': 5}).""" + doc = copy.deepcopy(self.state) + for dotted, value in changes.items(): + node = doc + keys = dotted.split('.') + for key in keys[:-1]: + node = node[key] + node[keys[-1]] = value + self.write_state(doc) + + @staticmethod + def _atomic(path, text): + tmp = path.with_name(path.name + '.tmp') + tmp.write_text(text, encoding='utf-8') + os.replace(tmp, path) + + +PNG = b'\x89PNG\r\n\x1a\n' + b'\x00\x00\x00\rIHDR' + b'\x00' * 17 + b'\x00\x00\x00\x00IEND\xaeB`\x82' + + +class FakeApp: + """The app's side of the channel, run on each FakeClock.sleep: a new frame per tick, a fresh + heartbeat, and the inbox's `shot` requests answered as LabChannel does (done/, png, journal). + + Knobs: `frames` (False: the video froze), `serve` (False: the app is busy), `journal_error`, + `no_frame`, `png` (the bytes the app saves). + """ + + def __init__(self, lab, clock): + self.lab = lab + self.clock = clock + self.frames = True + self.serve = True + self.journal_error = None + self.no_frame = False + self.png = PNG + self.requests = [] + clock.on_sleep.append(self.tick) + + def tick(self): + now = timestamps.format(self.clock.now()) + changes = {'written_at': now} + if self.frames: + changes['video.frame_seq'] = self.lab.state['video']['frame_seq'] + 1 + changes['video.captured_at'] = now + self.lab.update_state(**changes) + if self.serve: + for request in sorted((self.lab.dir / 'inbox').glob('*.txt')): + self.answer(request) + + def answer(self, request): + name = request.stem + text = request.read_text(encoding='utf-8') + os.replace(request, self.lab.dir / 'done' / request.name) + self.requests.append(text) + outbox = self.lab.dir / 'outbox' + if self.journal_error is not None: + journal = 'error 2 (shot frame): {}\nend\n'.format(self.journal_error) + elif self.no_frame: + journal = 'shot (no video frame)\nok 2 shot frame @0-3ms\nend\n' + else: + png = outbox / '{}_frame.png'.format(name) + png.write_bytes(self.png) + journal = 'shot {}\nok 2 shot frame @0-41ms\nend\n'.format(png) + (outbox / (name + '.out')).write_text(journal, encoding='utf-8') diff --git a/lab/server/tests/test_config.py b/lab/server/tests/test_config.py new file mode 100644 index 0000000000..e41e8b8293 --- /dev/null +++ b/lab/server/tests/test_config.py @@ -0,0 +1,74 @@ +"""Server config: the B-only allowlist, loopback bind and the bearer token file (Slice 2, fork #131). + +Run from the repo root: python3 -m unittest discover -s lab/server/tests -t lab/server -v +""" + +import json +import os +from pathlib import Path +import tempfile +import unittest + +from pa_lab import config + + +class ConfigTests(unittest.TestCase): + def setUp(self): + tmp = tempfile.TemporaryDirectory(prefix='pa-lab-config-') + self.addCleanup(tmp.cleanup) + self.dir = Path(tmp.name) + self.token = self.dir / 'token' + config.create_token(self.token) + + def write(self, doc): + path = self.dir / 'server.json' + path.write_text(json.dumps(doc), encoding='utf-8') + return path + + def good(self): + return {'schema': 1, 'host': '127.0.0.1', 'port': 8765, 'token_file': str(self.token), + 'consoles': {'B': {'lab_dir': str(self.dir / 'Lab'), 'profile': 'lab-B'}}} + + def test_good_config_loads(self): + loaded = config.load(self.write(self.good())) + self.assertEqual(list(loaded.consoles), ['B']) + self.assertEqual(loaded.consoles['B'].profile, 'lab-B') + self.assertEqual(loaded.port, 8765) + + def test_refused_configs(self): + cases = [ + dict(name='console A listed', input={'consoles.A': {'lab_dir': '/x/Lab'}}, expectation='consoles'), + dict(name='no console', input={'consoles': {}}, expectation='consoles'), + dict(name='bind to every interface', input={'host': '0.0.0.0'}, expectation='host'), + dict(name='relative lab dir', input={'consoles.B': {'lab_dir': 'Lab'}}, expectation='consoles.B.lab_dir'), + dict(name='unknown key', input={'mutations': True}, expectation='mutations'), + dict(name='future schema', input={'schema': 2}, expectation='schema'), + ] + for case in cases: + with self.subTest(case['name']): + doc = self.good() + for dotted, value in case['input'].items(): + node = doc + keys = dotted.split('.') + for key in keys[:-1]: + node = node[key] + node[keys[-1]] = value + with self.assertRaises(config.ConfigError) as raised: + config.load(self.write(doc)) + self.assertIn(case['expectation'], str(raised.exception)) + + def test_token_file_is_owner_only(self): + self.assertEqual(os.stat(self.token).st_mode & 0o777, 0o600) + self.assertGreaterEqual(len(config.read_token(self.token)), 32) + os.chmod(self.token, 0o644) + with self.assertRaises(config.ConfigError) as raised: + config.read_token(self.token) + self.assertIn('0644', str(raised.exception)) + + def test_create_token_never_overwrites(self): + with self.assertRaises(config.ConfigError): + config.create_token(self.token) + + +if __name__ == '__main__': + unittest.main() diff --git a/lab/server/tests/test_ensure_game.py b/lab/server/tests/test_ensure_game.py new file mode 100644 index 0000000000..abba0c1930 --- /dev/null +++ b/lab/server/tests/test_ensure_game.py @@ -0,0 +1,80 @@ +"""ensure_game: read-only verification of the game and screen observations (Slice 2, fork #131). + +Run from the repo root: python3 -m unittest discover -s lab/server/tests -t lab/server -v +""" + +import unittest + +from pa_lab import lab_reader, tools +from tests.fake_lab import FakeClock, FakeLab, golden + +BDSP = {'value': 'PokemonBDSP', 'observed_at': '2026-11-14T07:02:41.000Z', 'detector': 'bdsp_overworld'} +OVERWORLD = {'value': 'overworld', 'observed_at': '2026-11-14T07:02:41.000Z', 'detector': 'bdsp_overworld'} +UNKNOWN = {'value': 'unknown', 'observed_at': None} + + +class EnsureGameTests(unittest.TestCase): + def test_verdicts(self): + cases = [ + dict(name='detectors not there yet', + input=dict(game=UNKNOWN, screen=UNKNOWN, args={'expected': 'PokemonBDSP'}), + expectation=dict(verified=False, reason='game_unknown', age_ms=None)), + dict(name='game matches, no screen asked', + input=dict(game=BDSP, screen=UNKNOWN, args={'expected': 'PokemonBDSP'}), + expectation=dict(verified=True, reason=None, age_ms=1000)), + dict(name='another game', + input=dict(game=BDSP, screen=UNKNOWN, args={'expected': 'PokemonFRLG'}), + expectation=dict(verified=False, reason='game_mismatch', age_ms=1000)), + dict(name='screen allowed', + input=dict(game=BDSP, screen=OVERWORLD, + args={'expected': 'PokemonBDSP', 'allowed_screens': ['overworld', 'menu']}), + expectation=dict(verified=True, reason=None, age_ms=1000)), + dict(name='screen unknown', + input=dict(game=BDSP, screen=UNKNOWN, + args={'expected': 'PokemonBDSP', 'allowed_screens': ['overworld']}), + expectation=dict(verified=False, reason='screen_unknown', age_ms=1000)), + dict(name='screen not allowed', + input=dict(game=BDSP, screen=OVERWORLD, + args={'expected': 'PokemonBDSP', 'allowed_screens': ['battle']}), + expectation=dict(verified=False, reason='screen_not_allowed', age_ms=1000)), + dict(name='observation too old', + input=dict(game=BDSP, screen=UNKNOWN, args={'expected': 'PokemonBDSP', 'max_age_ms': 500}), + expectation=dict(verified=False, reason='observation_stale', age_ms=1000)), + ] + for case in cases: + with self.subTest(case['name']): + lab = FakeLab(self) + lab.state = golden('app_state', 'running_lab') + lab.update_state(**{'observation.game': case['input']['game'], + 'observation.screen': case['input']['screen']}) + console = lab_reader.ConsoleReader('B', lab.dir, profile='lab-B', + now=FakeClock('2026-11-14T07:02:42.000Z').now, + pid_alive=lambda pid: True) + result = tools.ensure_game(console, case['input']['args']) + want = case['expectation'] + self.assertEqual((result['verified'], result['reason'], result['game_age_ms']), + (want['verified'], want['reason'], want['age_ms'])) + self.assertEqual(result['game'], case['input']['game']) + + def test_bad_arguments_name_the_field(self): + cases = [ + dict(name='no expected', input={}, expectation='expected'), + dict(name='expected not an id', input={'expected': 'Pokemon FRLG'}, expectation='expected'), + dict(name='unknown argument', input={'expected': 'PokemonFRLG', 'navigate': True}, + expectation='navigate'), + dict(name='screens not a list', input={'expected': 'PokemonFRLG', 'allowed_screens': 'menu'}, + expectation='allowed_screens'), + ] + lab = FakeLab(self) + lab.write_state(golden('app_state', 'running_lab')) + console = lab_reader.ConsoleReader('B', lab.dir, now=FakeClock('2026-11-14T07:02:42.000Z').now, + pid_alive=lambda pid: True) + for case in cases: + with self.subTest(case['name']): + with self.assertRaises(tools.InvalidArguments) as raised: + tools.ensure_game(console, case['input']) + self.assertEqual(raised.exception.field, case['expectation']) + + +if __name__ == '__main__': + unittest.main() diff --git a/lab/server/tests/test_lab_reader.py b/lab/server/tests/test_lab_reader.py new file mode 100644 index 0000000000..bedd0bb28f --- /dev/null +++ b/lab/server/tests/test_lab_reader.py @@ -0,0 +1,163 @@ +"""console://B/state and console://B/save from a fake Lab/ folder (Slice 2, fork #131). + +Run from the repo root: python3 -m unittest discover -s lab/server/tests -t lab/server -v +""" + +import unittest + +from pa_lab import contracts, lab_reader +from tests.fake_lab import FakeClock, FakeLab, golden + + +def reader(lab, clock, alive=True): + return lab_reader.ConsoleReader('B', lab.dir, profile='lab-B', now=clock.now, + pid_alive=lambda pid: alive) + + +class ConsoleStateTests(unittest.TestCase): + def test_stopped_by_ui_is_the_user_lease_golden(self): + lab = FakeLab(self) + lab.write_state(golden('app_state', 'stopped_ui')) + clock = FakeClock('2026-11-14T06:10:12.400Z') + self.assertEqual(reader(lab, clock).console_state(), golden('console_state', 'available_user_lease')) + + def test_unsupported_schema_is_the_unavailable_golden(self): + lab = FakeLab(self) + doc = golden('app_state', 'stopped_ui') + doc['schema'] = 2 + lab.write_state(doc) + clock = FakeClock('2026-11-14T08:00:00.000Z') + self.assertEqual(reader(lab, clock).console_state(), golden('console_state', 'unavailable')) + + def test_unavailable_states(self): + written_at = '2026-11-14T06:10:12.124Z' + cases = [ + dict(name='no state file', + input=dict(text=None, now=written_at, alive=True), + expectation=dict(reason='no_state_file', contains='does not exist')), + dict(name='partial write', + input=dict(text='{"schema": 1, "written_at": "2026-11-14T06:1', now=written_at, alive=True), + expectation=dict(reason='malformed', contains='not complete JSON')), + dict(name='duplicate key', + input=dict(text='{"schema": 1, "schema": 1}', now=written_at, alive=True), + expectation=dict(reason='malformed', contains='duplicate key')), + dict(name='NaN', + input=dict(text='{"schema": NaN}', now=written_at, alive=True), + expectation=dict(reason='malformed', contains='NaN is not JSON')), + dict(name='contract break', + input=dict(edit={'program.state': 'paused'}, now=written_at, alive=True), + expectation=dict(reason='malformed', contains="program.state: 'paused' is not one of")), + dict(name='another profile', + input=dict(edit={'instance.profile': 'lab-A'}, now=written_at, alive=True), + expectation=dict(reason='malformed', contains="profile 'lab-A'")), + dict(name='dead pid', + input=dict(edit={}, now=written_at, alive=False), + expectation=dict(reason='app_not_running', contains='pid 4411')), + dict(name='stale heartbeat', + input=dict(edit={}, now='2026-11-14T06:10:22.200Z', alive=True), + expectation=dict(reason='stale_heartbeat', contains='10.1 s ago')), + ] + for case in cases: + with self.subTest(case['name']): + lab = FakeLab(self) + given = case['input'] + if 'edit' in given: + lab.state = golden('app_state', 'stopped_ui') + lab.update_state(**given['edit']) + elif given['text'] is not None: + lab.write_raw(lab.state_path, given['text']) + state = reader(lab, FakeClock(given['now']), alive=given['alive']).console_state() + self.assertEqual(state['availability'], {'state': 'unavailable', + 'reason': case['expectation']['reason']}) + self.assertIsNone(state['app']) + self.assertEqual(state['blocked'][0]['code'], 'app_unavailable') + self.assertIn(case['expectation']['contains'], state['blocked'][0]['message']) + + def test_partial_write_recovers_on_the_next_whole_file(self): + lab = FakeLab(self) + clock = FakeClock('2026-11-14T06:10:12.400Z') + whole = golden('app_state', 'stopped_ui') + lab.write_raw(lab.state_path, '{"schema": 1, "writ') + console = reader(lab, clock) + self.assertEqual(console.console_state()['availability']['reason'], 'malformed') + lab.write_state(whole) + self.assertEqual(console.console_state()['app'], whole) + + def test_app_restart_shows_the_new_instance_with_its_own_sequence(self): + lab = FakeLab(self) + clock = FakeClock('2026-11-14T06:10:12.400Z') + lab.write_state(golden('app_state', 'stopped_ui')) + console = reader(lab, clock) + before = console.console_state()['app'] + lab.update_state(**{'instance.id': '11111111-2222-4333-8444-555555555555', 'video.frame_seq': 3, + 'program.last_transition': None}) + after = console.console_state() + self.assertEqual(after['availability']['state'], 'available') + self.assertNotEqual(after['app']['instance']['id'], before['instance']['id']) + self.assertEqual(after['app']['video']['frame_seq'], 3) + self.assertEqual(after['lease']['state'], 'free') + + def test_blocked_lists_what_a_run_would_hit(self): + cases = [ + dict(name='running by lab', input=golden('app_state', 'running_lab'), + expectation=['program_running']), + dict(name='settings panel', input=golden('app_state', 'no_program'), + expectation=['panel_not_program', 'video_stale']), + dict(name='stopped by user', input=golden('app_state', 'stopped_ui'), + expectation=['console_held_by_user']), + ] + for case in cases: + with self.subTest(case['name']): + lab = FakeLab(self) + lab.write_state(case['input']) + clock = FakeClock(case['input']['written_at']) + state = reader(lab, clock).console_state() + self.assertEqual([b['code'] for b in state['blocked']], case['expectation']) + + +class SaveResourceTests(unittest.TestCase): + def setUp(self): + self.lab = FakeLab(self) + self.clock = FakeClock('2026-11-14T06:10:12.400Z') + + def test_no_save_file_is_unknown(self): + self.lab.write_state(golden('app_state', 'stopped_ui')) + self.assertEqual(reader(self.lab, self.clock).save_resource(), golden('save_resource', 'unknown')) + + def test_hooked_save_is_known(self): + self.lab.write_state(golden('app_state', 'running_lab')) + self.clock = FakeClock('2026-11-14T07:02:42.000Z') + self.lab.write_save(golden('save_fact', 'frlg_checkpoint')) + self.assertEqual(reader(self.lab, self.clock).save_resource(), golden('save_resource', 'known')) + + def test_ui_stop_after_the_save_makes_it_stale(self): + self.lab.write_state(golden('app_state', 'stopped_ui')) + self.lab.write_save(golden('save_fact', 'frlg_checkpoint')) + self.assertEqual(reader(self.lab, self.clock).save_resource(), golden('save_resource', 'stale_after_user')) + + def test_save_written_after_the_ui_stop_is_known_again(self): + self.lab.write_state(golden('app_state', 'stopped_ui')) + fact = golden('save_fact', 'frlg_checkpoint') + fact['saved_at'] = '2026-11-14T06:11:00.000Z' + self.lab.write_save(fact) + self.assertEqual(reader(self.lab, self.clock).save_resource()['status'], 'known') + + def test_unreadable_save_file_is_unavailable_not_unknown(self): + cases = [ + dict(name='partial write', input='{"schema": 1, "game": "Pok', + expectation=dict(reason='malformed', code='app_unavailable')), + dict(name='future schema', input='{"schema": 3}', + expectation=dict(reason='unsupported_schema', code='unsupported_schema')), + ] + self.lab.write_state(golden('app_state', 'stopped_ui')) + for case in cases: + with self.subTest(case['name']): + self.lab.write_raw(self.lab.save_path, case['input']) + with self.assertRaises(lab_reader.Unavailable) as raised: + reader(self.lab, self.clock).save_resource() + self.assertEqual(raised.exception.reason, case['expectation']['reason']) + self.assertEqual(raised.exception.refusal()['code'], case['expectation']['code']) + + +if __name__ == '__main__': + unittest.main() diff --git a/lab/server/tests/test_mcp_server.py b/lab/server/tests/test_mcp_server.py new file mode 100644 index 0000000000..766a114b36 --- /dev/null +++ b/lab/server/tests/test_mcp_server.py @@ -0,0 +1,263 @@ +"""The Streamable HTTP endpoint end to end against a fake lab (Slice 2, fork #131): auth, Origin, +sessions, resources, tools, and many readers at once while the app keeps rewriting its files. + +Run from the repo root: python3 -m unittest discover -s lab/server/tests -t lab/server -v +""" + +import base64 +import http.client +import json +import threading +import time +import unittest + +from pa_lab import lab_reader, mcp_server, timestamps +from tests.fake_lab import PNG, FakeApp, FakeLab, golden + +TOKEN = 'test-token-' + 'x' * 32 + + +class WallClock: + """FakeApp's clock in real time: the app thread ticks it, `sleep` really sleeps.""" + + def __init__(self): + self.on_sleep = [] + + def now(self): + return time.time() + + +class Client: + def __init__(self, port, token=TOKEN): + self.port = port + self.token = token + self.session = None + self.next_id = 0 + + def raw(self, method='POST', body=None, headers=None): + conn = http.client.HTTPConnection('127.0.0.1', self.port, timeout=10) + all_headers = {'Authorization': 'Bearer ' + self.token, 'Content-Type': 'application/json', + 'Accept': 'application/json, text/event-stream'} + if self.session is not None: + all_headers['Mcp-Session-Id'] = self.session + all_headers.update(headers or {}) + all_headers = {k: v for k, v in all_headers.items() if v is not None} + data = json.dumps(body).encode('utf-8') if body is not None else None + conn.request(method, '/mcp', body=data, headers=all_headers) + response = conn.getresponse() + payload = response.read() + conn.close() + return response, (json.loads(payload) if payload else None) + + def rpc(self, method, params=None, **headers): + self.next_id += 1 + response, body = self.raw(body={'jsonrpc': '2.0', 'id': self.next_id, 'method': method, + 'params': params or {}}, headers=headers) + return response.status, body + + def initialize(self): + response, body = self.raw(body={'jsonrpc': '2.0', 'id': 0, 'method': 'initialize', 'params': { + 'protocolVersion': '2025-06-18', 'capabilities': {}, 'clientInfo': {'name': 'test'}}}) + self.session = response.getheader('Mcp-Session-Id') + self.raw(body={'jsonrpc': '2.0', 'method': 'notifications/initialized'}) + return response, body + + def read(self, uri): + status, body = self.rpc('resources/read', {'uri': uri}) + if 'error' in body: + return body['error'] + return json.loads(body['result']['contents'][0]['text']) + + def tool(self, name, **arguments): + status, body = self.rpc('tools/call', {'name': name, 'arguments': arguments}) + return body['result'] + + +class ServerTest(unittest.TestCase): + def setUp(self): + self.lab = FakeLab(self) + state = golden('app_state', 'running_lab') + state['written_at'] = timestamps.format(time.time()) + state['video']['captured_at'] = state['written_at'] + self.lab.write_state(state) + self.app = FakeApp(self.lab, WallClock()) + self.stop = threading.Event() + self.app_thread = threading.Thread(target=self._run_app, daemon=True) + self.app_thread.start() + console = lab_reader.ConsoleReader('B', self.lab.dir, profile='lab-B', pid_alive=lambda pid: True) + self.server = mcp_server.make_server(0, TOKEN, {'B': console}) + threading.Thread(target=self.server.serve_forever, daemon=True).start() + self.addCleanup(self._shutdown) + self.client = Client(self.server.server_address[1]) + + def _run_app(self): + for _ in range(2000): # 20 ms ticks, at most 40 s + if self.stop.wait(0.02): + return + self.app.tick() + + def _shutdown(self): + self.stop.set() + self.app_thread.join(5) + self.server.shutdown() + self.server.server_close() + + +class GateTests(ServerTest): + def test_requests_without_the_right_credentials_are_refused(self): + cases = [ + dict(name='no token', input={'Authorization': None}, expectation=401), + dict(name='wrong token', input={'Authorization': 'Bearer nope'}, expectation=401), + dict(name='foreign origin', input={'Origin': 'https://evil.example'}, expectation=403), + dict(name='rebinding host', input={'Host': 'evil.example:80'}, expectation=403), + dict(name='unknown protocol version', input={'MCP-Protocol-Version': '1999-01-01'}, expectation=400), + ] + self.client.initialize() + for case in cases: + with self.subTest(case['name']): + status, body = self.client.rpc('ping', **case['input']) + self.assertEqual(status, case['expectation']) + self.assertNotIn(TOKEN, json.dumps(body)) + + def test_own_origin_is_allowed(self): + self.client.initialize() + status, body = self.client.rpc('ping', Origin='http://127.0.0.1:{}'.format(self.client.port)) + self.assertEqual((status, body['result']), (200, {})) + + def test_session_required_after_initialize(self): + status, _ = self.client.rpc('ping') + self.assertEqual(status, 400) + self.client.session = 'f' * 32 + status, _ = self.client.rpc('ping') + self.assertEqual(status, 404) + + def test_delete_ends_the_session(self): + self.client.initialize() + response, _ = self.client.raw('DELETE') + self.assertEqual(response.status, 200) + status, _ = self.client.rpc('ping') + self.assertEqual(status, 404) + + def test_get_has_no_stream(self): + response, _ = self.client.raw('GET') + self.assertEqual(response.status, 405) + + def test_oversized_body_is_refused(self): + self.client.initialize() + conn = http.client.HTTPConnection('127.0.0.1', self.client.port, timeout=10) + self.addCleanup(conn.close) + conn.putrequest('POST', '/mcp') + for key, value in (('Authorization', 'Bearer ' + TOKEN), ('Content-Type', 'application/json'), + ('Mcp-Session-Id', self.client.session), + ('Content-Length', str(mcp_server.MAX_BODY_BYTES + 1))): + conn.putheader(key, value) + conn.endheaders() + self.assertEqual(conn.getresponse().status, 413) + + +class ProtocolTests(ServerTest): + def setUp(self): + super().setUp() + self.response, self.init = self.client.initialize() + + def test_initialize_offers_resources_and_tools(self): + result = self.init['result'] + self.assertEqual(result['protocolVersion'], '2025-06-18') + self.assertEqual(set(result['capabilities']), {'resources', 'tools'}) + self.assertIsNotNone(self.client.session) + + def test_lists_only_console_b(self): + _, body = self.client.rpc('resources/list') + self.assertEqual([r['uri'] for r in body['result']['resources']], ['console://B/state', 'console://B/save']) + _, body = self.client.rpc('tools/list') + self.assertEqual([t['name'] for t in body['result']['tools']], ['shot', 'ensure_game']) + + def test_state_resource(self): + state = self.client.read('console://B/state') + self.assertEqual(state['availability']['state'], 'available') + self.assertEqual(state['app']['instance']['id'], 'd8ea6a9d-1eab-4a40-b355-d88072b289a1') + + def test_save_resource(self): + self.assertEqual(self.client.read('console://B/save')['status'], 'unknown') + self.lab.write_raw(self.lab.save_path, '{"schema": 1, "ga') + error = self.client.read('console://B/save') + self.assertEqual(error['code'], mcp_server.RESOURCE_UNAVAILABLE) + self.assertEqual(error['data']['refusal']['code'], 'app_unavailable') + + def test_console_a_and_paths_are_not_resources(self): + for uri in ('console://A/state', 'console://B/../../etc/passwd', 'file:///etc/passwd'): + with self.subTest(uri): + self.assertEqual(self.client.read(uri)['code'], mcp_server.RESOURCE_NOT_FOUND) + + def test_tools_refuse_console_a(self): + result = self.client.tool('shot', console='A') + self.assertTrue(result['isError']) + self.assertEqual(result['structuredContent']['refusal']['code'], 'console_not_allowed') + + def test_shot_returns_the_png(self): + result = self.client.tool('shot', console='B') + self.assertFalse(result['isError'], result) + image = result['content'][0] + self.assertEqual((image['type'], image['mimeType']), ('image', 'image/png')) + self.assertEqual(base64.b64decode(image['data']), PNG) + self.assertGreater(result['structuredContent']['frame_seq_at_least'], 921930) + + def test_shot_timeout_is_a_refusal_document(self): + self.app.frames = False + result = self.client.tool('shot', console='B', timeout_ms=300) + self.assertTrue(result['isError']) + self.assertEqual(result['structuredContent']['refusal']['code'], 'timeout') + self.assertEqual(json.loads(result['content'][0]['text']), result['structuredContent']) + + def test_ensure_game(self): + result = self.client.tool('ensure_game', console='B', expected='PokemonBDSP') + self.assertEqual(result['structuredContent']['reason'], 'observation_stale') # the golden's is old + self.assertTrue(result['isError']) + result = self.client.tool('ensure_game', console='B', expected='Pokemon BDSP') + self.assertEqual(result['structuredContent']['refusal']['field'], 'expected') + + def test_unknown_method_and_tool(self): + _, body = self.client.rpc('tools/press') + self.assertEqual(body['error']['code'], mcp_server.METHOD_NOT_FOUND) + _, body = self.client.rpc('tools/call', {'name': 'run_program', 'arguments': {'console': 'B'}}) + self.assertEqual(body['error']['code'], mcp_server.INVALID_PARAMS) + + +class ConcurrencyTests(ServerTest): + def test_many_readers_and_shots_while_the_app_writes(self): + self.client.initialize() + errors = [] + paths = [] + lock = threading.Lock() + + def reader(): + client = Client(self.client.port) + client.initialize() + for _ in range(15): + state = client.read('console://B/state') + if state['availability']['state'] != 'available': + with lock: + errors.append(state['blocked']) + + def shooter(): + client = Client(self.client.port) + client.initialize() + result = client.tool('shot', console='B') + with lock: + if result['isError']: + errors.append(result['structuredContent']) + else: + paths.append(result['structuredContent']['path']) + + threads = [threading.Thread(target=reader) for _ in range(6)] + \ + [threading.Thread(target=shooter) for _ in range(4)] + for thread in threads: + thread.start() + for thread in threads: + thread.join(30) + self.assertEqual(errors, []) + self.assertEqual(len(set(paths)), 4) + + +if __name__ == '__main__': + unittest.main() diff --git a/lab/server/tests/test_shot.py b/lab/server/tests/test_shot.py new file mode 100644 index 0000000000..1add423780 --- /dev/null +++ b/lab/server/tests/test_shot.py @@ -0,0 +1,142 @@ +"""shot: a PNG strictly newer than the call, through the app's channel (Slice 2, fork #131). + +Run from the repo root: python3 -m unittest discover -s lab/server/tests -t lab/server -v +""" + +import unittest + +from pa_lab import lab_reader, shot +from tests.fake_lab import PNG, FakeApp, FakeClock, FakeLab, golden + +START = '2026-11-14T06:10:12.400Z' +NEW_INSTANCE = '11111111-2222-4333-8444-555555555555' + + +class ShotTests(unittest.TestCase): + def setUp(self): + self.lab = FakeLab(self) + self.lab.write_state(golden('app_state', 'stopped_ui')) + self.clock = FakeClock(START) + self.app = FakeApp(self.lab, self.clock) + self.console = lab_reader.ConsoleReader('B', self.lab.dir, profile='lab-B', now=self.clock.now, + pid_alive=lambda pid: True) + + def take(self, **arguments): + return shot.take_shot(self.console, dict(arguments, console='B'), sleep=self.clock.sleep) + + def refusal(self, **arguments): + with self.assertRaises(shot.Refused) as raised: + self.take(**arguments) + return raised.exception.refusal + + def test_returns_a_frame_newer_than_the_call(self): + result = self.take() + self.assertEqual(result['png'], PNG) + self.assertEqual(result['instance_id'], 'd8ea6a9d-1eab-4a40-b355-d88072b289a1') + self.assertGreater(result['frame_seq_at_least'], 918274) + self.assertTrue(result['path'].endswith('_frame.png')) + self.assertEqual(result['call_started_at'], START) + + def test_the_request_only_reads(self): + self.take() + self.assertEqual(len(self.app.requests), 1) + lines = self.app.requests[0].splitlines() + self.assertRegex(lines[0], r'^request [0-9a-f-]{36}$') + self.assertEqual(lines[1:], ['shot frame']) + + def test_no_newer_frame_times_out_before_asking_the_app(self): + self.app.frames = False + refusal = self.refusal() + self.assertEqual(refusal, golden('refusal', 'shot_timeout')['refusal']) + self.assertEqual(self.app.requests, []) + + def test_sequence_going_back_in_one_instance_is_not_newer(self): + self.app.frames = False + self.lab.update_state(**{'video.frame_seq': 5}) + with self.assertRaises(shot.Refused) as raised: + shot.take_shot(self.console, {'console': 'B', 'timeout_ms': 300}, sleep=self._reset_then_sleep) + self.assertEqual(raised.exception.refusal['code'], 'timeout') + + def _reset_then_sleep(self, seconds): + self.lab.update_state(**{'video.frame_seq': 2}) + self.clock.sleep(seconds) + + def test_app_restart_while_waiting_is_refused(self): + self.app.frames = False + self.clock.on_sleep.append(lambda: self.lab.update_state(**{'instance.id': NEW_INSTANCE, + 'video.frame_seq': 1})) + refusal = self.refusal() + self.assertEqual(refusal['code'], 'app_unavailable') + self.assertEqual(refusal['evidence']['reason'], 'instance_replaced') + self.assertEqual(refusal['evidence']['new_instance_id'], NEW_INSTANCE) + + def test_partial_state_file_while_waiting_is_tolerated(self): + torn = {'n': 0} + + def tear_once(): + if torn['n'] == 0: + self.lab.write_raw(self.lab.state_path, '{"schema": 1, "writ') + torn['n'] += 1 + self.clock.on_sleep.append(tear_once) + self.assertEqual(self.take()['png'], PNG) + + def test_busy_app_times_out_and_the_request_is_withdrawn(self): + self.app.serve = False + refusal = self.refusal(timeout_ms=1000) + self.assertEqual(refusal['code'], 'timeout') + self.assertIn('did not answer', refusal['message']) + self.assertEqual(list((self.lab.dir / 'inbox').glob('*.txt')), []) + + def test_app_failures(self): + cases = [ + dict(name='journal error', input=dict(journal_error='Controller is not ready.'), + expectation=dict(code='app_unavailable', contains='Controller is not ready.')), + dict(name='no frame', input=dict(no_frame=True), + expectation=dict(code='video_stale', contains='no video frame')), + dict(name='truncated png', input=dict(png=PNG[:20]), + expectation=dict(code='app_unavailable', contains='not a complete PNG')), + ] + for case in cases: + with self.subTest(case['name']): + self.setUp() + for knob, value in case['input'].items(): + setattr(self.app, knob, value) + refusal = self.refusal() + self.assertEqual(refusal['code'], case['expectation']['code']) + self.assertIn(case['expectation']['contains'], refusal['message']) + + def test_refused_before_waiting(self): + cases = [ + dict(name='video missing', input={'video.state': 'missing', 'video.frame_seq': None, + 'video.captured_at': None}, + expectation='video_stale'), + dict(name='black screen', input={'video.signal': 'black'}, expectation='video_bad_signal'), + dict(name='controller not ready', input={'controller.state': 'not_connected'}, + expectation='controller_not_ready'), + dict(name='settings panel', input={'panel.kind': 'other', 'panel.id': None, + 'program.state': 'no_program'}, + expectation='panel_not_program'), + dict(name='future schema', input={'schema': 2}, expectation='unsupported_schema'), + ] + for case in cases: + with self.subTest(case['name']): + self.setUp() + self.lab.update_state(**case['input']) + self.assertEqual(self.refusal()['code'], case['expectation']) + self.assertEqual(self.app.requests, []) + + def test_newer_frame_older_than_max_age_is_stale(self): + self.app.frames = False + self.clock.on_sleep.append(lambda: self.lab.update_state(**{ + 'video.frame_seq': 918275, 'video.captured_at': '2026-11-14T06:10:09.000Z'})) + refusal = self.refusal() + self.assertEqual(refusal['code'], 'video_stale') + + def test_bad_arguments(self): + with self.assertRaises(shot.InvalidArguments) as raised: + self.take(timeout_ms=10 ** 9) + self.assertEqual(raised.exception.field, 'timeout_ms') + + +if __name__ == '__main__': + unittest.main() From cbfccc2ac68e0c0e7cd214aa991da250faf067f7 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sat, 14 Nov 2026 02:50:33 -0800 Subject: [PATCH 2/3] lab/server: shot uses the app's snapshot command (#481) shot now sends `snapshot frame ` at once and returns the exact frame_seq / captured_at from the `snapshot saved` line. The panel and controller refusals are gone; the app's timeout and unavailable replies map to timeout, video_stale and app_unavailable (evidence.reason), and a reply from another instance is instance_replaced. Only the expected outbox path is opened. The fake app answers snapshot requests as LabChannel does. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- lab/server/README.md | 24 +-- lab/server/pa_lab/mcp_server.py | 2 +- lab/server/pa_lab/shot.py | 218 ++++++++++++++-------------- lab/server/tests/fake_lab.py | 69 +++++++-- lab/server/tests/test_mcp_server.py | 2 +- lab/server/tests/test_shot.py | 132 ++++++++++------- 6 files changed, 253 insertions(+), 194 deletions(-) diff --git a/lab/server/README.md b/lab/server/README.md index c96683bfb0..78ea12ccb5 100644 --- a/lab/server/README.md +++ b/lab/server/README.md @@ -18,7 +18,7 @@ lease store, no write path and no press: those are Slices 3 and 5. | `pa_lab/lab_reader.py` | Strict reads of `Lab/state.json` and `Lab/save.json`; `console://B/state` and `/save` | | `pa_lab/tools.py`, `pa_lab/shot.py` | `ensure_game` (verification only) and `shot` (newer than the call) | | `pa_lab/mcp_server.py` | MCP over Streamable HTTP on `127.0.0.1`: bearer, Host/Origin, sessions, size caps | -| `tests/fake_lab.py` | A fake `Lab/` folder and a fake app answering `shot` requests, in temp dirs | +| `tests/fake_lab.py` | A fake `Lab/` folder and a fake app answering `snapshot` requests, in temp dirs | | `tests/test_{lab_reader,ensure_game,shot,config,mcp_server}.py` | Slice 2's fake-lab tests | Stdlib only (Python 3.8+), so no venv: the MCP transport is small enough to write on @@ -172,13 +172,15 @@ remembered across an app restart until Slice 3's store. `unknown` never verifies; until the app has detectors, every call says `game_unknown`. **`shot(console, max_age_ms=2000, timeout_ms=5000)`** returns the PNG (MCP image content), its -path and `frame_seq_at_least`. The app has no snapshot command yet (#481), so the daemon reads -`(instance.id, frame_seq)` at call start, waits until `state.json` shows a strictly greater -`frame_seq` from the same instance, and only then writes the fixed request `request ` / -`shot frame` into `Lab/inbox` (a read-only line: no owner token). The saved PNG is that frame or -a later one. It is opened only at the path the daemon chose, and only when complete (signature -and `IEND`). Refusals: `timeout` (no newer frame, or the app did not answer; the request is then -withdrawn from the inbox), `video_stale`, `video_bad_signal`, `panel_not_program` and -`controller_not_ready` (the channel's `shot` needs both today), `app_unavailable` (journal -error, incomplete PNG, `instance_replaced`). The exact frame token of the PNG and a snapshot -without a ready controller wait for the app's snapshot command (#131 Slice 1). +path and the exact `frame_seq` and `captured_at` of that frame. The daemon checks `state.json` +once (the app is up; its `instance.id`), then writes the fixed request `request ` / +`snapshot frame ` into `Lab/inbox` at once. The app's `snapshot` command (#481, +`Lab.md` "Snapshot") needs no owner token, program state or controller: it waits for the first +frame after the line starts, saves it and prints `snapshot saved instance=... frame_seq=... +captured_at=... after=... path=...`. The daemon opens only the path it chose, never the one the +journal names, and only when complete (signature and `IEND`). Refusals: `timeout` (the app's +`snapshot timeout`, evidence `{instance_id, frame_seq: after}`; or the app did not answer within +`timeout_ms` + 2 s, and the request is withdrawn from the inbox), `video_stale` (`reason=no_video`, +or the saved frame is older than `max_age_ms`), `video_bad_signal`, `app_unavailable` (a reply +from another instance: `evidence.reason` `instance_replaced`; `panel_changed`, `app_closing`, +`save_failed` as `evidence.reason`; a line error or an incomplete PNG). diff --git a/lab/server/pa_lab/mcp_server.py b/lab/server/pa_lab/mcp_server.py index 66d3dccbc0..6e1383eb7d 100644 --- a/lab/server/pa_lab/mcp_server.py +++ b/lab/server/pa_lab/mcp_server.py @@ -53,7 +53,7 @@ { 'name': 'shot', 'title': 'Console screenshot', - 'description': 'A PNG of the console strictly newer than this call. Read-only; needs no lease. ' + 'description': 'The first console frame after this call starts, with its frame_seq. Read-only; needs no lease. ' 'Refuses on timeout, stale video or a classified bad signal.', 'inputSchema': { 'type': 'object', diff --git a/lab/server/pa_lab/shot.py b/lab/server/pa_lab/shot.py index 844d5edb80..8595012cf5 100644 --- a/lab/server/pa_lab/shot.py +++ b/lab/server/pa_lab/shot.py @@ -1,19 +1,19 @@ -"""`shot`: a console screenshot strictly newer than the call (Slice 2 of fork #131). - -What the app offers today (#481, lab/observation-seam) is the channel's read-only `shot LABEL` -line: it needs no owner token, but it runs only on a console program panel with a ready -controller, and its journal does not name the frame it saved. So the newer-than-call-start rule -is kept this way: - -1. Read `(instance.id, frame_seq)` from `Lab/state.json` at call start. -2. Wait until state.json shows the same instance with a strictly greater `frame_seq` (a new - instance is refused: its sequence restarted). That frame arrived before step 3. -3. Only then write the request `request ` / `shot frame` into `Lab/inbox`; the app saves - its current frame, which is that frame or a later one. -4. Read the journal, check the PNG is complete, and return it with `frame_seq_at_least`. - -The app's frame token for the exact PNG, and a snapshot without a ready controller, wait for -#131 Slice 1's snapshot command. The request is fixed text; no caller input reaches the inbox. +"""`shot`: the console's first frame after the call starts (Slice 2 of fork #131). + +The app's channel command `snapshot LABEL TIMEOUT_MS` (#481, Lab.md "Snapshot") waits for the +first video frame that arrives after the line starts, saves it and names it with the same +`instance.id` and `frame_seq` that `Lab/state.json` uses. It needs no owner token, program state +or controller. So: + +1. Read `Lab/state.json` at call start: the app must be up (fresh heartbeat), and its + `instance.id` is the one the reply must name. +2. Write the request `request ` / `snapshot frame ` into `Lab/inbox` at once. +3. Read the journal: `snapshot saved ...` gives the exact `frame_seq` and `captured_at`; + `snapshot timeout` and `snapshot unavailable` map to refusals. +4. Open only the PNG this call asked for, never a path read from the journal, check it is + complete, and return it. + +The request is fixed text; no caller input but the checked `timeout_ms` reaches the inbox. """ from __future__ import annotations @@ -23,7 +23,7 @@ import time import uuid from pathlib import Path -from typing import Any, Callable, Dict, Optional, Tuple +from typing import Any, Callable, Dict, List, Optional from pa_lab import timestamps from pa_lab.lab_reader import BAD_SIGNALS, ConsoleReader, Unavailable @@ -31,13 +31,21 @@ DEFAULT_MAX_AGE_MS = 2000 DEFAULT_TIMEOUT_MS = 5000 +# The app reads its inbox every 500 ms and its own wait starts when the line does; the journal +# may come this long after the caller's timeout. +ANSWER_GRACE_MS = 2000 POLL_S = 0.05 MAX_PNG_BYTES = 32 << 20 LABEL = 'frame' PNG_SIGNATURE = b'\x89PNG\r\n\x1a\n' PNG_END = b'\x00\x00\x00\x00IEND\xaeB`\x82' JOURNAL_ERROR_RE = re.compile(r'^error \d+ \([^)]*\): (.*)$') -JOURNAL_OK_RE = re.compile(r'^ok \d+ shot ' + LABEL + r'\b') +JOURNAL_OK_RE = re.compile(r'^ok \d+ snapshot ' + LABEL + r'\b') +SAVED_RE = re.compile(r'^snapshot saved instance=(\S+) frame_seq=(\d+) captured_at=(\S+) after=(\d+) path=(.+)$') +TIMEOUT_RE = re.compile(r'^snapshot timeout instance=(\S+) after=(\d+) timeout_ms=(\d+)$') +UNAVAILABLE_RE = re.compile(r'^snapshot unavailable instance=(\S+) reason=(\S+)$') +# `snapshot unavailable` reasons the app has no frame for; the rest mean the app could not serve. +APP_REASONS = ('panel_changed', 'app_closing', 'save_failed') __all__ = ['take_shot', 'Refused', 'InvalidArguments'] @@ -51,67 +59,15 @@ def __init__(self, code: str, message: str, evidence: Optional[Dict[str, Any]] = def _check_start(app: Dict[str, Any]) -> None: - video = app['video'] - if video['state'] == 'missing' or video['frame_seq'] is None: - raise Refused('video_stale', 'The app has no video frame (video.state {}).'.format(video['state'])) - if video['signal'] in BAD_SIGNALS: - raise Refused('video_bad_signal', 'The video shows {}.'.format(video['signal'].replace('_', ' '))) - if app['panel']['kind'] != 'program': - raise Refused('panel_not_program', "The selected panel is not a program; the app's shot line " - 'needs a console program panel (no snapshot command yet).') - if app['controller']['state'] != 'ready': - raise Refused('controller_not_ready', "The controller is {}; the app's shot line needs a ready " - 'controller (no snapshot command yet).'.format(app['controller']['state'].replace('_', ' '))) - - -class _Call: - def __init__(self, console: ConsoleReader, timeout_ms: int, sleep: Callable[[float], None]): - self.console = console - self.sleep = sleep - self.started = console.now() - self.deadline = self.started + timeout_ms / 1000.0 - self.timeout_ms = timeout_ms - - def expired(self) -> bool: - return self.console.now() >= self.deadline - - def app_or_none(self) -> Tuple[Optional[Dict[str, Any]], Optional[Unavailable]]: - try: - return self.console.app_state(), None - except Unavailable as e: - return None, e - - -def _wait_for_newer_frame(call: _Call, instance_id: str, start_seq: int) -> Dict[str, Any]: - last_error = None - last_app = None - while True: - app, error = call.app_or_none() - if app is not None: - last_app = app - if app['instance']['id'] != instance_id: - raise Refused('app_unavailable', 'The app restarted during the call; its frames are not ' - 'comparable with the old instance.', { - 'reason': 'instance_replaced', 'instance_id': instance_id, - 'new_instance_id': app['instance']['id']}) - seq = app['video']['frame_seq'] - if seq is not None and seq > start_seq: - return app - else: - last_error = error - if call.expired(): - break - call.sleep(POLL_S) - if last_app is None and last_error is not None: - raise Refused(last_error.refusal()['code'], last_error.message, last_error.evidence) - raise Refused('timeout', 'No frame newer than seq {} within {} ms.'.format(start_seq, call.timeout_ms), - {'instance_id': instance_id, 'frame_seq': start_seq}) + signal = app['video']['signal'] + if signal in BAD_SIGNALS: + raise Refused('video_bad_signal', 'The video shows {}.'.format(signal.replace('_', ' '))) -def _write_request(lab_dir: Path, name: str, request_id: str) -> Path: +def _write_request(lab_dir: Path, name: str, request_id: str, timeout_ms: int) -> Path: part = lab_dir / 'outbox' / (name + '.part') inbox = lab_dir / 'inbox' / (name + '.txt') - part.write_text('request {}\nshot {}\n'.format(request_id, LABEL), encoding='utf-8') + part.write_text('request {}\nsnapshot {} {}\n'.format(request_id, LABEL, timeout_ms), encoding='utf-8') os.replace(part, inbox) return inbox @@ -123,42 +79,83 @@ def _withdraw(inbox: Path) -> None: pass -def _wait_for_journal(call: _Call, lab_dir: Path, name: str, inbox: Path) -> str: +def _wait_for_journal(console: ConsoleReader, sleep: Callable[[float], None], deadline: float, + lab_dir: Path, name: str, inbox: Path) -> List[str]: journal = lab_dir / 'outbox' / (name + '.out') while True: if journal.exists(): - return journal.read_text(encoding='utf-8', errors='replace') - if call.expired(): + return journal.read_text(encoding='utf-8', errors='replace').splitlines() + if console.now() >= deadline: break - call.sleep(POLL_S) + sleep(POLL_S) _withdraw(inbox) - raise Refused('timeout', 'The app did not answer the shot request within {} ms (busy with another ' - 'request?).'.format(call.timeout_ms), {'request': name}) + raise Refused('timeout', 'The app did not answer the snapshot request in time (busy with another ' + 'request?).', {'request': name}) + + +def _check_instance(reply_instance: str, instance_id: str) -> None: + if reply_instance != instance_id: + raise Refused('app_unavailable', 'The app restarted during the call; its frames are not ' + 'comparable with the old instance.', { + 'reason': 'instance_replaced', 'instance_id': instance_id, + 'new_instance_id': reply_instance}) -def _read_png(journal: str, expected: Path) -> bytes: - lines = journal.splitlines() +def _refuse_failed_reply(lines: List[str], instance_id: str) -> None: + """Raises the refusal for a `snapshot timeout` or `snapshot unavailable` line, if any.""" + for line in lines: + match = TIMEOUT_RE.match(line) + if match: + _check_instance(match.group(1), instance_id) + after = int(match.group(2)) + raise Refused('timeout', 'No frame newer than seq {} within {} ms.'.format(after, match.group(3)), + {'instance_id': instance_id, 'frame_seq': after}) + match = UNAVAILABLE_RE.match(line) + if match: + _check_instance(match.group(1), instance_id) + reason = match.group(2) + if reason == 'no_video': + raise Refused('video_stale', 'The selected panel has no video.', + {'instance_id': instance_id, 'reason': reason}) + if reason in APP_REASONS: + raise Refused('app_unavailable', 'The app could not save a frame ({}).'.format( + reason.replace('_', ' ')), {'instance_id': instance_id, 'reason': reason}) + raise Refused('app_unavailable', 'The app gave an unknown snapshot reason {!r}.'.format(reason), + {'instance_id': instance_id, 'reason': 'unknown', 'journal': lines}) + + +def _parse_saved(lines: List[str], instance_id: str, expected: Path) -> Dict[str, Any]: + _refuse_failed_reply(lines, instance_id) for line in lines: match = JOURNAL_ERROR_RE.match(line) if match: - raise Refused('app_unavailable', "The app's shot line failed: {}".format(match.group(1)), + raise Refused('app_unavailable', "The app's snapshot line failed: {}".format(match.group(1)), {'journal': lines}) - if not any(JOURNAL_OK_RE.match(line) for line in lines): - raise Refused('app_unavailable', 'The shot journal has no ok line.', {'journal': lines}) - printed = [line[len('shot '):] for line in lines if line.startswith('shot ')] - if printed == ['(no video frame)']: - raise Refused('video_stale', 'The app had no video frame to save.', {'journal': lines}) - # Only the file this call asked for is opened, never a path read from the journal. - if len(printed) != 1 or Path(printed[0]).name != expected.name: - raise Refused('app_unavailable', 'The shot journal names {!r}, not {}.'.format(printed, expected.name), + saved = [m for m in (SAVED_RE.match(line) for line in lines) if m] + if len(saved) != 1 or not any(JOURNAL_OK_RE.match(line) for line in lines): + raise Refused('app_unavailable', 'The snapshot journal has no single saved line and ok line.', {'journal': lines}) + match = saved[0] + _check_instance(match.group(1), instance_id) + frame_seq, after = int(match.group(2)), int(match.group(4)) try: - with open(expected, 'rb') as f: + timestamps.parse(match.group(3)) + except ValueError: + raise Refused('app_unavailable', 'The snapshot names a bad capture time.', {'journal': lines}) + # The journal's path is compared by name only; the file opened is the one this call asked for. + if frame_seq <= after or Path(match.group(5)).name != expected.name: + raise Refused('app_unavailable', 'The snapshot line does not match this request.', {'journal': lines}) + return {'frame_seq': frame_seq, 'captured_at': match.group(3)} + + +def _read_png(path: Path) -> bytes: + try: + with open(path, 'rb') as f: data = f.read(MAX_PNG_BYTES + 1) except OSError as e: - raise Refused('app_unavailable', 'The saved shot cannot be read: {}.'.format(e.strerror)) + raise Refused('app_unavailable', 'The saved snapshot cannot be read: {}.'.format(e.strerror)) if len(data) > MAX_PNG_BYTES or not data.startswith(PNG_SIGNATURE) or not data.endswith(PNG_END): - raise Refused('app_unavailable', 'The saved shot is not a complete PNG ({} bytes).'.format(len(data))) + raise Refused('app_unavailable', 'The saved snapshot is not a complete PNG ({} bytes).'.format(len(data))) return data @@ -168,36 +165,33 @@ def take_shot(console: ConsoleReader, arguments: Dict[str, Any], """Raises InvalidArguments or Refused (with a contract refusal object).""" args = check_arguments('shot', arguments) max_age_ms = args.get('max_age_ms', DEFAULT_MAX_AGE_MS) - call = _Call(console, args.get('timeout_ms', DEFAULT_TIMEOUT_MS), sleep) + timeout_ms = args.get('timeout_ms', DEFAULT_TIMEOUT_MS) + started = console.now() try: app = console.app_state() except Unavailable as e: raise Refused(e.refusal()['code'], e.message, e.evidence) _check_start(app) instance_id = app['instance']['id'] - start_seq = app['video']['frame_seq'] - - newer = _wait_for_newer_frame(call, instance_id, start_seq) - captured_at = newer['video']['captured_at'] - age_ms = int(round((console.now() - timestamps.parse(captured_at)) * 1000)) - if age_ms > max_age_ms: - raise Refused('video_stale', 'The newest frame is {} ms old (max_age_ms {}).'.format(age_ms, max_age_ms), - {'instance_id': instance_id, 'frame_seq': newer['video']['frame_seq'], - 'captured_at': captured_at}) request_id = str(new_uuid()) name = 'palab_shot_' + request_id.replace('-', '') - inbox = _write_request(console.lab_dir, name, request_id) - journal = _wait_for_journal(call, console.lab_dir, name, inbox) + inbox = _write_request(console.lab_dir, name, request_id, timeout_ms) + deadline = started + (timeout_ms + ANSWER_GRACE_MS) / 1000.0 + lines = _wait_for_journal(console, sleep, deadline, console.lab_dir, name, inbox) png_path = console.lab_dir / 'outbox' / '{}_{}.png'.format(name, LABEL) - png = _read_png(journal, png_path) + frame = _parse_saved(lines, instance_id, png_path) + age_ms = int(round((console.now() - timestamps.parse(frame['captured_at'])) * 1000)) + if age_ms > max_age_ms: + raise Refused('video_stale', 'The saved frame is {} ms old (max_age_ms {}).'.format(age_ms, max_age_ms), + dict(frame, instance_id=instance_id)) return { 'console': console.console, 'path': str(png_path), - 'png': png, + 'png': _read_png(png_path), 'instance_id': instance_id, - 'frame_seq_at_least': newer['video']['frame_seq'], - 'captured_at_at_least': captured_at, - 'call_started_at': timestamps.format(call.started), + 'frame_seq': frame['frame_seq'], + 'captured_at': frame['captured_at'], + 'call_started_at': timestamps.format(started), 'request': name, } diff --git a/lab/server/tests/fake_lab.py b/lab/server/tests/fake_lab.py index 26534c0785..72c72ea900 100644 --- a/lab/server/tests/fake_lab.py +++ b/lab/server/tests/fake_lab.py @@ -86,10 +86,14 @@ def _atomic(path, text): class FakeApp: """The app's side of the channel, run on each FakeClock.sleep: a new frame per tick, a fresh - heartbeat, and the inbox's `shot` requests answered as LabChannel does (done/, png, journal). - - Knobs: `frames` (False: the video froze), `serve` (False: the app is busy), `journal_error`, - `no_frame`, `png` (the bytes the app saves). + heartbeat, and the inbox's `snapshot LABEL TIMEOUT_MS` requests answered as LabChannel does + (Lab.md "Snapshot"): the request moves to done/, and the first frame newer than the line's + start is saved as `_