146 lines
5.4 KiB
Python
146 lines
5.4 KiB
Python
#!/usr/bin/env python3
|
|
"""Black-box consumer for Marqdo Execution Events v1 (RFC-OBS-0001).
|
|
|
|
This is an independent consumer: it imports only the Python standard library
|
|
and the `jsonschema` package, never the Rust workspace, and it consumes the
|
|
output of a released `marqdo` binary (or a checked-in fixture).
|
|
|
|
Usage:
|
|
execution_events_consumer.py EVENTS.jsonl
|
|
execution_events_consumer.py - # read stdin
|
|
execution_events_consumer.py --schema-check FILE.jsonl
|
|
|
|
Checks:
|
|
* every line is one JSON object validated against
|
|
`spec/schemas/execution-events-v1.schema.json`;
|
|
* `stream.opened` is first (seq 0), `run.started` occurs at most once,
|
|
exactly one terminal event on a complete stream, nothing follows it;
|
|
* `seq` is contiguous and strictly increasing;
|
|
* `run_id` and protocol/schema are consistent across lines;
|
|
* `stdout.chunk`/`stderr.chunk` base64 decodes and `byte_count` matches;
|
|
* an unknown schema major is rejected, never treated as v1.
|
|
|
|
Exit status 0 means the stream validated. 2 means invalid input, 3 means an
|
|
incomplete stream (no terminal event; a legal boundary after SIGKILL/EOF).
|
|
"""
|
|
import base64
|
|
import binascii
|
|
import json
|
|
import pathlib
|
|
import sys
|
|
|
|
from jsonschema import Draft202012Validator
|
|
|
|
ROOT = pathlib.Path(__file__).resolve().parents[2]
|
|
SCHEMA_PATH = ROOT / "spec" / "schemas" / "execution-events-v1.schema.json"
|
|
SCHEMA = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
|
|
Draft202012Validator.check_schema(SCHEMA)
|
|
VALIDATOR = Draft202012Validator(SCHEMA)
|
|
|
|
SCHEMA_NAME = "marqdo.execution-events"
|
|
SCHEMA_VERSION = 1
|
|
TERMINALS = {"run.completed", "run.failed", "run.rejected"}
|
|
|
|
|
|
class Invalid(Exception):
|
|
pass
|
|
|
|
|
|
def parse_line(number, raw):
|
|
try:
|
|
event = json.loads(raw)
|
|
except json.JSONDecodeError as error:
|
|
raise Invalid(f"line {number}: not JSON: {error}") from error
|
|
if not isinstance(event, dict):
|
|
raise Invalid(f"line {number}: event is not a JSON object")
|
|
errors = sorted(VALIDATOR.iter_errors(event), key=str)
|
|
if errors:
|
|
raise Invalid(f"line {number}: schema: {errors[0].message}")
|
|
return event
|
|
|
|
|
|
def check_chunk(event):
|
|
payload = event["payload"]
|
|
if payload.get("encoding") != "base64":
|
|
raise Invalid(f"seq {event['seq']}: unsupported chunk encoding")
|
|
try:
|
|
data = base64.b64decode(payload["data_base64"], validate=True)
|
|
except (binascii.Error, ValueError) as error:
|
|
raise Invalid(f"seq {event['seq']}: data_base64 is not valid base64: {error}") from error
|
|
if len(data) != payload["byte_count"]:
|
|
raise Invalid(
|
|
f"seq {event['seq']}: byte_count={payload['byte_count']} but decoded {len(data)} bytes"
|
|
)
|
|
return data
|
|
|
|
|
|
def consume(lines, require_terminal=True):
|
|
events = [parse_line(number, raw) for number, raw in enumerate(lines, start=1)]
|
|
if not events:
|
|
raise Invalid("empty stream")
|
|
|
|
first = events[0]
|
|
if first["kind"] != "stream.opened":
|
|
raise Invalid("first event must be stream.opened")
|
|
if first["seq"] != 0:
|
|
raise Invalid("stream.opened must have seq 0")
|
|
if first["schema"] != SCHEMA_NAME or first["schema_version"] != SCHEMA_VERSION:
|
|
raise Invalid("stream.opened does not negotiate marqdo.execution-events v1")
|
|
|
|
run_id = first["run_id"]
|
|
chunks = bytearray()
|
|
terminal = None
|
|
started = 0
|
|
for index, event in enumerate(events):
|
|
seq = event["seq"]
|
|
if seq != index:
|
|
raise Invalid(f"seq {seq} at line {index + 1}; expected {index}")
|
|
if event["schema"] != SCHEMA_NAME or event["schema_version"] != SCHEMA_VERSION:
|
|
raise Invalid(f"seq {seq}: inconsistent schema negotiation")
|
|
if event["run_id"] != run_id:
|
|
raise Invalid(f"seq {seq}: run_id changed within one stream")
|
|
if terminal is not None:
|
|
raise Invalid(f"seq {seq}: event follows terminal {terminal}")
|
|
if event["kind"] == "run.started":
|
|
started += 1
|
|
if started > 1:
|
|
raise Invalid("more than one run.started")
|
|
if event["kind"] in TERMINALS:
|
|
terminal = event["kind"]
|
|
if event["kind"] in ("stdout.chunk", "stderr.chunk"):
|
|
chunks.extend(check_chunk(event))
|
|
|
|
if require_terminal and terminal is None:
|
|
return 3, f"incomplete stream: {len(events)} events, no terminal event"
|
|
if terminal == "run.completed" and started != 1:
|
|
raise Invalid("run.completed requires exactly one preceding run.started")
|
|
if terminal == "run.failed" and started != 1:
|
|
raise Invalid("run.failed requires exactly one preceding run.started")
|
|
if terminal == "run.rejected" and started != 0:
|
|
raise Invalid("run.rejected must not be preceded by run.started")
|
|
return 0, (
|
|
f"ok: {len(events)} events, terminal={terminal}, "
|
|
f"stdout+stderr bytes={len(chunks)}"
|
|
)
|
|
|
|
|
|
def main(argv):
|
|
if len(argv) != 2:
|
|
raise SystemExit(__doc__)
|
|
target = argv[1]
|
|
if target == "-":
|
|
lines = [line for line in sys.stdin.read().splitlines() if line.strip()]
|
|
else:
|
|
text = pathlib.Path(target).read_text(encoding="utf-8")
|
|
lines = [line for line in text.splitlines() if line.strip()]
|
|
try:
|
|
status, message = consume(lines)
|
|
except Invalid as error:
|
|
raise SystemExit(f"execution events consumer: INVALID: {error}")
|
|
print(f"execution events consumer: {message}")
|
|
raise SystemExit(status)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main(sys.argv)
|