diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..8dd103e --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,76 @@ +# Architecture + +``` + ┌──────────────────────────────────────────┐ + │ hyprland-headless.service │ + │ Hyprland 0.56.2, no physical monitor │ + │ private XDG_RUNTIME_DIR, as `user` │ + │ outputs come from `outputs[]` │ + └───────────────┬──────────────────────────┘ + │ Wayland session + ▼ + ┌──────────────────────────────────────────┐ + │ hyprland-headless-stream.service │ + │ hhstream-server │ + │ capture ──▶ one "latest frame" slot │ + │ accept ──▶ a thread per client │ + └───────────────┬──────────────────────────┘ + │ AF_UNIX, mode 0660 + ▼ + many clients ── hhstream-client / any socket reader +``` + +Three pieces, deliberately separate: + +1. **The compositor** (`Hyprland`, unchanged upstream) renders into virtual + outputs. It knows nothing about frames on a socket. +2. **The frame server** (`hhstream`) captures, holds exactly one frame, and + publishes it. It owns the socket, the framing and the drop policy. +3. **The client** is any process that can open a Unix socket and read the + contract's byte format. The shipped `hhstream-client` is a convenience, not a + requirement. + +## Why one frame, not a queue + +The server keeps a single slot holding the most recent frame. Each client thread +sends whatever is in that slot when it is ready. A client that cannot keep up +therefore misses frames instead of forcing the server to buffer them: memory use +does not grow with the number of stalled clients, and a stalled client cannot +delay the others. See `docs/CONTRACT.md` for exactly what a client observes. + +## Capture + +Capturing is a separate program (by default `grim`, a wlr-screencopy client) run +inside the compositor's session and pointed at stdout. That choice is what keeps +`hhstream` free of Wayland and GPU code — the awkward part lives in a tool that +already exists and is already tested — and it is why the capture command is a +module option: tests inject a fake, and a future backend (a native screencopy +client, a hardware encoder) is a command-line swap rather than a rewrite. + +## The hardware requirement, stated plainly + +`Hyprland` 0.56.2 asks aquamarine for its **headless backend as mandatory** +(`src/Compositor.cpp`) and does not accept the DRM backend if it is +unavailable. Aquamarine's headless backend still needs an EGL/GBM **render +node**; there is no software-only path that works without one. Consequently a +host with no graphics device at all (`/dev/dri` missing) cannot run this, and +Pyprland fails with `CBackend::create() failed!` before any of its managers come +up. + +So the requirements are: + +- a render node, i.e. `/dev/dri/renderD*` — from a real GPU, a virtual GPU + (`virtio-gpu`, `virtio-gpu-gl`, QXL) or a NixOS test VM's own QEMU display; +- the `video`/`render` groups for whichever user runs it (the module sets them). + +## Testing, and what each layer proves + +| Layer | Proves | +|---|---| +| `tests/unit` | the framing, the capture wrapper and the server's client handling, with no compositor and no GPU | +| `checks.vm-basic` | the module actually starts both units, the socket appears with the right owner/mode, the Hello parses and two frames arrive — with a fake capture program | +| `checks.vm-hyprland` | the real thing: headless Hyprland comes up in the VM and `grim` captures a frame of the configured size | + +`vm-hyprland` is the only check that can fail for reasons outside this repo, so +it is kept separate from `vm-basic` on purpose: when it fails, the compositor's +log is the answer and the other two layers are already known good. \ No newline at end of file diff --git a/docs/CONTRACT.md b/docs/CONTRACT.md index fef3bb4..2ddb051 100644 --- a/docs/CONTRACT.md +++ b/docs/CONTRACT.md @@ -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. \ No newline at end of file + 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 --fps --format \ + [--capture-command ...] +``` + +- `--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=` form is accepted as well, and + the two may be mixed. When absent, the server derives `grim -t -`. +- 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. \ No newline at end of file