Compare commits

...
5 Commits
Author SHA1 Message Date
HermenixandClaude Opus 5 ca5dbfb2ea feat(nix): the hhstream-live unit, and the two things it has to be handed
`services.hyprland-headless-stream.sessions.stream.enable` (default **false**)
runs `hhstream-live` and hands the broker `/run/hhstream/live.sock`. Running it
still turns nothing on: a stream exists only for the sessions
`hhstream session stream enable` was run on, which is the plan's rule that a
stream is never on for all sessions at all times.

A fourth unit rather than a flag on an existing one, for the pointer driver's
reason: `grim` blocks tens to hundreds of milliseconds, so the capture must not
run where `touch` and `kill` are answered, and a LAN-facing HTTP parser must not
run in the frame server whose one-socket contract cannot grow one.

Two things the unit must be handed, both of them MEASURED failures rather than
precautions:

1. **The capture command, spelled out, with grim's store path.** A unit's
   `PATH` has no `grim`
   (`docs/TODO/capture-binary-and-the-unit-path.md`), and the symptom is a
   stream that answers with an empty frame area and says why only in the
   daemon's journal. Every word is passed as `--capture-command=<word>` and not
   `--capture-command <word>`, because grim's last word is a bare `-` and
   argparse reads a lone dash as an option prefix rather than a value -- a unit
   crash-looping with "expected one argument", which is how that form was
   chosen.
2. **The compositor's session.** `XDG_RUNTIME_DIR` on the unit plus `execLive`,
   which discovers whichever `wayland-N` the compositor actually bound and
   exports it -- `execServer`'s trick, for `execServer`'s reason: the name is
   only known once the compositor is up, so it cannot be an `Environment=`
   line. Without it the unit was `active (running)`, the broker attached,
   `stream status` said `attached: true`, and every capture exited 1 with
   "XDG_RUNTIME_DIR is invalid or not set in the environment" until the
   publisher gave up after ten in a row. checks/vm-stream.nix found that on its
   first real run, which is the whole reason that check reads bytes instead of
   asserting a 200.

`SupplementaryGroups` gets the compositor's group for the pointer driver's
reason one step further -- this one has to *capture*, not merely find the
socket -- and there is deliberately no `RuntimeDirectory=`: a second one on
/run/hhstream would delete the broker's control socket when this unit stopped,
which the plan names as the Stage 3 risk.

`sessions.stream.fps` is the daemon's own default and nothing else sends one, so
the option changes what actually happens; the port and bind address are the
daemon's too, and the broker learns the URL from it.

