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