buzz: initial mirror

This commit is contained in:
Hermenix committed 2026-09-28 05:01:41 +00:00
commit 8993f026d3
13 files changed
+536

No files matched your search

+87
View File
@@ -0,0 +1,87 @@
# Wire contract (v1)
This file is the interface. Code on either side may change freely; **this
document may not**, without bumping the version.
## Socket
- Transport: `AF_UNIX`, `SOCK_STREAM`.
- Path: whatever `services.hyprland-headless-stream.socketPath` says.
Default `/run/hyprland-headless-stream/stream.sock`.
- Ownership: the service user (`user` option, default `hhstream`), mode `0660`.
- The server accepts **any number of concurrent clients**. Each client gets its
own copy of the header and of every subsequent frame. A client disconnecting
(or dying mid-frame) must never take the server down and must never disturb
the other clients.
- The server runs whether or not anyone is connected. No client is privileged.
- The socket path is removed and recreated on start; a stale socket file must
not prevent startup.
## Message sequence
**1. Hello.** Immediately on connect, the server writes exactly one UTF-8 JSON
object followed by a single `\n`:
```json
{"magic":"HHS1","width":1280,"height":720,"format":"image/png","fps":30}
```
Fields: `magic` (protocol tag, `HHS1`), `width`/`height` (pixels of the captured
output), `format` (`image/png` or `image/jpeg`), `fps` (target capture rate,
advisory — the server does not buffer to keep up).
**2. Frames.** Then, forever, one frame per message:
```
<ascii-decimal byte length><0x0A><payload — exactly that many bytes>
```
`payload` is one complete, independently decodable image in `format`.
Notes:
- Byte length counts the payload only, never the length prefix.
- The length prefix is plain ASCII digits; no leading zeros, no `+`, no spaces.
- Frames are never split, merged or interleaved on the wire. One length, one
payload.
- A client that stalls or reads slowly is *slowed*, not queued: the server drops
frames for that client rather than buffering them. Backpressure must never
grow unbounded memory.
- Shutdown: either side closes the socket. Nothing else is negotiated.
## Client → server direction
Reserved. In v1 a client sends **nothing**; any bytes received from a client are
read and ignored. (This leaves room to add a control channel later without
breaking v1 readers, which never expect inbound data.)
## Failure semantics
- 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.
## NixOS module surface
Namespace: `services.hyprland-headless-stream`
| Option | Type | Default | Meaning |
|---|---|---|---|
| `enable` | bool | `false` | turn everything on |
| `socketPath` | str | `/run/hyprland-headless-stream/stream.sock` | published socket |
| `user` / `group` | str | `hhstream` | owner of the session and the socket |
| `frameRate` | int | `30` | capture target, becomes `fps` in Hello |
| `format` | enum `png`/`jpeg` | `png` | frame encoding |
| `outputs` | list of attrsets | one 1280×720@30 `HEADLESS-1` | virtual monitors: `name`, `width`, `height`, `refresh`, `scale` |
| `extraConfig` | str | `""` | extra lines appended to `hyprland.conf` |
| `hyprlandPackage` | package | `pkgs.hyprland` | which compositor |
| `package` | package | the flake's own build | the frame server/client |
| `captureCommand` | list of str | `[ "grim" … ]` | override the capture backend — used by tests |
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.