`nix/package.nix` names `hhstream_live.control` and `hhstreamd.live` in
`pythonImportsCheck`: they are the one pair in this package that has to agree
with each other across two processes, so an import error in either is worth
finding at build time rather than the first time an operator enables a stream.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:48:22 +00:00
HermenixandClaude Opus 5 850f9caa1d feat(cli): session stream and start --stream
The operator's side of the four verbs: `hhstream session stream
enable|disable|list|status`, and `start --stream [--stream-phrase]
[--stream-fps]` for the one-call case.

`stream enable` prints the URL on **stdout and nothing else**, with the detail
on stderr, so `url=$(hhstream session stream enable ID)` works -- the same shape
`start` already has for the session id. `start --stream` prints the id and then
the URL, two lines, because a caller who asked for both should not have to run
a second verb for the second one.

The phrase is a credential, and the two renderers disagree on purpose:

* `render_streams` (`stream list`) does **not** show it. A listing is what ends
  up in a shared terminal, a paste or a screenshot, so what it shows is enough
  to recognise and manage a stream -- session, output, rate, viewers, `LIVE` --
  and not enough to watch one. It also prints the daemon's reachability, because
  "two records and no daemon" is a different situation from "two records and two
  captures" and the rows alone cannot say which.
* `render_stream` (`stream status ID`) does show the URL. That question was
  asked about one session by name, which is what somebody about to watch it
  does, and making them reach for `--json` for the thing the verb is for would
  be the worse trade.

When the daemon is not publishing, `status` says so and prints no URL -- the
phrase is kept, so re-enabling restores the same one.

`start --stream` that starts the session but cannot open the stream exits 0 and
says `WARNING: the session is running but its stream was not enabled: …` on
stderr. Loudly, because the exit code is the session's and a caller who asked
for a stream must not read a 0 as one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:48:00 +00:00
HermenixandClaude Opus 5 7d8ca6191b feat(sessions)!: the four stream verbs, schema 4, and the viewer sweep
The broker half of sessions-v4: `stream.enable`, `stream.disable`,
`stream.list`, `stream.status`, `start`'s three new arguments, and the one rule
that is genuinely new rather than additive -- a connected viewer is activity.

The decisions worth reading the diff for:

**A stream never falls back to the main output.** `_stream_output` refuses when
a session has no container, and the refusal is stronger than the pointer's for a
reason the hint states: the main output carries *every other session*, so a
fallback would put somebody else's desktop on a phone behind a phrase that was
issued for this one.

**The phrase lives in the record, so re-enabling returns the same URL.** A
different `--phrase` on an already-enabled session is `stream_busy` (exit 8),
not a silent rotation: rotating under a caller who is holding the old URL is the
one outcome neither answer can be mistaken for. `disable` then `enable` is how
it rotates, which is explicit.

**`_checked_phrase` raises the shape and never the value**, with `from None`, for
`control._phrase_of`'s reason: `phrase.validate` names what it rejected, and
this value is a password on its way into an error reply and a log.

**`fps` is only sent when a caller named one** (`_checked_fps` returns `None`
otherwise), which is what makes the daemon's own default authoritative instead
of decorative. The broker holds the daemon to the frozen cap before sending, so
a nonsense rate is exit 2 from the verb rather than a surprise from the socket.

**`attached` is its own field and is not folded into `enabled`.** A record can
say the operator asked for a stream while the daemon is down, and those are two
different facts; `url` and `viewers` are *absent* rather than stale when it is
false, because a URL that no longer serves anything is worse than no URL.
`stream.list` also reports `available`, so "no streams" is distinguishable from
"no daemon" without parsing an error.

**The viewer sweep** (`_sweep_streams`, every `STREAM_SWEEP_S = 60`s) asks the
daemon for viewer counts and stamps `touch` on every session somebody is
watching. It is the only thing in this daemon that treats an observation as an
intention, and it exists for one failure: an operator watching a long job on his
phone 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 -- which is why it is safe to run
unconditionally.

**Teardown detaches before it destroys the container.** The other order makes
every capture fail against a removed output, which is a stream that gives up
ten frames later and a log that blames `grim`.

`start` takes `stream`, `stream_phrase` and `stream_fps` and reports a stream it
could not open in `stream_error` beside a session that *did* start, because the
exit code is 0 and a caller who asked for a stream must not read that as one.

Registry schema 3 -> 4: the record gains `stream`, older records migrate to
`null` rather than being refused, and the viewer count is deliberately not
stored -- a viewer count on disk is a number that is wrong the moment it is
written.

No new exit numbers: `stream_busy` -> 8, `stream_budget` -> 6,
`stream_unavailable` -> 10. The last one is 10 for `driver_refused`'s reason --
the session keeps running, and a caller that read an unreachable stream as a
dead session would kill an application over a web page.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:47:43 +00:00
HermenixandClaude Opus 5 8c99518a62 feat(live): live.sock, both ends
The socket CONTRACT-sessions.md §3.5 freezes, implemented on both sides and by
nobody else: `hhstream_live.control` answers it, `hhstreamd.live` asks it.

`control.Control` is the four ops and nothing more -- attach, detach, list,
viewers -- with the decisions the daemon is allowed to make and no others. It
owns the two things only this process knows: how to build a capture for an
output (the capture command, from this unit's argv) and what a URL looks like
(the bound port). Both are injected as callables by `__main__.control_server`,
which is also why `attach` replies with a URL rather than letting the broker
assemble one from a port it was told about once.

`attach` is idempotent on the phrase and returns the existing stream, so a
re-`enable` after a broker restart cannot double the `grim` rate on an output.
The same phrase aimed at a *different* output is `invalid_argument`, because
that is a mistake and not a request.

Two details that are the point rather than polish:

* `_phrase_of` holds a caller's phrase to the generated shape and raises a
  shape-only message, with `from None`. `phrase.validate` names the value it
  rejected, which is correct for a library and wrong here: this value is a
  password, and the refusal travels back over a socket and into a log.
* `ControlServer.serve_forever` reads `self._sock` into a local before using
  it. `close()` runs on the main thread while this one is in `accept()`, and
  the attribute it was reading can be gone by the time it is dereferenced.

`hhstreamd.live` is the broker's client: one op at a time behind a lock, a
2-second timeout, `LiveUnavailable` for "could not be reached or did not answer
intelligibly" and `LiveRejected` carrying the `kind` the broker maps to an exit
code -- the pointer driver's client, verb for verb, because the broker already
knows how to hold one of those. `Attachment.parse` refuses a malformed reply
rather than defaulting its way past one.

`fps` is omitted from an `attach` unless a caller named one, which is what makes
`sessions.stream.fps` on the daemon's unit authoritative instead of decorative.
And `_safe()` renders a phrase as `<phrase:5 tokens>` for the one log line that
mentions a stream at all: the shape, never the words.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:47:16 +00:00
HermenixandClaude Opus 5 0f2810afaa 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
2026-10-11 22:46:54 +00:00
12 changed files with 1924 additions and 31 deletions

No files matched your search

+162 -11
View File
@@ -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` |
---
+170 -7
View File
@@ -46,6 +46,7 @@ let
brokerRuntimeDir = "/run/${brokerRuntimeDirName}";
controlSocket = "${brokerRuntimeDir}/control.sock";
pointerSocket = "${brokerRuntimeDir}/pointer.sock";
liveSocket = "${brokerRuntimeDir}/live.sock";
# Addresses that mean "this listener answers on loopback only". The spelling
# `localhost` is included because it is what a person writes; it is not a
@@ -164,6 +165,35 @@ let
done
exec ${lib.getExe' cfg.package "hhstream-server"} "$@"
'';
# The same problem, for the stream daemon, one step worse.
#
# `grim` is an ordinary Wayland client: it needs XDG_RUNTIME_DIR *and* the
# name of the socket the compositor actually bound, and that name is only
# known once the compositor is up -- so, exactly as above, it cannot be an
# `Environment=` line.
#
# MEASURED, in checks/vm-stream.nix, which is the check that exists to find
# this: with the group but without the environment, the unit came up
# `active (running)`, the broker attached, `stream status` said
# `attached: true`, and every capture failed with
#
# grim: error: XDG_RUNTIME_DIR is invalid or not set in the environment.
#
# until the publisher gave up after ten in a row. A viewer with the right
# phrase got a page and no frames, and nothing in the session's own state
# said why -- the sibling failure to
# docs/TODO/capture-binary-and-the-unit-path.md, and the reason this unit
# spells out the whole capture command *and* hands it a session.
execLive = pkgs.writeShellScript "hhstream-exec-live" ''
for candidate in "$XDG_RUNTIME_DIR"/wayland-*; do
if [ -S "$candidate" ]; then
export WAYLAND_DISPLAY="''${candidate##*/}"
break
fi
done
exec ${lib.getExe' cfg.package "hhstream-live"} "$@"
'';
hyprlandConf = pkgs.writeText "hyprland.conf" (import ./hyprland-conf.nix {
inherit lib;
inherit (cfg) outputs extraConfig;
@@ -701,15 +731,57 @@ in {
# The session-stream web app — `hhstream-live`, the router that serves a
# live view of one session per phrase, over one port
# (`docs/plans/2026-10-04-session-stream-webapp.md`).
# (`docs/plans/2026-10-04-session-stream-webapp.md`, Stage 2 and 3).
#
# Only the *reach* of it is declared here so far: the port every stream
# shares, the address it will bind, and whether that port is opened in
# the firewall. The unit that runs the app, the phrases the broker keeps
# in its records and the `session stream enable` verbs are later stages
# of that plan — and deliberately so: a stream is switched on per
# session, never for all of them, so nothing here turns one on.
# `enable` runs the unit and hands the broker `/run/hhstream/live.sock`,
# over which `hhstream session stream enable <id>` switches one stream
# on. Everything else here is the *reach* of it: the port every stream
# shares, the address it binds, and whether that port is opened in the
# firewall.
#
# Running it still turns nothing on. A stream exists only for the
# sessions it was enabled on — a stream is switched on per session, never
# for all of them — so `enable = true` is a listener serving one form
# until somebody asks for a session.
stream = {
enable = lib.mkOption {
type = lib.types.bool;
default = false;
description = ''
Run `hhstream-live`, the web app that publishes one session's
screen at a URL whose path is a spoken phrase, and give the broker
the socket it switches streams on over
(`/run/hhstream/live.sock`).
Off by default, and running it turns **nothing** on: a stream
exists only for the sessions `hhstream session stream enable` was
called on, and until then this is a listener serving one form.
That is deliberate — a live view of a desktop is readable by
anyone who can reach the port and guess the phrase, so switching
one on is a per-session act and never a consequence of the service
being up.
Needs {option}`sessions.enable`: the phrase lives in the session
record, and there are no sessions without the broker.
'';
};
fps = lib.mkOption {
type = lib.types.ints.positive;
default = 5;
description = ''
Frames a second a stream captures at when nobody says otherwise.
Five is one frame per ~200 ms plus a ~46 ms `grim`, measured rather
than guessed; the daemon's own hard cap is 10, because this box is
also running the compositor and the main frame publisher. Capture
happens **only while somebody is connected**, so an enabled stream
nobody is watching costs nothing at any rate.
`hhstream session stream enable --fps N` overrides it per stream.
'';
};
port = lib.mkOption {
type = lib.types.port;
default = 9988;
@@ -1236,5 +1308,96 @@ in {
];
};
};
# The stream daemon. A third executor beside the pointer driver, and the
# split is the driver's: `grim` blocks tens to hundreds of milliseconds, so
# the capture must not run where `touch` and `kill` are answered, and a
# LAN-facing HTTP parser must not run in the frame server whose one-socket
# contract cannot grow one (docs/CONTRACT-sessions.md §3.5).
systemd.services.hhstream-live = lib.mkIf (cfg.sessions.enable && cfg.sessions.stream.enable) {
description = "Per-session live stream for the headless Hyprland desktop";
wantedBy = ["multi-user.target"];
after = ["hyprland-headless.service"];
# `BindsTo` for the pointer driver's reason: this process captures from
# that compositor's outputs through `grim`, so when the compositor goes
# it has nothing left to capture. The broker reports such a stream as
# `attached: false` rather than pretending, and re-enabling re-attaches.
bindsTo = ["hyprland-headless.service"];
environment = {
PYTHONUNBUFFERED = "1";
# The compositor's session, not this unit's own: `grim` has to find the
# Wayland socket in here. `WAYLAND_DISPLAY` is set by `execLive` at
# start, because the socket's name is only known once the compositor
# has bound it. HOME is deliberately NOT redirected here the way the
# frame server's is -- this unit runs as the operator's account, and
# the compositor's runtime directory is not writable by it.
XDG_RUNTIME_DIR = runtimeDir;
};
serviceConfig = {
Type = "simple";
User = cfg.sessions.user;
# The compositor's runtime directory is 0750 and owned by this group,
# and `grim` is a Wayland client of it -- same reason the pointer
# driver needs the group, one step further: this one has to *capture*,
# not merely find the socket.
SupplementaryGroups = [cfg.sessions.group];
# No `RuntimeDirectory`: /run/hhstream belongs to the broker's unit and
# to the tmpfiles entry above, and a second RuntimeDirectory= on the
# same path would delete the broker's control socket when this unit
# stopped. The plan calls this out by name as the Stage 3 risk.
WorkingDirectory = brokerRuntimeDir;
UMask = "0007";
Restart = "on-failure";
RestartSec = 1;
NoNewPrivileges = true;
KillMode = "process";
# `grim` is NOT on a unit's PATH, and the symptom of leaving it off is
# a stream that serves an empty frame area without saying why --
# docs/TODO/capture-binary-and-the-unit-path.md, found the first time
# the capture ran as a unit rather than from a login shell. So the
# whole capture command is spelled out here, with grim's store path.
#
# `--capture-command=<word>` and not `--capture-command <word>`:
# MEASURED, as a unit crash-looping with
#
# hhstream-live serve: error: argument --capture-command: expected
# one argument
#
# because grim's last word is a bare `-` (its "write to stdout"), and
# argparse reads a lone dash as an option prefix rather than a value.
# The `=` form is unambiguous for every word, so it is used for every
# word rather than only the one that needs it.
# Same second line of defence as the frame server's: `BindsTo=` stops
# this unit when the compositor goes, but the compositor is only
# *ready* once its socket is bound, and `execLive` has to find that
# socket to export its name.
ExecStartPre = "${findSession} >/dev/null";
ExecStart = lib.escapeShellArgs (
[
execLive
"serve"
"--control-socket=${liveSocket}"
"--bind=${cfg.sessions.stream.bind}"
"--port=${toString cfg.sessions.stream.port}"
"--fps=${toString cfg.sessions.stream.fps}"
]
++ map (word: "--capture-command=${word}") [
(lib.getExe pkgs.grim)
"-c" # include the cursor
"-t"
"jpeg"
"-q"
"80"
"-" # write to stdout
]
);
};
};
};
}
+7
View File
@@ -38,6 +38,13 @@ python3.pkgs.buildPythonApplication {
# The web app: importing the server pulls in the router, the publisher and
# the pages.
"hhstream_live.server"
# The two halves of `live.sock` (CONTRACT-sessions.md §3.5). Both are
# stdlib-only, and they are named here because they are the one pair in
# this package that has to agree with each other across two processes --
# so an import error in either is worth finding at build time rather than
# the first time an operator enables a stream.
"hhstream_live.control"
"hhstreamd.live"
];
# `pythonImportsCheck` only *imports*, and `hhstream_live.phrase` reads its
+55 -3
View File
@@ -88,6 +88,13 @@ def build_parser() -> argparse.ArgumentParser:
serve.add_argument("--stream", action="append", default=[], type=parse_stream,
metavar="PHRASE=OUTPUT",
help="enable a stream on this output; repeatable")
serve.add_argument(
"--control-socket",
metavar="PATH",
help="serve the broker's control socket here (CONTRACT-sessions.md "
"§3.5), so `hhstream session stream enable` can attach a stream. "
"Omitted, the app is standalone and only --stream puts anything on it.",
)
serve.add_argument("--capture-command", action="append", default=None,
metavar="WORD",
help="capture argv word; repeat (a repeated flag is the "
@@ -139,6 +146,7 @@ def cmd_serve(args: argparse.Namespace) -> int:
capture_base = args.capture_command or DEFAULT_CAPTURE
registry = make_registry(args.stream, capture_base, args.fps)
server = LiveServer(registry, host=args.bind, port=args.port)
control = control_server(args, registry, server, capture_base)
# A service is stopped with SIGTERM, not with Ctrl-C: without a handler the
# default action kills the process outright and `server.stop` never runs, so
@@ -159,14 +167,25 @@ def cmd_serve(args: argparse.Namespace) -> int:
try:
server.start() # raises OSError loudly if the port is taken
if control is not None:
# After the listener, because `attach` replies with a URL and the
# URL has no answer until the port is bound -- a requested port of
# 0 least of all.
control.listen()
threading.Thread(
target=control.serve_forever,
name="hhstream-live.control",
daemon=True,
).start()
print(f"control socket: {control.socket_path}", file=sys.stderr)
# Printed after `start`, because a requested port of 0 only has an answer
# once it is bound. `describe_bind` names the real bind, so `0.0.0.0` is
# not reported as loopback just because that is the address you click.
print(server.describe_bind(), file=sys.stderr)
print(f"landing page: http://{server.address}:{server.port}/", file=sys.stderr)
if not args.stream:
print("no --stream given; only the landing page will answer",
file=sys.stderr)
if not args.stream and control is None:
print("no --stream and no --control-socket; only the landing page "
"will answer", file=sys.stderr)
for phrase in registry.phrases():
print(server.url_for(phrase))
sys.stdout.flush()
@@ -177,10 +196,43 @@ def cmd_serve(args: argparse.Namespace) -> int:
finally:
if previous is not None:
signal.signal(signal.SIGTERM, previous)
if control is not None:
# Before the HTTP listener: the broker's next `attach` should fail
# to connect rather than be accepted by a process on its way out.
control.close()
server.stop()
return 0
def control_server(
args: argparse.Namespace,
registry: StreamRegistry,
server: LiveServer,
capture_base: list[str],
) -> "ControlServer | None":
"""The broker's control socket, or ``None`` for a standalone run.
The two things only this process knows are injected here and nowhere else:
how to build a capture for an output (the capture command, from this unit's
argv) and how to name a URL (the bound port). That is the whole reason
`attach` replies with a URL instead of letting the broker assemble one.
"""
if not getattr(args, "control_socket", None):
return None
from .control import Control, ControlServer
from hhstream.capture import CommandCapture
control = Control(
registry,
capture_for=lambda output: CommandCapture(capture_argv(capture_base, output)),
url_for=server.url_for,
default_fps=args.fps,
)
return ControlServer(args.control_socket, control)
def main(argv: list[str] | None = None) -> int:
args = parse_args(argv)
logging.basicConfig(
+317
View File
@@ -0,0 +1,317 @@
"""``/run/hhstream/live.sock`` — the broker tells this process what to publish.
The daemon's end of `docs/CONTRACT-sessions.md` §3.5. Four ops (`attach`,
`detach`, `list`, `viewers`) over newline-delimited JSON, in the shape the
pointer driver's socket already uses, because a second convention for the same
job would be a second thing to remember.
**This process decides nothing about sessions.** It does not know what an idle
clock is, which application a session runs, or whether a stream *should* be on.
It is told a phrase, an output and a rate, and it publishes. `viewers` is a
counter read; what it means is the broker's business
(`docs/CONTRACT-sessions.md` §4).
**It does own the port, the bind address and the capture command**, from its own
unit's argv — which is why `attach` replies with the URL rather than letting the
broker assemble one. A URL built from a port somebody was told about once is a
URL that lies the first time the listener moves.
**`attach` is idempotent on the phrase.** The same phrase aimed at the same
output returns the running stream instead of starting a second capture: the
broker re-attaches after a restart, and doubling the ``grim`` rate on one output
because of a reconnect would be a self-inflicted load problem. The same phrase
aimed somewhere *else* is refused — a phrase is a credential for one view, and
silently re-pointing it would show a person a desktop they were not given.
**The phrase is never logged**, here or in the broker. Every line below names
the output and the session.
"""
from __future__ import annotations
import json
import logging
import os
import socket
import threading
from pathlib import Path
from typing import Any, Callable
from . import phrase as phrase_mod
from .publisher import DEFAULT_FPS, FPS_CAP, StreamRegistry, StreamSpec
log = logging.getLogger("hhstream.live.control")
#: Matches ``hhstreamd.protocol.MAX_LINE_BYTES`` and the pointer driver's.
MAX_LINE_BYTES = 1 << 20
LISTEN_BACKLOG = 8
#: A rejection the broker maps to exit 2 rather than exit 10 -- the caller's
#: mistake, not a failure of this process. Same vocabulary as the driver's.
INVALID = "invalid_argument"
class Control:
"""The op handler. Holds the registry and the two things only this process knows.
``capture_for`` turns an output name into a capture object, and ``url_for``
turns a phrase into this listener's URL. Both are injected rather than
built here so the tests can drive the whole protocol without a compositor
and without binding a port.
"""
def __init__(
self,
registry: StreamRegistry,
*,
capture_for: Callable[[str], Any],
url_for: Callable[[str], str],
default_fps: int = DEFAULT_FPS,
) -> None:
self.registry = registry
self.capture_for = capture_for
self.url_for = url_for
#: The rate an `attach` with no `fps` gets. This process's, from its
#: own argv, because it is the one that has to keep up with it -- and
#: so an operator's `sessions.stream.fps` reaches every stream rather
#: than only the ones somebody named a rate for.
self.default_fps = int(default_fps)
self._lock = threading.Lock()
# -- the ops ----------------------------------------------------------
def handle(self, request: Any) -> dict[str, Any]:
if not isinstance(request, dict):
return _no(f"request is not an object: {type(request).__name__}", INVALID)
op = request.get("op")
handler = {
"attach": self._attach,
"detach": self._detach,
"list": self._list,
"viewers": self._viewers,
}.get(op if isinstance(op, str) else "")
if handler is None:
return _no(f"unknown op: {op!r}", INVALID)
# One op at a time: `attach` reads the registry and then mutates it, and
# two brokers (or a broker and a restart sweep) must not interleave
# there and start two captures for one phrase.
with self._lock:
try:
return handler(request)
except Rejected as refused:
return _no(str(refused), refused.kind)
except (ValueError, TypeError) as exc:
# The registry's own validation (`fps must be a positive int`,
# `phrase ... is already enabled`) surfaces here. It is the
# caller's mistake, so it is exit 2 and not a daemon failure.
return _no(str(exc), INVALID)
def _attach(self, request: dict[str, Any]) -> dict[str, Any]:
phrase = _phrase_of(request)
output = _text(request, "output")
fps = _fps(request, self.default_fps)
session = request.get("session")
session = None if session is None else str(session)
label = str(request.get("label") or "")
existing = self.registry.get(phrase)
if existing is not None:
if existing.spec.output != output:
raise Rejected(
f"that phrase is already publishing output "
f"{existing.spec.output!r}, not {output!r}; disable it first",
INVALID,
)
# Idempotent: the running stream, with whatever rate it was started
# at. A new `fps` is deliberately NOT applied here -- changing the
# rate under a connected viewer is a `disable`/`enable`, which is
# one record write and one obvious act, rather than a silent
# re-rate that no log line would explain.
log.info("re-attached output %s for %s", output, session or "a standalone stream")
return {"ok": True, "stream": self._describe(existing)}
spec = StreamSpec(
phrase=phrase, output=output, fps=fps, session=session, label=label or output
)
stream = self.registry.add(spec, self.capture_for(output))
log.info(
"attached output %s for %s at %s fps",
output,
session or "a standalone stream",
fps,
)
return {"ok": True, "stream": self._describe(stream)}
def _detach(self, request: dict[str, Any]) -> dict[str, Any]:
phrase = _phrase_of(request)
stream = self.registry.remove(phrase)
if stream is None:
# Not an error. `disable` on a session whose daemon restarted since
# `enable` is the ordinary case, and the broker has to clear its
# record either way.
return {"ok": True, "detached": False}
log.info(
"detached output %s for %s",
stream.spec.output,
stream.spec.session or "a standalone stream",
)
return {"ok": True, "detached": True}
def _list(self, request: dict[str, Any]) -> dict[str, Any]:
return {"ok": True, "streams": [self._describe(s) for s in self.registry.all()]}
def _viewers(self, request: dict[str, Any]) -> dict[str, Any]:
return {
"ok": True,
# `Stream.viewers` is a property, not a method.
"viewers": {s.spec.phrase: s.viewers for s in self.registry.all()},
}
def _describe(self, stream: Any) -> dict[str, Any]:
public = dict(stream.spec.public())
public["url"] = self.url_for(stream.spec.phrase)
public["viewers"] = stream.viewers
return public
class Rejected(Exception):
"""A refusal with a ``kind`` the broker maps to an exit code."""
def __init__(self, message: str, kind: str | None = None) -> None:
super().__init__(message)
self.kind = kind
def _no(error: str, kind: str | None = None) -> dict[str, Any]:
reply: dict[str, Any] = {"ok": False, "error": error}
if kind:
reply["kind"] = kind
return reply
def _text(request: dict[str, Any], field: str) -> str:
value = request.get(field)
if not isinstance(value, str) or not value.strip():
raise Rejected(f"{field} must be a non-empty string", INVALID)
return value.strip()
def _phrase_of(request: dict[str, Any]) -> str:
"""The request's phrase, held to the generated shape.
``phrase.validate`` and not a looser check, for the reason it exists: the
phrase is this stream's only credential, so anything that reaches the
registry has to be a password rather than ``a-b-c``. The refusal never
echoes the phrase back.
"""
value = request.get("phrase")
if not isinstance(value, str):
raise Rejected("phrase must be a string", INVALID)
try:
return phrase_mod.validate(value)
except ValueError:
# Not `{exc}`: the validator names the value it refused, and this
# message travels back over the socket into the broker's log. The
# shape, never the phrase.
raise Rejected(
"the phrase given is not of the expected shape: four words of at "
"least three letters plus a five-character tail",
INVALID,
) from None
def _fps(request: dict[str, Any], default: int) -> int:
value = request.get("fps")
if value is None:
return default
if isinstance(value, bool) or not isinstance(value, int):
raise Rejected(f"fps must be an int, got {type(value).__name__}", INVALID)
if value <= 0 or value > FPS_CAP:
raise Rejected(f"fps must be between 1 and {FPS_CAP}, got {value}", INVALID)
return value
class ControlServer:
"""The accept loop for ``live.sock``. One connection at a time.
The same shape as ``hhstream_pointer.server.PointerServer``: the broker is
the only peer, the ops are one small line each, and an async server would
buy nothing but a way to interleave two attaches.
"""
def __init__(
self,
socket_path: Path | str,
control: Control,
*,
socket_mode: int = 0o660,
) -> None:
self.socket_path = Path(socket_path)
self.control = control
self.socket_mode = socket_mode
self._sock: socket.socket | None = None
self.ready = threading.Event()
def listen(self) -> None:
"""Bind and listen. A stale socket file is replaced, not refused:
a crashed daemon leaves one behind and the unit must still start."""
self.socket_path.parent.mkdir(parents=True, exist_ok=True)
if self.socket_path.is_socket():
self.socket_path.unlink()
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.bind(str(self.socket_path))
os.chmod(self.socket_path, self.socket_mode)
sock.listen(LISTEN_BACKLOG)
self._sock = sock
self.ready.set()
log.info("control socket listening on %s", self.socket_path)
def serve_forever(self) -> None:
assert self._sock is not None, "listen() first"
while True:
# Read into a local first. `close()` runs on another thread and
# sets `_sock` to None, so reading the attribute twice can find a
# socket and then find nothing -- measured, as an AttributeError
# out of a daemon thread at shutdown rather than the clean return
# this loop is supposed to make.
sock = self._sock
if sock is None:
return
try:
conn, _ = sock.accept()
except OSError:
# The other way `close()` shows up: the listener was closed
# while this thread was blocked in `accept`.
return
with conn:
self._serve_connection(conn)
def close(self) -> None:
sock, self._sock = self._sock, None
if sock is not None:
sock.close()
self.socket_path.unlink(missing_ok=True)
self.ready.clear()
def _serve_connection(self, conn: socket.socket) -> None:
with conn.makefile("rwb") as stream:
while True:
line = stream.readline(MAX_LINE_BYTES + 1)
if not line:
return
if len(line) > MAX_LINE_BYTES:
_write(stream, _no("request line too long", INVALID))
return
try:
request = json.loads(line)
except json.JSONDecodeError as exc:
_write(stream, _no(f"malformed JSON: {exc}", INVALID))
continue
_write(stream, self.control.handle(request))
def _write(stream, response: dict[str, Any]) -> None:
stream.write(json.dumps(response, separators=(",", ":")).encode() + b"\n")
stream.flush()
+252
View File
@@ -38,6 +38,9 @@ The verb tree, beyond the original eight:
session keyboard type ID TEXT one argument, raw UTF-8, no escapes
session keyboard key ID NAME tap: down then up
session keyboard down/up ID NAME
session stream enable ID publish ID's screen behind a spoken phrase
session stream disable ID stop publishing, and forget the phrase
session stream list/status what is being published, and who is watching
The pointer *and keyboard* verbs share one precondition — the pointer lease —
and the lease id lives in :mod:`hhstream_session.lease` between invocations,
@@ -187,6 +190,27 @@ def _build_namespace(parser: argparse.ArgumentParser) -> None:
help="deduplication token: retrying a start with the same id returns the "
"original reply instead of launching a second application",
)
start.add_argument(
"--stream",
action="store_true",
help="also enable a live stream for this session and print its URL. "
"Needs the session's container output, which this creates — which is "
"why it is a flag here rather than a second command you have to "
"sequence yourself.",
)
start.add_argument(
"--stream-phrase",
metavar="PHRASE",
help="use this phrase instead of a minted one (four words and a "
"five-character tail). It is the stream's only credential, so it is "
"held to exactly that shape.",
)
start.add_argument(
"--stream-fps",
type=int,
metavar="N",
help="frames per second for the stream (default: the broker's)",
)
start.add_argument(
"--no-container",
action="store_true",
@@ -303,6 +327,9 @@ def _build_namespace(parser: argparse.ArgumentParser) -> None:
# ---- keyboard ----------------------------------------------------
_build_keyboard(verbs, common)
# ---- stream ------------------------------------------------------
_build_stream(verbs, common)
#: Button names the driver knows (``hhstream_pointer.buttons.CODES``), mirrored
#: here rather than imported: this module's whole integration promise is that it
@@ -627,6 +654,136 @@ def _build_keyboard(verbs: Any, common: argparse.ArgumentParser) -> None:
sub.add_argument("name", help="XKB keysym name, e.g. Control_L, Shift_L")
#: Printed under `stream --help` and under `enable`. The two facts an operator
#: gets wrong about this group, and they pull in opposite directions: the
#: phrase is a password, and *watching* is the one thing besides `touch` that
#: keeps a session alive.
STREAM_NOTE = (
"CREDENTIAL: the phrase in the URL is the stream's only protection — no "
"TLS, no second factor. Anyone who can reach the port and guess four "
"words can watch. It is never written to the audit log, and it is not "
"echoed by 'list' unless you ask for --json.\n\n"
"ACTIVITY: 'stream enable|disable|list|status' do NOT reset the idle "
"clock, like every pointer and keyboard verb. But A CONNECTED VIEWER "
"DOES: about once a minute the broker stamps 'touch' on any session "
"somebody is watching, so a session you are watching on a phone is not "
"reaped at three hours. An enabled stream with nobody watching captures "
"nothing and keeps nothing alive."
)
def _build_stream(verbs: Any, common: argparse.ArgumentParser) -> None:
"""``session stream <verb>`` — a live view of one session, behind a phrase.
A nested namespace for the reason ``pointer`` is one: these four verbs
share a precondition nothing else here has. It is the session's **container
output** — a stream never falls back to the main output, because that one
carries every other session.
"""
namespace = verbs.add_parser(
"stream",
parents=[common],
help="publish one session's screen on the LAN, behind a spoken phrase",
description=(
"A live view of one session, in a browser, at a URL whose path is "
"four words and a five-character tail. Off by default and per "
"session: a session does not stream because it exists, it streams "
"because it was switched on.\n\n"
"What is published is the session's own container output, never "
"the main one — that output carries every other session, and "
"putting it behind one session's phrase is the mistake this "
"refuses to make (exit 10 with no container).\n\n"
"The transport is MJPEG over HTTP: a browser <img> is the whole "
"client. Capture runs only while somebody is connected."
),
epilog=f"{STREAM_NOTE}\n\n{ACTIVITY_NOTE}",
formatter_class=argparse.RawDescriptionHelpFormatter,
)
streams = namespace.add_subparsers(dest="stream_verb", metavar="VERB")
namespace.set_defaults(
func=_cmd_stream_list, hhstream_session_handler=_cmd_stream_list, json=False
)
def add_stream_verb(name: str, handler, **kwargs: Any):
sub = streams.add_parser(name, parents=[common], **kwargs)
sub.set_defaults(func=handler, hhstream_session_handler=handler)
sub.add_argument("--json", action="store_true", help="emit the protocol object on stdout")
return sub
enable = add_stream_verb(
"enable",
_cmd_stream_enable,
help="switch a session's stream on and print its URL",
description=(
"Mint a phrase, open a capture, and print the URL on stdout — so "
"$(hhstream session stream enable ID) is the URL and nothing "
"else. The phrase is kept in the session's record, so it survives "
"a broker restart and a re-enable: somebody you read it out to "
"keeps the URL you gave them.\n\n"
"Re-enabling an enabled session prints the same URL. A --phrase "
"that differs from the stored one is exit 8 rather than a silent "
"rotation, because rotating under a caller holding the old URL is "
"the one outcome neither answer can be mistaken for. 'disable' "
"then 'enable' rotates it."
),
epilog=f"{STREAM_NOTE}\n\n{ACTIVITY_NOTE}",
formatter_class=argparse.RawDescriptionHelpFormatter,
)
enable.add_argument("id", help="session id")
enable.add_argument(
"--phrase",
metavar="PHRASE",
help="use this phrase instead of a minted one. Held to exactly the "
"generated shape (four words of 3+ letters, then a five-character "
"tail): it is a password, and a looser check would accept 'a-b-c'.",
)
enable.add_argument(
"--fps",
type=int,
metavar="N",
help="frames per second (default: the broker's; the daemon caps it)",
)
disable = add_stream_verb(
"disable",
_cmd_stream_disable,
help="switch a session's stream off and forget its phrase",
description=(
"Close the capture, drop the route, and clear the record. The "
"phrase is gone: a later 'enable' mints a new one, which is how a "
"phrase is rotated.\n\n"
"Disabling a stream the daemon has already forgotten is not an "
"error — that is the ordinary case after the daemon restarts, and "
"the record has to be cleared either way. 'detached' says which "
"happened."
),
)
disable.add_argument("id", help="session id")
add_stream_verb(
"list",
_cmd_stream_list,
help="every session with a stream (does NOT count as activity)",
description=(
"Every session a stream was enabled on, with its output, rate and "
"connected viewer count. The phrase is shown only under --json: "
"this listing is the kind of thing that ends up in a terminal "
"somebody is sharing, and the phrase is the credential.\n\n"
"'available' is whether the stream daemon could be asked at all, "
"so 'no streams' is distinguishable from 'no daemon' without "
"parsing an error."
),
)
status = add_stream_verb(
"status",
_cmd_stream_status,
help="one session's stream (does NOT count as activity)",
)
status.add_argument("id", nargs="?", help="session id; omit for all of them")
def _button_help() -> str:
return f"one of: {', '.join(BUTTONS)} (default: left)"
@@ -749,6 +906,9 @@ def _cmd_start(args: argparse.Namespace) -> int:
home=args.home,
ephemeral_home=args.ephemeral_home or None,
request_id=args.request_id,
stream=args.stream or None,
stream_phrase=args.stream_phrase,
stream_fps=args.stream_fps,
)
if not reply.get("ok"):
# A failed start may still have created a session (it exited at once, or
@@ -778,6 +938,27 @@ def _cmd_start(args: argparse.Namespace) -> int:
"(the only mark of activity; list/status/logs/gc do not count)",
file=sys.stderr,
)
if args.stream:
stream = session.get("stream") or {}
error = session.get("stream_error")
if stream.get("url"):
# stdout, beside the id: the URL is the other thing a caller asked
# for, and `$(... --stream)` giving the id and the URL on two lines
# is more useful than making them run a second verb for it.
print(stream["url"])
print(
f"watching it counts as activity; stop it with: hhstream "
f"session stream disable {session_id}",
file=sys.stderr,
)
else:
# The session started. Saying so loudly, because the exit code is
# 0 and a caller who asked for a stream must not read that as one.
print(
f"WARNING: the session is running but its stream was not "
f"enabled: {error or 'the broker reported no stream'}",
file=sys.stderr,
)
return int(ExitCode.OK)
@@ -1312,6 +1493,77 @@ def _cmd_keyboard_hold(args: argparse.Namespace) -> int:
return _finish_gesture(args, reply, render, args.id)
# --------------------------------------------------------------------------
# the live stream
# --------------------------------------------------------------------------
@_guard
def _cmd_stream_enable(args: argparse.Namespace) -> int:
reply = _request(
args, "stream.enable", id=args.id, phrase=args.phrase, fps=args.fps
)
if not reply.get("ok"):
return _finish(args, reply, lambda r: "")
if args.json:
fmt.dump_json(reply)
return int(ExitCode.OK)
stream = reply.get("stream") or {}
# stdout is the URL and nothing else, the same shape `start` and `pointer
# acquire` already have: one token a caller passes on, detail on stderr.
print(stream.get("url") or "")
print(
f"{reply.get('id')}: streaming output {stream.get('output')} "
f"at {stream.get('fps')} fps",
file=sys.stderr,
)
print(
"the phrase in that URL is its only protection, and watching it counts "
"as activity; stop it with: hhstream session stream disable "
f"{reply.get('id')}",
file=sys.stderr,
)
if not stream.get("attached"):
# `enable` cannot normally get here -- it had to attach to succeed --
# but a reply without it means the daemon answered and then went away,
# and a printed URL that serves nothing is worse than a warning.
print(
"WARNING: the broker recorded this stream but the daemon did not "
"confirm it is attached; the URL may not answer",
file=sys.stderr,
)
return int(ExitCode.OK)
@_guard
def _cmd_stream_disable(args: argparse.Namespace) -> int:
reply = _request(args, "stream.disable", id=args.id)
def render(r: dict[str, Any]) -> str:
detached = r.get("detached")
return (
f"{r.get('id')}: stream disabled and its phrase forgotten"
+ ("" if detached else "; the daemon had already dropped it")
)
return _finish(args, reply, render)
@_guard
def _cmd_stream_list(args: argparse.Namespace) -> int:
reply = _request(args, "stream.list")
return _finish(args, reply, fmt.render_streams)
@_guard
def _cmd_stream_status(args: argparse.Namespace) -> int:
session_id = getattr(args, "id", None)
reply = _request(args, "stream.status", id=session_id)
if session_id is None:
return _finish(args, reply, fmt.render_streams)
return _finish(args, reply, fmt.render_stream)
# --------------------------------------------------------------------------
# standalone use
# --------------------------------------------------------------------------
+81
View File
@@ -120,6 +120,87 @@ def render_list(
)
def render_streams(reply: dict[str, Any]) -> str:
"""``session stream list``: what is published, and who is watching.
**The phrase is not in this table**, and that is the whole shape of it. A
listing is the kind of thing that ends up in a shared terminal, a paste or
a screenshot, and the phrase is the stream's only credential — so what is
shown is enough to recognise and manage a stream (the session, the output,
the rate, the viewers) and not enough to watch one. ``--json`` carries the
phrase and the URL, because a caller that asked for the object asked for
the credential too.
``available`` is printed even when there are streams: "two records and no
daemon" is a different situation from "two records and two captures", and
the difference is invisible from the rows alone.
"""
rows = []
for row in reply.get("streams") or []:
rows.append(
[
_cell(row.get("id")),
_cell(row.get("app")),
_cell(row.get("output")),
_cell(row.get("fps")),
"yes" if row.get("attached") else "NO",
_cell(row.get("viewers")),
]
)
lines = [
render_table(rows, ["ID", "APP", "OUTPUT", "FPS", "LIVE", "VIEWERS"])
if rows
else "no session has a stream enabled"
]
available = reply.get("available")
lines.append(
"daemon: "
+ (
"answering"
if available
else "NOT REACHABLE — the records below are what was asked for, "
"not what is running"
)
)
if rows:
lines.append(
"the URL (with its phrase) is in --json, or in `stream status <id>`"
)
return "\n".join(lines)
def render_stream(reply: dict[str, Any]) -> str:
"""``session stream status ID``: one session's stream, URL included.
The URL *is* here, unlike in the listing: this was asked about one session
by name, which is what somebody about to watch it does, and making them
reach for ``--json`` to get the thing the verb is for would be a worse
trade than the one the listing makes.
"""
stream = reply.get("stream")
if not stream:
return f"{_cell(reply.get('id'))}: no stream enabled"
lines = [
f"{_cell(reply.get('id'))}: output {_cell(stream.get('output'))} "
f"at {_cell(stream.get('fps'))} fps",
]
if stream.get("attached"):
lines.append(f" url {_cell(stream.get('url'))}")
lines.append(f" viewers {_cell(stream.get('viewers'))}")
else:
# No URL, deliberately: the record's phrase is still there, but a URL
# that no longer serves anything is worse than none. See
# `SessionManager._stream_public`.
lines.append(
" url — (the daemon is not publishing this; the phrase is "
"kept, so re-enabling restores the same URL)"
)
lines.append(f" enabled {_cell(stream.get('enabled_at'))}")
return "\n".join(lines)
def render_containers(reply: dict[str, Any]) -> str:
"""``session container`` with no id: every container, and every orphan.
+301
View File
@@ -0,0 +1,301 @@
"""The broker's end of the stream daemon's socket (CONTRACT-sessions.md §3.5).
`hhstream-live` is a third executor beside the pointer driver, and this module
is the client that talks to it. The split is the driver's, for the driver's
reasons: ``grim`` blocks tens to hundreds of milliseconds, so the capture must
not run where ``touch`` and ``kill`` are answered, and a LAN-facing HTTP parser
must not run in the frame server whose one-socket contract cannot grow one.
**The broker holds the decision; the daemon holds the capture.** Which session
streams, and under which phrase, is the broker's — it is in the session record
and it survives a restart. The port, the bind address, the capture command and
the URL prefix are the daemon's, from its own unit's argv. So nothing here
passes a port and nothing here builds a URL: :attr:`Attachment.url` comes back
from the daemon, because a URL assembled from a port the broker was told about
once is a URL that lies the first time an operator moves the listener.
**The phrase is never logged.** It is the stream's only credential, in
cleartext in a URL on whatever the bind allows. Every log line here names the
output and the session; `_safe` is what keeps a phrase out of the ones that
would otherwise carry it.
Transport, lifetime and failure semantics are :mod:`hhstreamd.driver`'s, down to
the held connection and the EOF check before each write. One difference in
what a failure *means*: a dropped `release_all` leaves a key down in the
compositor, which is why the driver never retries; a dropped `attach` leaves
nothing behind but an unattached phrase, so `attach` is **idempotent on the
daemon's side** and re-sending it is safe. That is the daemon's guarantee, not
this module's, and it is what makes re-enabling after a restart cheap.
"""
from __future__ import annotations
import dataclasses
import json
import logging
import select
import socket
import threading
from pathlib import Path
from typing import Any
log = logging.getLogger("hhstreamd.live")
#: The daemon answers from memory for every op here -- it does not capture a
#: frame to answer `attach`, and `viewers` is a counter read. This only bounds
#: a daemon that has stopped answering at all.
DEFAULT_TIMEOUT_S = 2.0
#: Matches the daemon's own ceiling.
MAX_LINE_BYTES = 1 << 20
class LiveUnavailable(Exception):
"""The daemon could not be reached, or did not answer intelligibly.
Distinct from :class:`LiveRejected`: this one means nothing is known about
whether the stream is attached, so the caller reports a *degraded* stream
rather than an absent one. The session is unaffected either way -- a
stream that cannot be reached is a stream, not a dead application -- which
is why the manager maps this to exit 10 and never to a session failure.
"""
class LiveRejected(Exception):
"""The daemon refused. ``kind`` decides the exit code, as the driver's does."""
def __init__(self, message: str, *, kind: str | None = None) -> None:
super().__init__(message)
self.kind = kind
@dataclasses.dataclass(frozen=True)
class Attachment:
"""One stream, as the daemon reports it."""
phrase: str
output: str
fps: int
session: str | None
#: The daemon's own prefix, e.g. ``http://127.0.0.1:9988/<phrase>/``.
url: str
viewers: int
@classmethod
def parse(cls, data: Any) -> "Attachment":
if not isinstance(data, dict):
raise ValueError(f"stream is not an object: {type(data).__name__}")
try:
return cls(
phrase=str(data["phrase"]),
output=str(data["output"]),
fps=int(data["fps"]),
session=None if data.get("session") is None else str(data["session"]),
url=str(data.get("url") or ""),
viewers=int(data.get("viewers") or 0),
)
except (KeyError, TypeError, ValueError) as exc:
raise ValueError(f"malformed stream in the daemon's reply: {exc}") from exc
def _safe(phrase: str) -> str:
"""A phrase, for a log line. The shape, never the words.
``amber-otter-lantern-harbor-7k2qp`` becomes ``<phrase:5 tokens>``. A log
is read by whoever can read logs, and this one is a password.
"""
return f"<phrase:{len(phrase.split('-'))} tokens>"
class LiveStreams:
"""A client for one stream daemon's socket. Thread-safe; one op at a time."""
def __init__(self, socket_path: Path | str, *, timeout_s: float = DEFAULT_TIMEOUT_S) -> None:
self.socket_path = Path(socket_path)
self.timeout_s = float(timeout_s)
self._lock = threading.Lock()
self._sock: socket.socket | None = None
self._stream = None
# -- the ops ----------------------------------------------------------
def attach(
self,
*,
phrase: str,
output: str,
fps: int | None = None,
session: str | None = None,
label: str = "",
) -> Attachment:
"""Publish ``output`` under ``phrase``. Idempotent on the phrase.
The daemon returns the existing stream if the same phrase is already
aimed at the same output, rather than starting a second capture: a
re-enable after a broker restart must not double the ``grim`` rate on
one output. The same phrase aimed somewhere else is a rejection.
``fps`` is **omitted** when nobody asked for one, and that is the point:
the default rate 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 make the operator's ``sessions.stream.fps`` a setting that changed
nothing -- which is exactly the failure the keyboard layout's
``--xkb-layout`` comment in this tree is about.
"""
request: dict[str, Any] = {
"op": "attach",
"phrase": phrase,
"output": output,
"session": session,
"label": label,
}
if fps is not None:
request["fps"] = int(fps)
reply = self.request(request)
attachment = Attachment.parse(reply.get("stream"))
log.info(
"attached %s to output %s at %s fps (%s)",
session or "a standalone stream",
output,
attachment.fps,
_safe(phrase),
)
return attachment
def detach(self, phrase: str) -> bool:
"""Stop publishing ``phrase``. ``False`` if it was not attached.
Not an error: ``disable`` on a session whose daemon restarted since
``enable`` is the ordinary case, and the caller's job is to clear the
record either way.
"""
reply = self.request({"op": "detach", "phrase": phrase})
return bool(reply.get("detached"))
def list(self) -> list[Attachment]:
"""Every stream the daemon is publishing, in its own order."""
reply = self.request({"op": "list"})
streams = reply.get("streams")
if not isinstance(streams, list):
raise LiveUnavailable(
f"stream daemon {self.socket_path}: `list` returned "
f"{type(streams).__name__}, not a list"
)
try:
return [Attachment.parse(entry) for entry in streams]
except ValueError as exc:
raise LiveUnavailable(f"stream daemon {self.socket_path}: {exc}") from exc
def viewers(self) -> dict[str, int]:
"""Phrase to connected viewers, for the activity sweep (§4).
A reading, and nothing more: what it means for the idle clock is the
manager's, and this module deliberately has no opinion about it.
"""
reply = self.request({"op": "viewers"})
counts = reply.get("viewers")
if not isinstance(counts, dict):
raise LiveUnavailable(
f"stream daemon {self.socket_path}: `viewers` returned "
f"{type(counts).__name__}, not an object"
)
read: dict[str, int] = {}
for phrase, count in counts.items():
try:
read[str(phrase)] = int(count)
except (TypeError, ValueError) as exc:
raise LiveUnavailable(
f"stream daemon {self.socket_path}: viewer count for "
f"{_safe(str(phrase))} is not a number: {exc}"
) from exc
return read
# -- transport --------------------------------------------------------
def request(self, message: dict[str, Any]) -> dict[str, Any]:
"""One request, one reply. Raises rather than returning a guess."""
with self._lock:
try:
return self._exchange(message)
except (OSError, ValueError) as exc:
# The connection is now of unknown state -- a half-written
# request, a partial reply -- so it is dropped rather than
# reused for the next op.
self._disconnect()
raise LiveUnavailable(f"stream daemon {self.socket_path}: {exc}") from exc
def close(self) -> None:
with self._lock:
self._disconnect()
def _exchange(self, message: dict[str, Any]) -> dict[str, Any]:
stream = self._connect()
line = json.dumps(message, separators=(",", ":")).encode("utf-8") + b"\n"
stream.write(line)
stream.flush()
reply_line = stream.readline(MAX_LINE_BYTES + 1)
if not reply_line:
raise OSError("the daemon closed the connection without answering")
if len(reply_line) > MAX_LINE_BYTES:
raise ValueError("reply exceeds the frame limit")
reply = json.loads(reply_line)
if not isinstance(reply, dict):
raise ValueError(f"reply is not an object: {type(reply).__name__}")
if not reply.get("ok"):
kind = reply.get("kind")
raise LiveRejected(
str(reply.get("error") or "the stream daemon refused the request"),
kind=kind if isinstance(kind, str) else None,
)
return reply
def _connect(self):
if self._stream is not None and not self._stale():
return self._stream
self._disconnect()
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
try:
sock.settimeout(self.timeout_s)
sock.connect(str(self.socket_path))
except OSError:
sock.close()
raise
self._sock = sock
self._stream = sock.makefile("rwb")
log.debug("connected to the stream daemon at %s", self.socket_path)
return self._stream
def _stale(self) -> bool:
"""True if the held connection has died since the last op.
The daemon never speaks unsolicited, so a readable socket can only be
at EOF. One non-blocking ``select``, and it is what makes reconnecting
safe: a request is written only to a connection that was alive when it
was written.
"""
sock = self._sock
if sock is None:
return True
try:
readable, _, _ = select.select([sock], [], [], 0)
except (OSError, ValueError):
return True
return bool(readable)
def _disconnect(self) -> None:
stream, self._stream = self._stream, None
sock, self._sock = self._sock, None
for closeable in (stream, sock):
if closeable is None:
continue
try:
closeable.close()
except OSError:
pass
+468 -4
View File
@@ -57,6 +57,7 @@ from .container_host import (
ContainerHost,
)
from .driver import DriverRejected, DriverUnavailable, PointerDriver
from .live import Attachment, LiveRejected, LiveStreams, LiveUnavailable
from .ipc import CompositorUnavailable
from .launcher import Launcher
from .pointer import Bookmark, LeaseBusy, LeaseInvalid, PointerLease
@@ -70,6 +71,7 @@ from .registry import (
State,
container_record,
pointer_record,
stream_record,
)
from .textio import tail_lines
@@ -110,6 +112,16 @@ READBACK_INTERVAL_S = 0.05
#: as long as nobody asks.
POINTER_SWEEP_S = 1.0
#: How often the broker asks the stream daemon for viewer counts, and stamps
#: `touch` on every session that has one (CONTRACT-sessions.md §4).
#:
#: A minute, not a second: this is the one exception to "`touch` is the only
#: mark of activity", and the thing it exists to prevent is a three-hour idle
#: timeout firing under somebody's eyes. Against three hours a minute of
#: granularity is free, and a tighter sweep would be one `grim`-adjacent round
#: trip per second for a fact that changes when a browser tab opens.
STREAM_SWEEP_S = 60.0
#: The workspace band (CONTRACT-sessions.md §5) and how many slots of it this
#: broker will hand out. The real ceiling is a CPU question the plan defers to
#: a measurement (PLAN §5.5); the band is the part that can be enforced here,
@@ -199,8 +211,17 @@ class ManagerConfig:
pointer_ttl_s: float = 30.0
pointer_max_s: float = 300.0
pointer_sweep_s: float = POINTER_SWEEP_S
#: The broker↔stream socket (CONTRACT-sessions.md §3.5). Derived from the
#: runtime dir for the reason `pointer_socket` is: the path is frozen, so a
#: flag for it would be a flag for a value that may not vary.
live_socket: Path | None = None
#: How often the viewer sweep runs. The one thing that moves an idle clock
#: without a caller asking (CONTRACT-sessions.md §4).
stream_sweep_s: float = STREAM_SWEEP_S
def __post_init__(self) -> None:
if self.live_socket is None:
self.live_socket = Path(self.runtime_dir) / "live.sock"
if self.pointer_socket is None:
# `<runtime dir>/pointer.sock` is the frozen path
# (CONTRACT-sessions.md §5: /run/hhstream/pointer.sock), and
@@ -221,6 +242,7 @@ class SessionManager:
audit: AuditLog | None = None,
host: ContainerHost | None = None,
driver: PointerDriver | None = None,
live: LiveStreams | None = None,
) -> None:
self.config = config
self.clock = clock or Clock()
@@ -251,6 +273,10 @@ class SessionManager:
ttl_s=config.pointer_ttl_s, max_s=config.pointer_max_s, clock=self.clock.boottime
)
self.driver = driver
#: The stream daemon's client, or ``None`` with no socket configured --
#: in which case every `stream.*` verb answers `stream_unavailable`
#: (exit 10) rather than pretending there is a stream.
self.live = live
# Per-session asyncio plumbing, never persisted.
self._exited: dict[str, asyncio.Event] = {}
self._watchers: dict[str, asyncio.Task] = {}
@@ -259,6 +285,7 @@ class SessionManager:
#: Held so the loop does not collect a task mid-flight.
self._background: set[asyncio.Task] = set()
self._pointer_sweeper: asyncio.Task | None = None
self._stream_sweeper: asyncio.Task | None = None
#: Set while a lease is held with a caller-supplied TTL, so the default
#: comes back when the lease ends (the frozen ``acquire`` takes no TTL).
self._pointer_ttl_override = False
@@ -339,6 +366,13 @@ class SessionManager:
self._pointer_sweeper = asyncio.create_task(
self._sweep_pointer(), name="hhstreamd.pointer-sweep"
)
# Unconditional, even with no stream enabled anywhere: the sweep's own
# first act is to ask the daemon, and a broker that only started it on
# the first `enable` would be a broker whose adopted records were not
# being watched after a restart.
self._stream_sweeper = asyncio.create_task(
self._sweep_streams(), name="hhstreamd.stream-sweep"
)
return summary
# ------------------------------------------------------------------
@@ -632,11 +666,14 @@ class SessionManager:
"""
await self.reaper.stop()
if self._pointer_sweeper is not None:
self._pointer_sweeper.cancel()
for name in ("_pointer_sweeper", "_stream_sweeper"):
sweeper = getattr(self, name)
if sweeper is None:
continue
sweeper.cancel()
with contextlib.suppress(asyncio.CancelledError, Exception):
await self._pointer_sweeper
self._pointer_sweeper = None
await sweeper
setattr(self, name, None)
for task in list(self._background):
task.cancel()
for task in list(self._background):
@@ -650,6 +687,12 @@ class SessionManager:
with contextlib.suppress(Exception):
await self._release_all_buttons()
self.driver.close()
if self.live is not None:
# Nothing to lift on this one: a stream left attached across a
# broker restart is re-attached by `enable`, and the daemon keeps
# publishing meanwhile -- which is the behaviour an operator
# watching a long job wants.
self.live.close()
for task in list(self._watchers.values()):
task.cancel()
for task in list(self._watchers.values()):
@@ -878,6 +921,9 @@ class SessionManager:
wait_ready_s: float | None = None,
home: str | None = None,
ephemeral_home: bool = False,
stream: bool = False,
stream_phrase: str | None = None,
stream_fps: int | None = None,
) -> dict[str, Any]:
policy = self.config.policy
policy.check_capacity(len(self.registry.live()))
@@ -971,8 +1017,38 @@ class SessionManager:
ready = await self._settle(session, wait_ready)
if session.live:
await self._read_back(session, app_id)
stream_error: str | None = None
if stream and session.live:
# After the read-back, because that is what settles the container's
# output, and a stream has to have one to publish
# (`_stream_output`). Before the record below, so the phrase comes
# back with the session the caller asked for -- which is the whole
# reason `start` takes these arguments instead of making every
# caller sequence "start, then enable" and handle the half-done
# case in between.
#
# A stream that cannot be opened does NOT fail the start. The
# application is on the screen and killing it over a web page would
# be the wrong trade; the refusal is reported on the session's
# `stream_error` and the caller can retry `stream.enable`.
try:
await self.stream_enable(
session.id, phrase=stream_phrase, fps=stream_fps
)
except ManagerError as exc:
log.warning("could not enable %s's stream: %s", session.id, exc.reason)
session.last_error = session.last_error or exc.reason
# A local, not an attribute: two starts can be in flight at
# once and an attribute would hand one of them the other's
# failure.
stream_error = exc.reason
self.reaper.wake()
record = session.public(self.now())
if stream:
# Present whenever a stream was asked for, `None` when it worked:
# a key that appears only on failure is a key every caller has to
# remember to look for.
record["stream_error"] = stream_error
if session.state == State.EXITED:
# The app exited during the settle: surface it rather than handing
# back a healthy-looking id (DESIGN.md §7 #3).
@@ -1235,7 +1311,17 @@ class SessionManager:
# has four values (lease|timeout|crash|kill), and a reap is the
# broker killing the session.
await self._drop_lease_for(session, reason="kill")
# The stream goes BEFORE the output does, and the order is
# load-bearing (CONTRACT-sessions.md §4): a capture aimed at a
# removed output fails every time, so the daemon's own failure
# budget would close the viewers with "unknown output" instead of
# the session simply ending. Never raises -- a daemon that cannot
# be reached must not stop a session being killed.
stream_detached = await self._detach_stream(session)
if (session.stream or {}).get("phrase"):
session.stream = None
container_result = self._destroy_container(session)
container_result["stream_detached"] = stream_detached
if refused is None:
state_now = state
@@ -1929,6 +2015,368 @@ class SessionManager:
# -- lease internals --------------------------------------------------
# ------------------------------------------------------------------
# the live stream (CONTRACT-sessions.md §4, v4)
# ------------------------------------------------------------------
async def stream_enable(
self, session_id: str, *, phrase: str | None = None, fps: int | None = None
) -> dict[str, Any]:
"""Publish this session's container output under a spoken phrase.
**Does not** count as activity, like every `pointer.*` verb: switching
a stream on is not saying the session is wanted. What *is* activity is
somebody watching it, and that is :meth:`_sweep_streams`.
The phrase is minted here and stored in the record, so it survives a
broker restart and a re-enable: an operator who read four words out to
somebody must not have them change because the daemon bounced. A
caller's own `phrase` is held to the generated shape -- it is this
stream's only credential, so anything a caller may set is a password,
and a looser check would accept `a-b-c`.
Re-enabling an enabled session returns the same phrase. A different
`phrase` is `stream_busy` (exit 8) rather than a silent rotation,
because rotating under a caller who is holding the old URL is the one
outcome neither answer can be mistaken for.
"""
session = self._require_live(session_id)
output = self._stream_output(session)
rate = self._checked_fps(fps)
stored = session.stream or {}
wanted = self._checked_phrase(phrase)
if stored.get("phrase") and wanted and wanted != stored["phrase"]:
raise ManagerError(
"stream_busy",
f"session {session.id} already has a stream under a different phrase",
hint="`stream disable` then `stream enable` rotates it; a stream "
"cannot have two phrases, because the old one is a URL somebody "
"may be holding",
id=session.id,
)
settled = stored.get("phrase") or wanted or self._mint_phrase()
# The stored rate wins on a re-enable with no `fps`: a re-attach after a
# restart must not quietly re-rate a stream somebody is watching. With
# neither, the rate is left UNSET and the daemon applies its own
# configured default -- the broker does not have one, on purpose.
rate = rate or stored.get("fps")
attachment = await self._attach_stream(
session, phrase=settled, output=output, fps=None if rate is None else int(rate)
)
record = stream_record(
phrase=settled,
output=output,
fps=attachment.fps,
enabled_at=stored.get("enabled_at") or iso(self.clock.wall()),
)
session.stream = record
# `force=True`: the phrase is the one field here that cannot be
# re-derived, so it is on disk before the caller is told what it is.
self.registry.persist(session, force=True)
# The phrase is NOT in the audit entry (CONTRACT-sessions.md §3.5): the
# log is read by whoever can read logs, and this one is a password.
self.audit.emit(
"stream_enable", id=session.id, output=output, fps=attachment.fps
)
return {"id": session.id, "stream": self._stream_public(record, attachment)}
async def stream_disable(self, session_id: str) -> dict[str, Any]:
"""Stop publishing, and clear the record.
Detaching a stream the daemon has already forgotten is **not** an
error: `disable` after a daemon restart is the ordinary case, and the
record has to be cleared either way. `detached` says which happened.
"""
session = self._require_live(session_id)
stored = session.stream or {}
if not stored.get("phrase"):
raise ManagerError(
"stream_unavailable",
f"session {session.id} has no stream to disable",
hint="`stream enable` first",
id=session.id,
)
detached = await self._detach_stream(session)
session.stream = None
self.registry.persist(session, force=True)
self.audit.emit(
"stream_disable", id=session.id, output=stored.get("output"), detached=detached
)
return {"id": session.id, "stream": None, "detached": detached}
def stream_list(self) -> dict[str, Any]:
"""Every session with a stream, with the daemon's view merged in.
Does not count as activity. ``available`` is whether the daemon could
be asked at all, so a caller can tell "no streams" from "no daemon"
without parsing an error.
"""
attachments, available = self._attachments()
streams = []
for session in self.registry.live():
stored = session.stream or {}
if not stored.get("phrase"):
continue
streams.append(
{
"id": session.id,
"app": session.app,
**self._stream_public(stored, attachments.get(stored["phrase"])),
}
)
return {"streams": streams, "available": available}
def stream_status(self, session_id: str | None = None) -> dict[str, Any]:
"""One session's stream, or every one of them. Not activity."""
if session_id is None:
return self.stream_list()
session = self._require(session_id)
stored = session.stream or {}
if not stored.get("phrase"):
return {"id": session.id, "stream": None}
attachments, _ = self._attachments()
return {
"id": session.id,
"stream": self._stream_public(stored, attachments.get(stored["phrase"])),
}
# -- the pieces the four verbs share ---------------------------------
def _stream_output(self, session: Session) -> str:
"""The output a stream publishes: the session's own container.
Refused rather than defaulted, and the reason is stronger than the
pointer's: the main output carries *every other session*, so falling
back to it would put somebody else's desktop on a phone behind a phrase
that was issued for this one.
"""
output = (session.container or {}).get("output")
if output:
return str(output)
raise ManagerError(
"stream_unavailable",
f"session {session.id} has no container output to publish",
hint="a stream never falls back to the main output -- that one "
"carries every other session. `container.reconcile` once the "
"compositor is reachable, or start the session with containers on",
id=session.id,
container=session.container,
)
def _mint_phrase(self) -> str:
"""A fresh phrase.
From `hhstream_live.phrase`, which owns the wordlist, the shape and the
validator -- one definition, so a phrase the broker mints is one the
daemon will accept and a `--phrase` an operator types is held to the
same bar. Imported here rather than at module scope because this is the
only path that needs it and `hhstreamd` must stay importable without
the web app's wordlist being readable.
"""
from hhstream_live import phrase as phrase_mod
return phrase_mod.generate()
def _checked_phrase(self, phrase: Any) -> str | None:
if phrase is None:
return None
from hhstream_live import phrase as phrase_mod
if not isinstance(phrase, str):
raise ManagerError(
"invalid_argument", "phrase must be a string", id=None
)
try:
return phrase_mod.validate(phrase)
except ValueError:
# The validator's own message names the value it refused, which is
# right for an operator reading their own terminal and wrong here:
# this reason reaches the broker's log and the audit trail, and the
# value is a credential (CONTRACT-sessions.md §3.5). So the shape
# is described and the phrase is NOT interpolated -- deliberately,
# and `from None` so the chained message cannot carry it either.
raise ManagerError(
"invalid_argument",
"the phrase given is not of the expected shape",
hint="four words of at least three letters and a five-character "
"tail, e.g. amber-otter-lantern-harbor-7k2qp; omit it to have "
"one minted",
) from None
def _checked_fps(self, fps: Any) -> int | None:
if fps is None:
return None
if isinstance(fps, bool) or not isinstance(fps, int):
raise ManagerError(
"invalid_argument", f"fps must be an int, got {type(fps).__name__}"
)
if fps <= 0:
raise ManagerError("invalid_argument", f"fps must be positive, got {fps}")
# The ceiling is deliberately NOT checked here. It belongs to the
# daemon (`hhstream_live.publisher.FPS_CAP`), which is the process that
# has to keep up with it, and a second copy of the number here would be
# a second thing to raise when the box gets faster.
return fps
async def _attach_stream(
self, session: Session, *, phrase: str, output: str, fps: int | None
) -> Attachment:
live = self._live_streams()
if live is None:
raise ManagerError(
"stream_unavailable",
"no stream daemon is configured for this broker",
hint="the `hhstream-live` unit is what captures a stream; "
"`sessions.stream` in the module turns it on",
id=session.id,
)
try:
return await asyncio.to_thread(
live.attach,
phrase=phrase,
output=output,
fps=fps,
session=session.id,
label=session.app,
)
except LiveRejected as exc:
# The daemon's own vocabulary, mapped once: its `invalid_argument`
# is the caller's mistake (exit 2) and anything else is a stream
# that could not be opened (exit 10). The same split the driver's
# `kind` already gets.
error = "invalid_argument" if exc.kind == "invalid_argument" else "stream_unavailable"
raise ManagerError(error, str(exc), id=session.id) from exc
except LiveUnavailable as exc:
raise ManagerError(
"stream_unavailable",
f"the stream daemon could not be reached: {exc}",
hint="is hhstream-live running? the session itself is unaffected",
id=session.id,
) from exc
async def _detach_stream(self, session: Session) -> bool:
"""Stop the capture for this session, if there is one.
Never raises. Called from `disable`, which has a record to clear
regardless, and from teardown, where a daemon that cannot be reached
must not stop a session from being killed.
"""
phrase = (session.stream or {}).get("phrase")
live = self._live_streams()
if not phrase or live is None:
return False
try:
return await asyncio.to_thread(live.detach, str(phrase))
except (LiveRejected, LiveUnavailable) as exc:
log.warning(
"could not detach %s's stream on output %s: %s",
session.id,
(session.stream or {}).get("output"),
exc,
)
return False
def _attachments(self) -> tuple[dict[str, Attachment], bool]:
"""The daemon's streams by phrase, and whether it answered.
Synchronous and tolerant: the read verbs report what they can, and a
down daemon turns `attached` false rather than failing a `list` that
has records to show.
"""
live = self._live_streams()
if live is None:
return {}, False
try:
return {a.phrase: a for a in live.list()}, True
except (LiveRejected, LiveUnavailable) as exc:
log.debug("the stream daemon did not answer `list`: %s", exc)
return {}, False
@staticmethod
def _stream_public(
stored: dict[str, Any], attachment: Attachment | None
) -> dict[str, Any]:
"""The record, with the daemon's live view merged in.
``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" and "a capture is running right now" are two
different facts. ``url`` and ``viewers`` are *absent* when it is false,
rather than stale -- a URL that no longer serves anything is worse than
no URL.
"""
public = dict(stored)
public["attached"] = attachment is not None
if attachment is not None:
public["url"] = attachment.url
public["viewers"] = attachment.viewers
public["fps"] = attachment.fps
return public
async def _sweep_streams(self) -> None:
"""Stamp `touch` on every session somebody is watching.
The one exception to "`touch` is the only mark of activity"
(CONTRACT-sessions.md §4), and the only thing in this daemon that
treats an observation as an intention. It exists 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, so a forgotten `enable` is
not a leak -- which is why this is safe to run unconditionally.
"""
while True:
await asyncio.sleep(self.config.stream_sweep_s)
try:
await self._touch_watched()
except asyncio.CancelledError:
raise
except Exception: # noqa: BLE001 -- a sweep must outlive one failure
log.exception("the stream viewer sweep failed; continuing")
async def _touch_watched(self) -> list[str]:
"""One pass of the sweep. Returns the ids it touched."""
live = self._live_streams()
if live is None:
return []
try:
counts = await asyncio.to_thread(live.viewers)
except (LiveRejected, LiveUnavailable) as exc:
log.debug("the stream daemon did not answer `viewers`: %s", exc)
return []
touched: list[str] = []
for session in self.registry.live():
phrase = (session.stream or {}).get("phrase")
if not phrase:
continue
viewers = counts.get(str(phrase), 0)
if viewers <= 0:
continue
self.registry.touch(session, force_flush=True)
touched.append(session.id)
self.audit.emit(
"stream_viewer_activity",
id=session.id,
output=(session.stream or {}).get("output"),
viewers=viewers,
)
return touched
async def _sweep_pointer(self) -> None:
"""Expire a stale lease even when nobody asks.
@@ -2152,6 +2600,22 @@ class SessionManager:
self.driver = PointerDriver(self.config.pointer_socket)
return self.driver
# -- the stream daemon ------------------------------------------------
def _live_streams(self) -> LiveStreams | None:
"""The stream daemon's client, built on first use.
``None`` rather than raising, unlike :meth:`_pointer_driver`, and the
asymmetry is the point: a pointer verb with no driver is a verb that
cannot do its job, while a *read* of stream state with no daemon has a
true answer -- the records, with ``attached: false``. The write paths
(`_attach_stream`) raise `stream_unavailable` for themselves.
"""
if self.live is None and self.config.live_socket is not None:
self.live = LiveStreams(self.config.live_socket)
return self.live
async def _drive(self, verb: str, *args: Any) -> Any:
"""One driver call, off the event loop.
+21
View File
@@ -102,8 +102,17 @@ EXIT_CODE_FOR_ERROR: dict[str, ExitCode] = {
"pointer_busy": ExitCode.BUSY,
# 9 — the lease is required and not held
"no_lease": ExitCode.NO_LEASE,
# 8 — a phrase that is not this session's (v4)
"stream_busy": ExitCode.BUSY,
# 6 — the stream daemon's own cap (v4)
"stream_budget": ExitCode.POLICY,
# 10 — the compositor side failed; the session itself is fine
"compositor": ExitCode.COMPOSITOR,
# The stream could not be reached or has no output to aim at (v4). Exit 10
# for the reason `driver_refused` is: the *session* keeps running, and a
# caller that treated an unreachable stream as a dead session would kill an
# application over a web page.
"stream_unavailable": ExitCode.COMPOSITOR,
"compositor_unavailable": ExitCode.COMPOSITOR,
"no_container": ExitCode.COMPOSITOR,
"driver_unavailable": ExitCode.COMPOSITOR,
@@ -156,6 +165,12 @@ VERBS = (
# warp retargets the keys. So there is no `keyboard.acquire`.
"keyboard.key",
"keyboard.type",
# v4: the per-session live stream. `list` and `status` read; `enable` and
# `disable` are in the mutation set below.
"stream.enable",
"stream.disable",
"stream.list",
"stream.status",
)
#: Verbs whose reply is remembered by ``request_id``, so a caller that died
@@ -185,6 +200,12 @@ MUTATING_VERBS = frozenset(
# nothing, and a cached one would be a stale one.
"keyboard.key",
"keyboard.type",
# v4. `enable` mints or rotates a phrase: a retry that minted a second
# one would invalidate the URL somebody is already holding, and
# `disable` is here for symmetry -- a retried disable after a daemon
# restart must report what the first one did.
"stream.enable",
"stream.disable",
}
)
+57 -6
View File
@@ -23,11 +23,12 @@ from .clock import Clock, iso
log = logging.getLogger("hhstreamd.registry")
#: 3 adds the container, the pointer bookmark and the compositor signature
#: (PLAN §7). The number is read, never written by anyone but this module: a
#: record carrying an older one is **migrated on load** (:func:`migrate`), not
#: refused, because the processes it describes are still running and refusing
#: the record would strand them.
SCHEMA = 3
#: (PLAN §7); 4 adds the live stream (CONTRACT-sessions.md §6, v4). The number
#: is read, never written by anyone but this module: a record carrying an older
#: one is **migrated on load** (:func:`migrate`), not refused, because the
#: processes it describes are still running and refusing the record would
#: strand them.
SCHEMA = 4
#: Tombstones survive this long so a ``status`` after an unexplained failure
#: still answers the question. ``gc`` prunes them.
@@ -138,6 +139,17 @@ class Session:
#: ``{bookmark, last_released_at, released_by}``. Absent (``None``) means
#: the pointer was never aimed here — not that its position is unknown.
pointer: dict[str, Any] | None = None
#: The live stream, or ``None`` for a session nobody switched one on for
#: (CONTRACT-sessions.md §4). ``{enabled, phrase, output, fps, port,
#: enabled_at}``; the daemon's ``url`` and ``viewers`` are merged in by the
#: manager when it could be asked, and are deliberately not stored -- a
#: viewer count on disk is a number that is wrong the moment it is written.
#:
#: The phrase lives here because it has to survive a broker restart and a
#: re-enable: it is the stream's only credential, and an operator who read
#: four words out to somebody must not have them change underneath him
#: because the daemon bounced.
stream: dict[str, Any] | None = None
#: ``HYPRLAND_INSTANCE_SIGNATURE`` of the compositor this session's
#: container lives in, so a restarted broker re-attaches to the same
#: instance instead of picking whichever one is there now.
@@ -234,6 +246,38 @@ def container_record(
}
def stream_record(
*,
phrase: str,
output: str,
fps: int,
enabled_at: str,
) -> dict[str, Any]:
"""One ``stream`` sub-record (CONTRACT-sessions.md §4).
Only what survives a restart. The daemon's ``url`` and ``viewers`` are
merged in by the manager when it could be asked and are deliberately absent
here: a viewer count on disk is wrong the moment it is written, and a URL
assembled from a remembered port is a URL that lies the first time the
listener moves.
``enabled`` is always ``True`` in a stored record. A session that was
never enabled has ``stream: None``, and `disable` clears the field rather
than setting ``enabled: False`` -- "nobody asked for a stream here" and
"somebody asked and then stopped" are the same state as far as anything
downstream is concerned, and two spellings for one state is how a
`if stream:` check starts being wrong.
"""
return {
"enabled": True,
"phrase": phrase,
"output": output,
"fps": fps,
"enabled_at": enabled_at,
}
def pointer_record(
*,
bookmark: dict[str, Any] | None,
@@ -284,7 +328,14 @@ def migrate(data: dict[str, Any]) -> dict[str, Any]:
upgraded = dict(data)
# Only ever *adds* keys. A v2 record that somehow carries a container must
# keep it: the field is new to the schema, not new to the session.
for key in ("container", "pointer", "signature"):
#
# `stream` (schema 4) is `None` for the same reason the others are: a
# session written by a daemon that knew nothing of streams had no stream,
# and "no stream" is a defined value rather than a guess. It must NOT be
# invented as `{"enabled": false}` either -- a record that says it was
# asked about and declined is a different claim from one that was never
# asked.
for key in ("container", "pointer", "signature", "stream"):
upgraded.setdefault(key, None)
upgraded["schema"] = SCHEMA
log.info("migrated record %s from schema %s to %s", data.get("id"), schema, SCHEMA)
+33
View File
@@ -75,6 +75,10 @@ class ControlServer:
"pointer.state": self._op_pointer_state,
"keyboard.key": self._op_keyboard_key,
"keyboard.type": self._op_keyboard_type,
"stream.enable": self._op_stream_enable,
"stream.disable": self._op_stream_disable,
"stream.list": self._op_stream_list,
"stream.status": self._op_stream_status,
}
# ------------------------------------------------------------------
@@ -264,6 +268,9 @@ class ControlServer:
wait_ready_s=request.get("wait_ready_s"),
home=request.get("home"),
ephemeral_home=bool(request.get("ephemeral_home", False)),
stream=bool(request.get("stream", False)),
stream_phrase=request.get("stream_phrase"),
stream_fps=request.get("stream_fps"),
)
return protocol.ok(id=record["id"], state=record["state"], session=record)
@@ -297,6 +304,32 @@ class ControlServer:
)
return protocol.ok(id=record["id"], state=record["state"], session=record)
async def _op_stream_enable(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(
**await self.manager.stream_enable(
request.get("id"),
phrase=request.get("phrase"),
fps=request.get("fps"),
)
)
async def _op_stream_disable(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(**await self.manager.stream_disable(request.get("id")))
async def _op_stream_list(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(**self.manager.stream_list())
async def _op_stream_status(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(**self.manager.stream_status(request.get("id")))
async def _op_container_list(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]: