docs: pin the server command line in the contract; add ARCHITECTURE.md
This commit is contained in:
1 parent
578e14286d
commit
db886faa38
2 files changed
+110
-3
No files matched your search
@@ -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.
|
||||
+34
-3
@@ -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.
|
||||
Reference in new issue
Block a user