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