docs(sessions)!: sessions-v4, the per-session live stream
`docs/CONTRACT-sessions.md` goes to sessions-v4 with a change table at the top, for the reason mcp-v2 got one: everything in it is an addition, and a reader who learned v3 should be told what moved rather than diff it. The new §3.5 is the interface that needed freezing most, because it is the only one in this build that two *processes* have to agree on: `/run/hhstream/live.sock`, `LiveStreams.attach/detach/list/viewers`, the four JSON ops on the wire, and the `Attachment` the broker gets back. Its shape is §3.4's deliberately -- the broker holds the decision (which session streams, under which phrase), the daemon holds the capture -- so a reader who knows the pointer driver already knows this. Four rules in §3.5 are written out because each one is a thing a reasonable implementation would get wrong: * the daemon holds no session state and no idle clock; `viewers` is a reading, and what the broker does with it is the broker's; * `fps` is optional and omitting it is normal -- the default is the daemon's, from its own unit's argv, for the same reason the port is. A broker that sent its own default on every attach would turn `sessions.stream.fps` into a setting that changed nothing, which is the failure `--xkb-layout` exists to avoid; * `attach` is idempotent on the phrase, so a re-`enable` after a broker restart does not double the `grim` rate on one output; * the phrase is never logged by either side. It is the stream's only credential. §4 gains four verbs, the three `start` arguments, and the one genuinely new rule in this version: **a connected viewer is activity**. That is the first exception to "`touch` is the only mark of activity" since that rule was written, and it is there for one failure -- an operator watching a long job on his phone, saying nothing to the broker, and losing the session at three hours *because* watching was all he was doing. It cannot hold a session open by itself: an enabled stream with no viewer runs no `grim` and stamps nothing. No new exit numbers. The three error names map onto codes the frozen table already has (`stream_unavailable` -> 10, `stream_busy` -> 8, `stream_budget` -> 6), because no new *kind* of failure appeared: no container output is a compositor-side failure, a phrase collision is a busy, a viewer cap is a budget. §6 records schema 3 -> 4 (the record gains `stream`, older records migrate to `null`), and §5 names the socket, the unit and port 9988 beside the other frozen paths. What v4 deliberately withholds from the broker is the port, the bind address and the capture command. The broker learns the URL prefix *from* the daemon, in the `attach` reply -- a URL it assembled itself from a port it was told about once is a URL that lies the first time an operator moves the listener. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
This commit is contained in:
1 parent
e636472106
commit
0f2810afaa
1 file changed
+162
-11
+162
-11
@@ -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/<phrase>/
|
||||
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": {"<phrase>": 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) | `<runtime dir>/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/<session-id>` |
|
||||
| Container output name | `hh-<session-id>` |
|
||||
| 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` |
|
||||
|
||||
---
|
||||
|
||||
Reference in new issue
Block a user