docs: pin the server command line in the contract; add ARCHITECTURE.md

This commit is contained in:
Hermenix committed 2026-09-28 11:53:19 +00:00
1 parent 578e14286d
commit db886faa38
2 files changed
+110 -3

No files matched your search

+34 -3
View File
@@ -59,8 +59,17 @@ breaking v1 readers, which never expect inbound data.)
- Compositor not running / capture tool erroring: the server keeps the socket up
and retries; it does **not** exit and it does **not** send partial frames.
- If a Hello cannot be produced (no output size known yet), the server waits
until it can, then sends it. It never sends a Hello with zero size.
- **Hello timing.** The Hello is written the moment the server can produce it,
which in practice is the moment of the first successful capture. A client that
connects before that has received zero bytes and simply waits: the server
never sends a Hello with a zero or unknown size. ("Immediately" above means
"before any frame", not "before the first capture".)
- `width`/`height` in the Hello are **measured from the captured frame**, not
taken from configuration, so they cannot disagree with the pixels actually
being sent.
- A client that is torn down or killed *mid-frame* may see a truncated final
frame. "Never sends partial frames" is about the server failing to capture,
not about a client that has already gone away.
## NixOS module surface
@@ -84,4 +93,26 @@ Services (names are part of the contract, tests refer to them):
- `hyprland-headless.service` — the compositor, running as `user`, on a private
`XDG_RUNTIME_DIR`, with no physical output.
- `hyprland-headless-stream.service` — the frame server, `After=` the compositor,
with `Restart=always`, connected to the same session.
with `Restart=always`, connected to the same session.
## Server command line
The module drives the server, so its flags are an interface too — the same
status as the wire format. Exactly this shape, and no others:
```
hhstream-server --socket <socketPath> --fps <frameRate> --format <png|jpeg> \
[--capture-command <token> ...]
```
- `--format` takes the **short name** (`png`, `jpeg`), not a MIME type; the
server maps it to `image/png` / `image/jpeg` for the Hello.
- `--capture-command` is **repeated, one argv token per occurrence**:
`--capture-command grim --capture-command -t --capture-command png
--capture-command -`. A single shell string cannot carry a leading `-`
unambiguously. The `--capture-command=<token>` form is accepted as well, and
the two may be mixed. When absent, the server derives `grim -t <format> -`.
- There is deliberately **no** `--width` / `--height`: the Hello reports the
captured frame's real size (see above).
- The socket's **mode** (0660) is the server's business; its **ownership** is
the systemd unit's (`user`/`group`), because the server cannot chown.