Spaces:
Running
Running
File size: 3,369 Bytes
e59bd9d | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 | """IPC message envelope: schema, versioning, validation.
V3 deliberately uses NO network sockets. Internal communication between the
background controller, the launcher, and hook processes inside a target
project happens through per-session files under <lpu_home>/sessions/<id>/:
status.json - latest process status (atomic replace, JSON)
metrics.jsonl - appended performance/GPU metric records (JSON lines)
commands.jsonl- controller -> process commands (e.g. graceful stop)
session.json - immutable session descriptor written at launch
Rationale vs Windows Named Pipes: zero dependencies (no pywin32), survives
process crashes (the file IS the state), human-inspectable for diagnostics,
and trivially portable for tests. The transport is wrapped behind LocalChannel
so a future release can swap in named pipes or a public SDK without touching
callers.
"""
from __future__ import annotations
import json
import secrets
import time
from dataclasses import dataclass, asdict, field
from typing import Any, Dict, Optional
PROTOCOL_VERSION = 1
# V7 protocol extension (additive, backward compatible):
# - envelope format is UNCHANGED (protocol stays 1; old readers ignore
# unknown command types instead of failing)
# - the command allowlist gains the V7 control set used by the Accelerator
# server and the trainer-side Integration SDK:
# set_parameter - hot-reload/safe-boundary parameter change (with ack)
# validate_change - run a controlled A/B window for a level-2 proposal
# request_pause / request_resume - only if the trainer supports pause
# graceful_stop - finish current batch, checkpoint, exit cleanly
# ping - liveness probe (SDK must answer with an ack)
V7_COMMANDS = {
"set_parameter", "validate_change", "request_pause",
"request_resume", "graceful_stop", "ping",
}
VALID_COMMANDS = {"stop", "gc_cache", "status", "report"} | V7_COMMANDS
@dataclass
class Envelope:
"""Every IPC message. `type` selects the payload contract."""
type: str
ts: float = field(default_factory=time.time)
protocol: int = PROTOCOL_VERSION
session_id: Optional[str] = None
payload: Dict[str, Any] = field(default_factory=dict)
def to_json(self) -> str:
return json.dumps(asdict(self), ensure_ascii=False, default=str)
@classmethod
def from_json(cls, raw: str) -> "Envelope":
d = json.loads(raw)
if not isinstance(d, dict) or "type" not in d:
raise ValueError("invalid envelope: missing 'type'")
if int(d.get("protocol", 0)) > PROTOCOL_VERSION:
raise ValueError(f"envelope protocol {d.get('protocol')} newer than supported {PROTOCOL_VERSION}")
payload = d.get("payload")
if payload is not None and not isinstance(payload, dict):
raise ValueError("envelope payload must be a mapping")
return cls(
type=str(d["type"]),
ts=float(d.get("ts", time.time())),
protocol=int(d.get("protocol", PROTOCOL_VERSION)),
session_id=d.get("session_id"),
payload=payload or {},
)
def new_session_id() -> str:
"""Collision-safe session id (timestamp prefix + 48 bits of entropy)."""
return f"{int(time.time() * 1000):x}-{secrets.token_hex(6)}"
def validate_command(cmd: str) -> bool:
return cmd in VALID_COMMANDS
|