diff --git a/docs/CONTRACT-sessions.md b/docs/CONTRACT-sessions.md index 455ff0c..eb17fc6 100644 --- a/docs/CONTRACT-sessions.md +++ b/docs/CONTRACT-sessions.md @@ -1,4 +1,4 @@ -# CONTRACT — sessions build (sessions-v3) +# CONTRACT — sessions build (sessions-v4) This file is the interface for the **session** work: the broker, containers, compositor IPC and pointer **and keyboard** input. It is the sibling of `docs/CONTRACT.md`, which @@ -9,11 +9,31 @@ else. If something here is wrong or missing, **stop and report it in your final message** — the parent edits this file, not you. Do not widen your slice to work around a gap. -Version: sessions-v3 (2026-10-04). v1 was the freeze the four slices built +Version: sessions-v4 (2026-10-11). v1 was the freeze the four slices built against; v2 recorded the decisions their reports asked for; v3 adds the -keyboard. Every change in both has been an addition or a clarification — **no -v1 or v2 signature changed meaning** — so earlier code stays valid except where -noted. +keyboard; v4 adds the **per-session live stream**. Every change in all of them +has been an addition or a clarification — **no v1, v2 or v3 signature changed +meaning** — so earlier code stays valid except where noted. + +v4 changes, all of them the stream +(`docs/plans/2026-10-04-session-stream-webapp.md`, Stage 2): + +| § | Change | Why | +| --- | --- | --- | +| §3.5 | New: `hhstreamd/live.py`, the broker's end of `/run/hhstream/live.sock`, and that socket's wire format. | The stream is captured by `hhstream-live`, a third executor beside the pointer driver. `grim` blocks tens to hundreds of milliseconds, so it must not run in the broker, and a LAN-facing HTTP parser must not run in the frame server whose one-socket contract cannot grow one. The broker therefore *tells* a process what to publish, exactly as it tells the driver where to warp. | +| §4 | Verbs `stream.enable`, `stream.disable`, `stream.list`, `stream.status`. `enable` and `disable` are in the mutation set; `list` and `status` are not. | `enable` mints or rotates a phrase and opens a capture — a retried `enable` that minted a second phrase would invalidate the URL somebody is already holding. | +| §4 | `start` gains `stream?`, `stream_phrase?` and `stream_fps?`. | A stream needs the session's container output, which `start` creates; sequencing "start, then enable" in a *caller* means every caller repeats the ordering and the failure handling. One request, one answer, and the phrase comes back with the session. | +| §4 | **A connected viewer is activity.** The broker asks the daemon for viewer counts about once a minute and stamps `touch` when any is non-zero. | The one new way the idle clock moves, and the only exception to "`touch` is the only mark of activity" since that rule was written. A session an operator is watching on his phone must not be reaped at three hours *because* watching is all he is doing. An enabled stream with **no** viewer runs no `grim` and keeps nothing alive, so this cannot hold a session open by itself. | +| §4 | Error names `stream_unavailable` (exit 10), `stream_busy` (exit 8), `stream_budget` (exit 6). **No new exit numbers.** | The failures are the ones the table already has: no container is a compositor-side failure, a phrase collision is a busy, a viewer cap is a policy budget. | +| §5 | `/run/hhstream/live.sock`, the unit `hhstream-live`, and the stream port 9988. | Named here with the other frozen paths, because two processes have to agree on them. | +| §6 | Registry **schema 3 → 4**: the record gains `stream`. | A phrase has to survive a broker restart and a re-enable, so it lives in the record. Older records migrate to `stream: null` and are adopted, not refused. | + +v4 deliberately does **not** give the broker the port, the bind address or the +capture command. Those are the daemon's, from its own unit's argv, for the +reason the keyboard layout is the driver's: the broker's TOML is read by +`hhstreamd`, and a setting an operator could change in it while the listener +stayed where it was would be worse than no setting at all. The broker learns +the URL prefix *from* the daemon, in the `attach` reply. v3 changes, all of them keyboard (`docs/plans/2026-10-03-keyboard-input.md` as amended by `docs/plans/2026-10-04-keyboard-verification.md`): @@ -375,6 +395,79 @@ the lease; a real-compositor case is still missing — see lease state** — the broker owns the lease; the driver is an executor that must never be trusted to serialise anything. +### 3.5 `hhstreamd/live.py` (v4) — the broker's end of the stream daemon + +A third executor beside the pointer driver, and the same shape as §3.4: the +broker holds the *decision* (which session streams, under which phrase) and the +daemon holds the *capture*. `hhstream-live` owns the port, the bind address and +the capture command, from its own unit's argv; the broker never passes them and +never reads them from its own TOML. + +```python +class LiveUnavailable(Exception): + """The stream daemon could not be reached, or did not answer intelligibly.""" + +class LiveRejected(Exception): + """The daemon refused. `kind` maps to an exit code, as the driver's does.""" + def __init__(self, message: str, *, kind: str | None = None) -> None: ... + +@dataclass(frozen=True) +class Attachment: + phrase: str; output: str; fps: int; session: str | None + url: str # the daemon's own prefix, e.g. http://127.0.0.1:9988// + viewers: int + +class LiveStreams: + def __init__(self, socket_path: Path | str, *, timeout_s: float = 2.0) -> None: ... + def attach(self, *, phrase: str, output: str, fps: int, + session: str | None = None, label: str = "") -> Attachment: ... + def detach(self, phrase: str) -> bool: ... # False if it was not attached + def list(self) -> list[Attachment]: ... + def viewers(self) -> dict[str, int]: ... # phrase -> connected viewers + def close(self) -> None: ... +``` + +Private socket protocol, newline-delimited JSON, the driver's conventions +exactly — `{"ok": true, …}` or `{"ok": false, "error": "…", "kind": "…"}`: + +```json +{"op": "attach", "phrase": "amber-otter-lantern-harbor-7k2qp", "output": "hh-x", + "session": "x", "label": "chromium", "fps": 5} // fps is OPTIONAL + -> {"ok": true, "stream": {"phrase": "…", "output": "hh-x", + "fps": 5, "session": "x", "url": "http://…/", "viewers": 0}} +{"op": "detach", "phrase": "…"} -> {"ok": true, "detached": true} +{"op": "list"} -> {"ok": true, "streams": [ {…}, … ]} +{"op": "viewers"} -> {"ok": true, "viewers": {"": 2}} +``` + +Four rules that are not interchangeable: + +- **The daemon holds no session state and no idea of an idle clock.** It + publishes what it was told to publish. `viewers` is a *reading*, and what the + broker does with it (§4) is the broker's. +- **`fps` is optional, and omitting it is the normal case.** The default rate is + the daemon's, from its own unit's argv (`sessions.stream.fps`), for the same + reason the port is. The broker sends one only when a caller named one, or + when re-attaching a stream that already had one. A broker that sent its own + default on every attach would make the operator's option a setting that + changed nothing — the same failure `--xkb-layout` (§3.4) exists to avoid. +- **`attach` is idempotent on the phrase.** Re-attaching the same phrase to the + same output returns the existing stream rather than starting a second + capture, because a re-`enable` after a broker restart must not double the + `grim` rate on one output. The same phrase aimed at a *different* output is + `{"kind": "invalid_argument"}`. +- **The phrase is never logged by either side.** It is the stream's only + credential. The daemon logs the output and the viewer count; the broker's + audit log records the session and the output (§4), and neither records the + phrase. + +`url` comes back from the daemon rather than being built by the broker, for the +reason the port is the daemon's: a URL the broker assembled from a port it was +told about once is a URL that silently lies the first time an operator moves +the listener. + +--- + --- ## 4. Wire format (broker control socket) — B, C and D do not implement this @@ -395,6 +488,44 @@ code will be called with): | `pointer.state` | — | `holder`, `since`, `lease_id`, `buttons[]`, `keys[]` | | `keyboard.key` (v3) | `id`, `lease_id`, `key`, `state` | `keys[]` | | `keyboard.type` (v3) | `id`, `lease_id`, `text` | `chars`, `keys[]` | +| `stream.enable` (v4) | `id`, `phrase?`, `fps?` | `stream` | +| `stream.disable` (v4) | `id` | `stream`, `detached` | +| `stream.list` (v4) | — | `streams[]`, `available` | +| `stream.status` (v4) | `id?` | `stream` \| `streams[]` | + +**v4, the stream.** `stream.enable` and `stream.disable` are in the +`request_id` mutation set; `stream.list` and `stream.status` are not. +`start` additionally accepts `stream?` (bool), `stream_phrase?` and +`stream_fps?`, and when `stream` is true its reply's session carries the same +`stream` object `stream.enable` would have returned. + +The `stream` object is the record's, with the daemon's `url` and `viewers` +merged in when it could be asked: + +```json +{"enabled": true, "phrase": "amber-otter-lantern-harbor-7k2qp", + "output": "hh-x", "fps": 5, "port": 9988, + "url": "http://127.0.0.1:9988/amber-otter-lantern-harbor-7k2qp/", + "viewers": 0, "enabled_at": "2026-10-11T…Z", "attached": true} +``` + +`attached` is its own field and is **not** folded into `enabled`: a record may +say a session is enabled while the daemon is down, and "the operator asked for +this stream" and "a capture is running right now" are two different facts. A +caller that wants the second one reads `attached`; `url` and `viewers` are +absent when it is false, rather than stale. + +**`stream.enable` requires the session's container output.** Without one it is +`stream_unavailable` (exit 10). A stream never falls back to the main output: +that output carries every other session, and putting it on a phone is the one +mistake this feature must not make. Re-enabling an enabled session returns the +same phrase; a `phrase` that differs from the stored one is `stream_busy` +(exit 8). `disable` then `enable` rotates it. + +**Teardown order is load-bearing.** `kill` detaches the stream *before* +`hyprctl output remove`, because a capture aimed at a removed output fails every +time and the daemon's own failure budget would close the viewers with +"unknown output" instead of "the session ended". **v3, the keyboard.** `keyboard.*` verbs take the **pointer** lease: there is no `keyboard.acquire` and no second lease id. One `wl_seat` means one keyboard @@ -417,10 +548,26 @@ explicitly rather than inheriting. | 0 OK | 2 USAGE | 3 NO_SUCH_SESSION | 4 BAD_STATE | 5 DAEMON_UNREACHABLE | | 6 POLICY | 7 TIMEOUT | 8 BUSY | **9 NO_LEASE (new)** | **10 COMPOSITOR (new)** | -Activity accounting is unchanged and load-bearing: **`touch` is the only mark of -activity**; `list`, `status`, `logs`, `gc`, and every `pointer.*` **and -`keyboard.*`** verb do **not** reset the idle clock. A session being typed into -is still a session nobody has said they want kept. +**v4 adds error names and no numbers.** `stream_unavailable` → 10 (no +container, or the daemon is unreachable — the session itself is fine either +way), `stream_busy` → 8 (a `phrase` that is not this session's), `stream_budget` +→ 6 (the daemon's viewer or stream cap). A bad `fps` is `invalid_argument` → 2, +as every other bad argument is. + +Activity accounting is load-bearing and has **one** exception as of v4: +**`touch` is the only mark of activity a caller can make**; `list`, `status`, +`logs`, `gc`, every `pointer.*` **and `keyboard.*`** verb, and every +`stream.*` verb do **not** reset the idle clock. A session being typed into is +still a session nobody has said they want kept. + +The exception is **a connected viewer**. About once a minute the broker asks +the daemon for viewer counts and stamps `touch` on every session whose stream +has at least one; the audit entry names the session, the output and the count, +never the phrase. This is not a caller's verb and cannot be invoked — it is the +broker observing that a person is *looking*, which is the one form of "still +wanted" that does not come down the control socket. It cannot hold a session +open on its own: an enabled stream with no viewer runs no `grim` and stamps +nothing. The *lease* clock is a different one, and v3 widens it: every `pointer.*` and `keyboard.*` gesture verb refreshes the lease's idle deadline, because they all @@ -438,14 +585,18 @@ go through the same gate. `pointer acquire`'s own stderr says so. | Frame socket (published) | `/stream.sock` — default `/run/hypr-stream/stream.sock`. Also frozen in `docs/CONTRACT.md`, which v1 of this file left disagreeing with it. | | Broker control socket | `/run/hhstream/control.sock` | | Broker↔driver socket | `/run/hhstream/pointer.sock` | +| Broker↔stream socket | `/run/hhstream/live.sock` (v4) | +| Stream port | **option default** `9988` (`sessions.stream.port`), fixed and single — no range, no fallback. The daemon owns it; the broker learns the URL from the daemon (§3.5). | +| Stream bind | **option default** `127.0.0.1` (`sessions.stream.bind`) | | Broker state dir | **option default** `/var/lib/hhstream`; this machine sets `/var/lib/hermes/hhstream-sessions` (`sessions.stateDir`). v1 listed the deployed value, which read as a contradiction of the module. | | Session runtime dir | `/run/hhstream/sessions/` | | Container output name | `hh-` | | Container workspace band | `1000 + slot`, allocated from the registry's free list | | Container mode | `1280x720` | -| Units | `hyprland-headless`, `hyprland-headless-stream`, `hhstream-sessions`, `hhstream-pointer` | +| Units | `hyprland-headless`, `hyprland-headless-stream`, `hhstream-sessions`, `hhstream-pointer`, `hhstream-live` (v4) | | Keyboard layout | **option default** `us` (`sessions.keyboard.layout`), reaching the driver as `--xkb-layout`. One group: a comma is refused. Hyprland's `input:kb_layout` is not read. | -| Binaries | `hhstream`, `hhstreamd`, `hhstream-server`, `hhstream-client`, `hhstream-pointer` | +| Binaries | `hhstream`, `hhstreamd`, `hhstream-server`, `hhstream-client`, `hhstream-pointer`, `hhstream-live` | +| Registry schema | **4** (v4; 3 → 4 adds `stream`, migrating to `null`) | | Service account | `hermes`, supplementary group `hhstream` | ---