Compare commits

...
Author SHA1 Message Date
HermenixandClaude Opus 5 a37b3dd485 checks: give both VM machines a virtio GPU, and say why when it is not enough
`nix build .#checks.x86_64-linux.vm-basic` failed because Hyprland 0.56.2
aborted with `CBackend::create() failed!` on every start. Reading aquamarine
0.15.1 rather than guessing at it, that abort had three independent causes on a
NixOS test machine, and none of them is visible in the journal until
`debug:disable_logs = false` is set -- Hyprland mutes aquamarine, so the abort
is all that survives. checks/lib/gpu-session.nix now supplies all three and
records the evidence for each:

  * `-vga virtio`, for a DRM render node. `virtualisation.graphics = false`
    still leaves QEMU's default bochs-drm adapter, which gives card0 and no
    renderD*. Measured in the guest: `-vga virtio` -> card0 + renderD128;
    `-device virtio-gpu-pci` only *adds* a card next to bochs-drm, so it would
    need `-vga none` beside it.

  * `hardware.graphics.enable`, so Mesa's GBM backends exist at all. Without it
    gbm_create_device() fails with "MESA-LOADER: failed to open dri:
    /run/opengl-driver/lib/gbm/dri_gbm.so" and aquamarine reports "Cannot open
    backend: no allocator available".

  * `SEATD_VTBOUND=0`, so libseat's embedded seatd hands out a seat with no VT.
    `CHeadlessBackend::drmFD()` returns -1 unconditionally, so the *only*
    source of an allocator is the DRM backend, which opens /dev/dri/card0
    through libseat -- and the default VT-bound seat needs /dev/tty0, which the
    unprivileged service user cannot open.

The diagnostics dump grows a "graphics devices" section (`ls -l /dev/dri`,
`cat /proc/fb`) and a "wayland socket vs WAYLAND_DISPLAY" section, so the next
machine that is missing a render node, or that binds a socket the frame server
is not waiting on, says so in three lines instead of timing out mutely.
vm-basic's `dump()` is now vm-hyprland's, which reports the exit status too.

vm-basic also gained `python3` in the guest: its last subtest shells out to a
python one-liner and had been dying on exit code 127 -- invisible until the
compositor got far enough to reach that subtest.

Neither check passes yet, and the two remaining blockers both live in
nix/module.nix, which this slice may not edit, so they are reported rather
than patched:

  * vm-basic stops at "the module's two units come up". The compositor is up
    and healthy; the frame server sits in ExecStartPre forever. The module
    hardcodes `waylandDisplay = "wayland-0"`, but Hyprland's socket loop is
    `// get socket, avoid using 0` over candidates 1..32 (src/Compositor.cpp),
    so the session binds wayland-1. Forcing WAYLAND_DISPLAY=wayland-1 in the
    guest was verified to carry vm-basic through every other subtest.

  * vm-hyprland stops at "the compositor reports the configured headless
    output" with "hyprctl never reported a HEADLESS-1 monitor". hyprctl reports
    `Monitor Virtual-1` at 1280x800 -- the virtio-gpu output. A HEADLESS-N
    output only exists after `hyprctl output create headless`, which the module
    never issues; Hyprland's own fallback output is named FALLBACK. The
    `monitor = HEADLESS-1, ...` line in hyprland.conf is a rule for a monitor
    that is never created.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018fJZYyS4pqxt2FC37JsFYd
2026-09-28 12:28:01 +00:00
Hermenix db886faa38 docs: pin the server command line in the contract; add ARCHITECTURE.md 2026-09-28 11:53:19 +00:00
Hermenix 578e14286d tests: merge the two unit-test conftests into one fixture set 2026-09-28 11:52:32 +00:00
Hermenix 72f359932a Merge branch 'slice/tests'
# Conflicts:
#	tests/unit/conftest.py
#	tests/unit/test_capture.py
#	tests/unit/test_client.py
#	tests/unit/test_protocol.py
#	tests/unit/test_server.py
2026-09-28 11:51:07 +00:00
Hermenix 0fb515cc83 Merge branch 'slice/module' 2026-09-28 11:50:51 +00:00
HermenixandClaude Opus 5 4af6f7072a server, client: implement the v1 frame protocol end to end
Fill in the bodies the skeleton left as NotImplementedError, to docs/CONTRACT.md:

- protocol: the `\n`-terminated JSON Hello and the `<ascii length>\n<payload>`
  frame, both directions. Malformed input raises (ValueError for a bad length
  prefix, EOFError for a truncated payload), never hangs on endless garbage and
  never silently truncates; a huge length prefix is not pre-allocated.
- capture: CommandCapture runs the configured command and reports a missing
  binary, a non-zero exit, a timeout and empty output as CaptureError, with the
  helper's stderr folded into the message so nothing leaks to the server's own
  stdio. The Hello's pixel size is read from the frame's PNG/JPEG header, so no
  compositor query is needed and an injected fake command behaves the same.
- server: one capture thread holding only the newest frame plus one thread per
  client, which is what drops frames for a slow client instead of queueing
  them. Survives a client dying mid-write, keeps the socket up across capture
  failures, withholds the Hello until a size is known, replaces a stale socket
  file (but never a non-socket one) and publishes it mode 0660.
- client: fetch()/read_stream() and the CLI, with --out suffixing per frame.

--capture-command folds its separated form into `--flag=value` before argparse
sees it, so the contract's default `grim -t png -` can actually be passed: its
tokens start with a dash.

Unit tests under tests/unit cover framing round-trips (including a payload
containing `\n` and a zero-length frame), truncated and garbage prefixes, a
stalled client not blocking a second one, a client dying mid-frame, frames being
dropped rather than queued, and every capture failure mode. A fake capture
command stands in for grim, so nothing needs a compositor or a GPU. They are
deliberately not wired into flake.nix: `checks` belongs to another workstream.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FYJ8ZQ5AZaDErYTwXZe7N9
2026-09-28 05:35:17 +00:00
HermenixandClaude Opus 5 464c93e8f4 module: wire up the headless session and the frame server
Implements the `config` side of the module surface in docs/CONTRACT.md:

- `hhstream` user/group, and one private runtime directory shared by both
  units (RuntimeDirectory= with Preserve=yes, so the Wayland socket survives
  a restart of either side).
- A rendered hyprland.conf (nix/hyprland-conf.nix): one `monitor =` line per
  `outputs` entry plus `extraConfig` verbatim, with the logo/splash, config
  autoreload, DPMS, cursor, animations, shadows and the update/donation and
  guiutils/XDG checks switched off -- none of them mean anything in a session
  with no seat, no input device and no user. Validated with
  `Hyprland --verify-config`.
- `hyprland-headless.service`: Hyprland as the service user, Type=notify (it
  sends READY=1), Restart=always, and deliberately no WAYLAND_DISPLAY or
  DISPLAY in the environment so the compositor cannot pick a nested backend
  and falls back to headless.
- `hyprland-headless-stream.service`: hhstream-server as the same user,
  After=/BindsTo= the compositor, Restart=always, with --socket/--fps/
  --format/--capture-command on the command line.

`outputs.*.scale` used `lib.types.positive`, which does not exist in nixpkgs
and made the whole `outputs` option unreadable; it is now
`lib.types.numbers.positive`. `package` gets its documented default (the
flake's own build) via mkDefault on the config side, so the declared option
surface is otherwise untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015pS3JxTJZBufyBKwimwBxy
2026-09-28 05:20:16 +00:00
20 changed files with 2268 additions and 567 deletions

No files matched your search

+84
View File
@@ -0,0 +1,84 @@
# What a NixOS test machine has to be given before Hyprland 0.56.2 will start.
#
# Imported by both VM checks. It is a machine definition, not a test: nothing
# here relaxes anything either check asserts, it only supplies hardware and
# session facts that a default `nodes.machine` does not have.
#
# The failure it fixes is the same one every time -- the compositor aborts with
#
# terminate called after throwing an instance of 'std::runtime_error'
# what(): CBackend::create() failed!
#
# and systemd restarts it until the test's timeout expires. `CBackend::create()`
# is aquamarine's, and reading aquamarine 0.15.1 rather than guessing at it, it
# needs three separate things that a bare test machine does not provide. Each is
# one of the blocks below, and each was confirmed in the guest by removing it
# again and watching the compositor die on the next line down.
#
# A note for whoever hits this next: none of it is visible in the journal until
# you also set `debug:disable_logs = false`, because Hyprland mutes aquamarine
# by default and the abort is all that survives. That is how the three causes
# below were separated.
{ ... }:
{
# 1. A DRM render node.
#
# `virtualisation.graphics = false` still leaves QEMU's default bochs-drm
# adapter in the guest, which offers /dev/dri/card0 and *no* renderD*. Measured
# in the guest, not assumed:
#
# (default) card0 (bochs-drm)
# -vga virtio card0, renderD128 (virtio_gpu)
# -device virtio-gpu-pci card0, card1, renderD128 (bochs + virtio)
# -vga none -device virtio-gpu-pci card0, renderD128 (virtio_gpu)
#
# `-vga virtio` *replaces* the default adapter, so it is the one-option form of
# the last line. `-device virtio-gpu-pci` on its own only *adds* a second card
# next to bochs-drm, so it would need `-vga none` beside it to leave the guest
# with a single DRM device.
virtualisation.qemu.options = [ "-vga virtio" ];
# 2. Mesa, where the GBM loader looks for it.
#
# aquamarine's allocator is gbm_create_device() on that node. On NixOS the GBM
# backends live under /run/opengl-driver, which only exists when
# hardware.graphics is enabled -- a test machine has it off. Without it:
#
# MESA-LOADER: failed to open dri: /run/opengl-driver/lib/gbm/dri_gbm.so:
# cannot open shared object file: No such file or directory
# ERR from aquamarine ]: Couldn't open a GBM device at fd 21
# CRIT from aquamarine ]: Cannot open backend: no allocator available
hardware.graphics.enable = true;
# 3. A seat that is not bound to a VT.
#
# This one is not really the test machine's business, and it is flagged rather
# than fixed: it belongs in nix/module.nix, which this slice may not edit.
#
# Only the DRM backend ever yields a buffer allocator --
# `CHeadlessBackend::drmFD()` returns -1 unconditionally (aquamarine
# src/backend/Headless.cpp), and CBackend::start() takes the allocator from the
# first implementation with a drm fd. So "headless" here does not mean "no
# GPU": the headless backend still rides on the DRM backend's allocator, and if
# the DRM backend fails there is none, whatever /dev/dri holds.
#
# The DRM backend opens /dev/dri/card0 through libseat. For this unit libseat
# finds no /run/seatd.sock and no logind session (it is a system service, not a
# login), so it falls back to its embedded seatd -- whose seat is VT-bound by
# default. It then tries to open /dev/tty0, which the unprivileged `hhstream`
# user cannot, so the client never becomes active and every device open is
# refused:
#
# ERR ]: [libseat] [common/terminal.c:162] Could not open target tty: Permission denied
# ERR ]: [libseat] [seatd/seat.c:557] Could not open VT for client
# ERR ]: libseat: Couldn't open device at /dev/dri/card0
# ERR ]: drm: Skipping device /sys/devices/.../drm/card0, not a KMS device
# ERR ]: drm: Found no gpus to use, cannot continue
# ERR ]: DRM Backend failed
#
# SEATD_VTBOUND=0 (seatd/server.c) asks that embedded seatd for a seat with no
# VT at all, which is the truth about this session: there is no terminal to
# switch away from. A headless session run as a system user will need this on
# any machine, not just in the test.
systemd.services.hyprland-headless.environment.SEATD_VTBOUND = "0";
}
+16 -4
View File
@@ -8,6 +8,7 @@
testers,
hhstream,
testTools,
python3,
hhsModule,
width ? 1280,
height ? 720,
@@ -22,7 +23,9 @@ testers.runNixOSTest {
globalTimeout = 900;
nodes.machine = {
imports = [ hhsModule ];
# gpu-session.nix is what makes the compositor able to start at all; see
# that file for the three things a bare test machine is missing.
imports = [ hhsModule ./lib/gpu-session.nix ];
services.hyprland-headless-stream = {
enable = true;
@@ -51,12 +54,19 @@ testers.runNixOSTest {
environment.systemPackages = [
testTools
hhstream
# The "client dying mid-stream" subtest opens the socket from a python
# one-liner in the guest. hhstream's own interpreter is reachable only
# through its wrapper, so without this the subtest dies on exit code 127
# (`python3: command not found`) rather than on anything it asserts.
python3
];
# Mesa and the compositor together need more than the fake capture alone
# did; the GPU itself comes from gpu-session.nix.
virtualisation = {
memorySize = 1024;
memorySize = 2048;
cores = 2;
diskSize = 3072;
diskSize = 4096;
graphics = false;
};
};
@@ -68,7 +78,9 @@ testers.runNixOSTest {
def dump(label):
print(f"########## diagnostics: {label} ##########")
print(machine.execute("hhs-hyprland-diagnostics")[1])
status, out = machine.execute("hhs-hyprland-diagnostics", timeout=120)
print(out)
print(f"########## end diagnostics (exit {status}) ##########")
start_all()
+6 -3
View File
@@ -24,7 +24,9 @@ testers.runNixOSTest {
globalTimeout = 1800;
nodes.machine = {
imports = [ hhsModule ];
# gpu-session.nix is what makes the compositor able to start at all; see
# that file for the three things a bare test machine is missing.
imports = [ hhsModule ./lib/gpu-session.nix ];
services.hyprland-headless-stream = {
enable = true;
@@ -53,8 +55,9 @@ testers.runNixOSTest {
];
# The compositor needs more room than the fake capture did, and its software
# renderer wants a CPU. There is still no GPU: Hyprland runs on its headless
# backend over llvmpipe.
# renderer wants a CPU. The virtio GPU from gpu-session.nix is there for its
# render node and its DRM backend, not for acceleration: rendering is still
# Mesa's software path.
virtualisation = {
memorySize = 2048;
cores = 2;
+76
View File
@@ -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
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.
+94
View File
@@ -0,0 +1,94 @@
# The hyprland.conf for a session nobody sits in front of.
#
# Split out of module.nix so the rendering is readable on its own (and diffable
# when an output list changes). Returns the file *text*; the caller puts it in
# the store.
{
lib,
outputs,
extraConfig,
}: let
# `monitor = <name>, <width>x<height>@<refresh>, auto, <scale>` -- "auto"
# lets the compositor lay the virtual outputs out left to right.
monitorLine = o: "monitor = ${o.name}, ${toString o.width}x${toString o.height}@${toString o.refresh}, auto, ${toString o.scale}";
in ''
# Generated by services.hyprland-headless-stream. Do not edit.
#
# There is no seat, no libinput device, no cursor and no human here: the only
# consumer of this session is the frame server. Everything below either
# creates the virtual outputs or switches off something that assumes a user.
${lib.concatMapStringsSep "\n" monitorLine outputs}
misc {
# Nothing should draw itself over the captured output.
disable_hyprland_logo = true
disable_splash_rendering = true
force_default_wallpaper = 0
background_color = 0x000000
# The config lives in the store and never changes under us; watching it
# would only cost inotify watches on a read-only path.
disable_autoreload = true
# A virtual output has no variable refresh rate to negotiate.
vrr = 0
# DPMS on a virtual output is meaningless, and there is no key or pointer
# event coming to wake it back up.
key_press_enables_dpms = false
mouse_move_enables_dpms = false
# Both of these check for a desktop that is not here: the Qt helper
# dialogs, and the XDG portal environment.
disable_hyprland_guiutils_check = true
disable_xdg_env_checks = true
}
debug {
# Capture wants a steady frame rate. With variable frame rate the
# compositor only renders on damage, so an idle session would starve the
# stream.
vfr = false
# The session is a systemd unit: its log belongs in the journal, not in a
# file under a runtime directory nobody will look in.
enable_stdout_logs = true
colored_stdout_logs = false
}
cursor {
# No hardware planes, no cursor theme on disk, nobody to warp.
invisible = true
no_hardware_cursors = true
enable_hyprcursor = false
no_warps = true
hide_on_key_press = false
inactive_timeout = 0
}
input {
# No pointer will ever exist; do not let focus depend on one.
follow_mouse = 0
}
# Frames cost capture bandwidth and CPU, and no one is watching the easing.
animations {
enabled = false
}
decoration {
blur {
enabled = false
}
shadow {
enabled = false
}
}
# Nothing here may reach the network or nag a user who is not there.
ecosystem {
no_update_news = true
no_donation_nag = true
}
${lib.optionalString (extraConfig != "") "\n${extraConfig}"}''
+224 -17
View File
@@ -1,10 +1,104 @@
{ lib, config, pkgs, ... }:
# Interface only: every option in docs/CONTRACT.md is declared here so tests and
# consumers can be written against a stable surface. The systemd wiring is the
# next piece of work (see docs/CONTRACT.md -> "Services").
{
lib,
config,
pkgs,
...
}:
# The option surface below is the interface described in docs/CONTRACT.md
# ("NixOS module surface"); the `config` block wires it to the two services
# named there.
let
cfg = config.services.hyprland-headless-stream;
# One private runtime directory, shared by both units: it holds the Wayland
# socket of the session and, by default, the published frame socket too.
# `RuntimeDirectoryPreserve` keeps it (and the Wayland socket) alive across a
# restart of either unit.
runtimeDirName = "hyprland-headless-stream";
runtimeDir = "/run/${runtimeDirName}";
socketDir = builtins.dirOf cfg.socketPath;
# Hyprland refuses `--socket` unless it is paired with `--wayland-fd` (that
# pair is the socket-handover path), so the name is not ours to choose: the
# compositor calls wl_display_add_socket_auto, which takes the first free
# `wayland-N` starting at 0. The runtime directory is private to this
# session, so that is always `wayland-0`.
waylandDisplay = "wayland-0";
hyprlandConf = pkgs.writeText "hyprland.conf" (import ./hyprland-conf.nix {
inherit lib;
inherit (cfg) outputs extraConfig;
});
# `BindsTo=` already stops the frame server when the compositor goes away,
# but the compositor is only *ready* once its Wayland socket is bound. The
# compositor unit is `Type=notify`, so this is a second line of defence for
# compositor builds that do not sd_notify.
waitForSession = pkgs.writeShellScript "hhstream-wait-for-session" ''
socket="$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY"
for _ in $(${lib.getExe' pkgs.coreutils "seq"} 1 300); do
if [ -S "$socket" ]; then
exit 0
fi
${lib.getExe' pkgs.coreutils "sleep"} 0.1
done
echo "no Wayland socket at $socket after 30s; is the compositor up?" >&2
exit 1
'';
serverArgs =
[
"--socket"
cfg.socketPath
"--fps"
(toString cfg.frameRate)
"--format"
cfg.format
]
# One occurrence per argv word. The capture command is a list whose words
# start with `-` (`grim -t png -`), and repeating the flag is the only
# shape that survives that without inventing a quoting convention.
# `hhstream.server.build_parser()` is still a stub, so this is the one
# place the module guesses at the server's CLI rather than reading it.
++ lib.concatMap (word: ["--capture-command" word]) cfg.captureCommand;
# Shared by both units: a private session, no parent display to nest in.
sessionEnvironment = {
XDG_RUNTIME_DIR = runtimeDir;
HOME = runtimeDir;
XDG_SESSION_TYPE = "wayland";
};
commonServiceConfig = {
User = cfg.user;
Group = cfg.group;
RuntimeDirectory = runtimeDirName;
RuntimeDirectoryMode = "0750";
RuntimeDirectoryPreserve = "yes";
WorkingDirectory = runtimeDir;
# docs/CONTRACT.md: the socket is owned by the service user, mode 0660.
UMask = "0007";
Restart = "always";
RestartSec = 2;
# A GPU render node is the one piece of hardware a headless session still
# needs; everything else is virtual.
SupplementaryGroups = ["video" "render"];
NoNewPrivileges = true;
PrivateTmp = true;
ProtectHome = true;
ProtectSystem = "strict";
ProtectControlGroups = true;
ProtectKernelTunables = true;
ProtectKernelModules = true;
RestrictSUIDSGID = true;
ReadWritePaths = lib.optional (socketDir != runtimeDir) socketDir;
};
in {
options.services.hyprland-headless-stream = {
enable = lib.mkEnableOption "a headless Hyprland session streamed to a Unix socket";
@@ -34,7 +128,7 @@ in {
};
format = lib.mkOption {
type = lib.types.enum [ "png" "jpeg" ];
type = lib.types.enum ["png" "jpeg"];
default = "png";
description = "Frame encoding.";
};
@@ -42,14 +136,37 @@ in {
outputs = lib.mkOption {
type = lib.types.listOf (lib.types.submodule {
options = {
name = lib.mkOption { type = lib.types.str; };
width = lib.mkOption { type = lib.types.ints.positive; default = 1280; };
height = lib.mkOption { type = lib.types.ints.positive; default = 720; };
refresh = lib.mkOption { type = lib.types.ints.positive; default = 30; };
scale = lib.mkOption { type = lib.types.positive; default = 1.0; };
name = lib.mkOption {type = lib.types.str;};
width = lib.mkOption {
type = lib.types.ints.positive;
default = 1280;
};
height = lib.mkOption {
type = lib.types.ints.positive;
default = 720;
};
refresh = lib.mkOption {
type = lib.types.ints.positive;
default = 30;
};
# Was `lib.types.positive`, which does not exist in nixpkgs and made
# `outputs` unreadable; `numbers.positive` is the int-or-float type
# that name meant.
scale = lib.mkOption {
type = lib.types.numbers.positive;
default = 1.0;
};
};
});
default = [ { name = "HEADLESS-1"; width = 1280; height = 720; refresh = 30; scale = 1.0; } ];
default = [
{
name = "HEADLESS-1";
width = 1280;
height = 720;
refresh = 30;
scale = 1.0;
}
];
description = "Virtual monitors the compositor should create.";
};
@@ -73,19 +190,109 @@ in {
captureCommand = lib.mkOption {
type = lib.types.listOf lib.types.str;
default = [ "grim" "-t" "png" "-" ];
default = ["grim" "-t" "png" "-"];
description = "Command that writes one frame to stdout; overridable for tests.";
};
};
config = lib.mkIf cfg.enable {
# TODO(module): user/group, runtime dir, hyprland.conf rendering, the two
# systemd units named in docs/CONTRACT.md.
assertions = [
{
assertion = cfg.outputs != [ ];
assertion = cfg.outputs != [];
message = "services.hyprland-headless-stream.outputs must not be empty.";
}
{
assertion = lib.hasPrefix "/" cfg.socketPath;
message = "services.hyprland-headless-stream.socketPath must be an absolute path.";
}
];
# The flake's own build, as docs/CONTRACT.md says; `mkDefault` so a
# consumer (or the test harness) can still point this at its own package.
services.hyprland-headless-stream.package =
lib.mkDefault (pkgs.callPackage ./package.nix {});
users.users.${cfg.user} = {
isSystemUser = true;
group = cfg.group;
description = "Headless Hyprland stream session";
};
users.groups.${cfg.group} = {};
# Only needed when the socket was moved out of the runtime directory that
# `RuntimeDirectory=` already creates for us.
systemd.tmpfiles.settings = lib.mkIf (socketDir != runtimeDir) {
"10-hyprland-headless-stream".${socketDir}.d = {
user = cfg.user;
group = cfg.group;
mode = "0750";
};
};
systemd.services.hyprland-headless = {
description = "Headless Hyprland session";
documentation = ["file://${hyprlandConf}"];
wantedBy = ["multi-user.target"];
# No WAYLAND_DISPLAY and no DISPLAY here on purpose: with either set the
# compositor would pick its nested backend and try to connect to a parent
# session. With no seat and no DRM device it falls back to headless,
# which is exactly what the virtual outputs in hyprland.conf want.
environment =
sessionEnvironment
// {
# We are a system service: there is no user bus and no user manager to
# import the session environment into.
HYPRLAND_NO_SD_VARS = "1";
HYPRLAND_NO_CRASHREPORTER = "1";
# Ignored by aquamarine-era Hyprland, honoured by wlroots-era builds
# someone may pin in `hyprlandPackage`.
WLR_BACKENDS = "headless";
WLR_LIBINPUT_NO_DEVICES = "1";
WLR_RENDERER_ALLOW_SOFTWARE = "1";
};
serviceConfig =
commonServiceConfig
// {
# Hyprland sends READY=1 once the session is up, so the frame server's
# `After=` is an ordering on readiness, not just on fork.
Type = "notify";
NotifyAccess = "all";
TimeoutStartSec = 60;
ExecStart = lib.escapeShellArgs [
(lib.getExe cfg.hyprlandPackage)
"--config"
"${hyprlandConf}"
];
};
};
systemd.services.hyprland-headless-stream = {
description = "Frame server for the headless Hyprland session";
wantedBy = ["multi-user.target"];
after = ["hyprland-headless.service"];
bindsTo = ["hyprland-headless.service"];
# `captureCommand` defaults to an unqualified `grim`.
path = [pkgs.grim];
environment =
sessionEnvironment
// {
WAYLAND_DISPLAY = waylandDisplay;
PYTHONUNBUFFERED = "1";
};
serviceConfig =
commonServiceConfig
// {
Type = "simple";
ExecStartPre = "${waitForSession}";
ExecStart = lib.escapeShellArgs (
[(lib.getExe' cfg.package "hhstream-server")] ++ serverArgs
);
};
};
};
}
}
+140 -5
View File
@@ -7,9 +7,24 @@ produces frames in a unit test.
from __future__ import annotations
import os
import struct
import subprocess
from typing import Protocol
#: MIME types the contract allows, and the pixel-size probe for each.
_SOF_MARKERS = frozenset(
m for m in range(0xC0, 0xD0) if m not in (0xC4, 0xC8, 0xCC)
)
class CaptureError(RuntimeError):
"""One capture attempt failed; the server catches this and keeps serving.
Covers every way the helper command can let us down: it is missing, it
exits non-zero, it times out, or it writes nothing.
"""
class CaptureBackend(Protocol):
def grab(self) -> bytes:
@@ -22,17 +37,137 @@ class CaptureBackend(Protocol):
class CommandCapture:
"""Runs a helper that writes one frame to stdout (default: grim)."""
"""Runs a helper that writes one frame to stdout (default: grim).
`env` is overlaid on the server's own environment (that is how the session
variables -- `WAYLAND_DISPLAY`, `XDG_RUNTIME_DIR` -- reach the helper
without having to restate `PATH`). The helper's stdout is the frame and its
stderr is captured, so a chatty or failing helper never writes to the
server's own stdout/stderr; the message ends up in the raised
`CaptureError` instead.
"""
def __init__(self, argv: list[str], env: dict[str, str] | None = None,
timeout: float = 5.0) -> None:
raise NotImplementedError
argv = list(argv)
if not argv:
raise ValueError("capture command must not be empty")
if timeout is not None and timeout <= 0:
raise ValueError(f"capture timeout must be positive, got {timeout!r}")
self.argv = argv
self.env = dict(env) if env is not None else None
self.timeout = timeout
self._size: tuple[int, int] | None = None
def grab(self) -> bytes:
raise NotImplementedError
"""Run the helper once and return the bytes it wrote to stdout."""
child_env = None
if self.env is not None:
child_env = dict(os.environ)
child_env.update(self.env)
try:
proc = subprocess.run(
self.argv,
stdin=subprocess.DEVNULL,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
env=child_env,
timeout=self.timeout,
check=False,
)
except subprocess.TimeoutExpired as exc:
raise CaptureError(
f"capture command {self.argv!r} timed out after {self.timeout}s"
) from exc
except OSError as exc:
raise CaptureError(
f"capture command {self.argv!r} could not be run: {exc}"
) from exc
if proc.returncode != 0:
raise CaptureError(
f"capture command {self.argv!r} exited {proc.returncode}: "
f"{_tail(proc.stderr)}"
)
if not proc.stdout:
raise CaptureError(
f"capture command {self.argv!r} produced no output: "
f"{_tail(proc.stderr)}"
)
measured = image_size(proc.stdout)
if measured is not None:
self._size = measured
return proc.stdout
def size(self) -> tuple[int, int]:
raise NotImplementedError
"""Pixel size of the captured output, for the Hello.
Measured from the frame itself (the PNG/JPEG header), so no compositor
query is needed and an injected fake command works the same way. The
first successful measurement is remembered; `grab` refreshes it, so
after a frame has been captured this costs nothing.
"""
if self._size is None:
self.grab()
if self._size is None:
raise CaptureError(
f"cannot determine pixel size from the output of {self.argv!r} "
"(not a PNG or JPEG?)"
)
return self._size
__all__ = ["CaptureBackend", "CommandCapture", "subprocess"]
def image_size(data: bytes) -> tuple[int, int] | None:
"""Pixel size of a PNG or JPEG frame, or None if it cannot be read."""
return _png_size(data) or _jpeg_size(data)
def _png_size(data: bytes) -> tuple[int, int] | None:
if not data.startswith(b"\x89PNG\r\n\x1a\n") or len(data) < 24:
return None
if data[12:16] != b"IHDR":
return None
width, height = struct.unpack(">II", data[16:24])
return (width, height) if width and height else None
def _jpeg_size(data: bytes) -> tuple[int, int] | None:
if not data.startswith(b"\xff\xd8"):
return None
i, n = 2, len(data)
while i + 1 < n:
if data[i] != 0xFF:
i += 1 # resync on the next marker
continue
marker = data[i + 1]
if marker == 0xFF:
i += 1 # fill byte
continue
if marker in (0x01, 0xD8, 0xD9) or 0xD0 <= marker <= 0xD7:
i += 2 # standalone marker, no payload
continue
if i + 4 > n:
return None
seglen = int.from_bytes(data[i + 2:i + 4], "big")
if seglen < 2:
return None
if marker in _SOF_MARKERS:
if i + 9 > n:
return None
height = int.from_bytes(data[i + 5:i + 7], "big")
width = int.from_bytes(data[i + 7:i + 9], "big")
return (width, height) if width and height else None
i += 2 + seglen
return None
def _tail(stderr: bytes | None, limit: int = 400) -> str:
if not stderr:
return "no stderr"
text = stderr.decode("utf-8", "replace").strip()
if len(text) > limit:
text = "..." + text[-limit:]
return text or "no stderr"
__all__ = ["CaptureBackend", "CommandCapture", "CaptureError", "image_size",
"subprocess"]
+102 -5
View File
@@ -3,22 +3,119 @@
from __future__ import annotations
import argparse
import json
import pathlib
import socket
import sys
from typing import Iterable
from . import protocol
DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock"
def fetch(socket_path: str, count: int = 1, timeout: float = 10.0) -> list[bytes]:
"""Connect and return up to `count` frame payloads (Hello consumed)."""
raise NotImplementedError
"""Connect and return up to `count` frame payloads (Hello consumed).
`timeout` bounds each socket operation, not the whole call: at the
advertised fps a frame is expected well inside it. Fewer than `count`
frames come back if the server closes the connection first.
"""
return read_stream(socket_path, count, timeout)[1]
def read_stream(socket_path: str, count: int = 1,
timeout: float = 10.0) -> tuple[dict, list[bytes]]:
"""Like `fetch`, but also returns the parsed Hello."""
conn = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
conn.settimeout(timeout)
try:
conn.connect(socket_path)
with conn.makefile("rb") as stream:
hello = protocol.read_hello(stream)
frames: list[bytes] = []
while len(frames) < count:
payload = protocol.read_frame(stream)
if payload is None:
break # server closed; return what we got
frames.append(payload)
return hello, frames
finally:
conn.close()
def build_parser() -> argparse.ArgumentParser:
raise NotImplementedError
parser = argparse.ArgumentParser(
prog="hhstream-client",
description="Read frames from a hyprland-headless-stream socket.",
)
parser.add_argument(
"--socket", default=DEFAULT_SOCKET, metavar="PATH",
help="socket to read from (default: %(default)s)",
)
parser.add_argument(
"--count", type=int, default=1, metavar="N",
help="how many frames to read (default: %(default)s)",
)
parser.add_argument(
"--out", metavar="PATH",
help="write each frame here, suffixed when --count > 1; "
"'-' writes the payloads to stdout",
)
parser.add_argument(
"--timeout", type=float, default=10.0, metavar="SECONDS",
help="per-read socket timeout (default: %(default)s)",
)
return parser
def main(argv: Iterable[str] | None = None) -> int:
raise NotImplementedError
args = build_parser().parse_args(argv)
if args.count < 0:
print("--count must not be negative", file=sys.stderr)
return 2
to_stdout = args.out == "-"
# Keep stdout for the payloads when they are going there.
report = sys.stderr if to_stdout else sys.stdout
try:
hello, frames = read_stream(args.socket, args.count, args.timeout)
except (OSError, EOFError, ValueError) as exc:
print(f"hhstream-client: {exc}", file=sys.stderr)
return 1
print(json.dumps(hello, separators=(",", ":")), file=report)
for index, payload in enumerate(frames, start=1):
if to_stdout:
sys.stdout.buffer.write(payload)
sys.stdout.buffer.flush()
print(f"frame {index}: {len(payload)} bytes", file=report)
elif args.out:
target = output_path(args.out, index, args.count)
target.write_bytes(payload)
print(f"frame {index}: {len(payload)} bytes -> {target}", file=report)
else:
print(f"frame {index}: {len(payload)} bytes", file=report)
report.flush()
if len(frames) < args.count:
print(
f"hhstream-client: wanted {args.count} frames, got {len(frames)} "
"(server closed the connection)",
file=sys.stderr,
)
return 1
return 0
__all__ = ["fetch", "DEFAULT_SOCKET", "build_parser", "main"]
def output_path(out: str, index: int, count: int) -> pathlib.Path:
"""`frame.png` -> itself for one frame, `frame-1.png`, `frame-2.png` beyond."""
path = pathlib.Path(out)
if count <= 1:
return path
width = len(str(count))
return path.with_name(f"{path.stem}-{index:0{width}d}{path.suffix}")
__all__ = ["fetch", "read_stream", "DEFAULT_SOCKET", "build_parser", "main",
"output_path"]
+115 -6
View File
@@ -10,23 +10,77 @@ from typing import BinaryIO
from . import MAGIC
#: Longest length prefix we will read before giving up. The contract allows
#: plain ASCII digits with no bound; 20 digits is past 2**63 and keeps a garbage
#: stream from making us read forever.
MAX_LENGTH_DIGITS = 20
#: Longest Hello line we will read before giving up, for the same reason.
MAX_HELLO_BYTES = 65536
_READ_CHUNK = 1 << 20
def hello(width: int, height: int, fmt: str, fps: int) -> bytes:
"""The one-line JSON Hello, `\\n`-terminated.
`fmt` is a MIME type ("image/png" / "image/jpeg").
"""
raise NotImplementedError
for name, value in (("width", width), ("height", height), ("fps", fps)):
if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
raise ValueError(f"{name} must be a positive int, got {value!r}")
if not isinstance(fmt, str) or not fmt:
raise ValueError(f"format must be a non-empty str, got {fmt!r}")
obj = {
"magic": MAGIC,
"width": width,
"height": height,
"format": fmt,
"fps": fps,
}
line = json.dumps(obj, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
if b"\n" in line:
raise ValueError("Hello would contain a newline")
return line + b"\n"
def parse_hello(line: bytes) -> dict:
"""Inverse of `hello`: validate `magic` and required fields, or raise."""
raise NotImplementedError
if not isinstance(line, (bytes, bytearray)):
raise ValueError(f"Hello must be bytes, got {type(line).__name__}")
text = bytes(line)
if text.endswith(b"\n"):
text = text[:-1]
if not text:
raise ValueError("empty Hello line")
try:
obj = json.loads(text.decode("utf-8"))
except UnicodeDecodeError as exc:
raise ValueError(f"Hello is not UTF-8: {exc}") from exc
except json.JSONDecodeError as exc:
raise ValueError(f"Hello is not valid JSON: {exc}") from exc
if not isinstance(obj, dict):
raise ValueError(f"Hello must be a JSON object, got {type(obj).__name__}")
if obj.get("magic") != MAGIC:
raise ValueError(f"bad magic {obj.get('magic')!r}, expected {MAGIC!r}")
for name in ("width", "height", "format", "fps"):
if name not in obj:
raise ValueError(f"Hello is missing {name!r}")
for name in ("width", "height", "fps"):
value = obj[name]
if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
raise ValueError(f"Hello {name} must be a positive int, got {value!r}")
if not isinstance(obj["format"], str) or not obj["format"]:
raise ValueError(f"Hello format must be a non-empty str, got {obj['format']!r}")
return obj
def frame(payload: bytes) -> bytes:
"""`<ascii length>\\n<payload>` for one complete image."""
raise NotImplementedError
if not isinstance(payload, (bytes, bytearray, memoryview)):
raise ValueError(f"payload must be bytes, got {type(payload).__name__}")
body = bytes(payload)
return str(len(body)).encode("ascii") + b"\n" + body
def read_frame(stream: BinaryIO) -> bytes | None:
@@ -35,12 +89,67 @@ def read_frame(stream: BinaryIO) -> bytes | None:
Returns None on a clean EOF before any byte of the next frame. Raises
ValueError on a malformed length prefix and EOFError on a truncated payload.
"""
raise NotImplementedError
digits = bytearray()
while True:
byte = stream.read(1)
if not byte:
if not digits:
return None # clean EOF between frames
raise EOFError(
f"EOF in length prefix after {bytes(digits)!r}"
)
if byte == b"\n":
break
if not (b"0" <= byte <= b"9"):
raise ValueError(
f"malformed length prefix: unexpected byte {byte!r} "
f"after {bytes(digits)!r}"
)
digits += byte
if len(digits) > MAX_LENGTH_DIGITS:
raise ValueError(
f"length prefix longer than {MAX_LENGTH_DIGITS} digits"
)
if not digits:
raise ValueError("malformed length prefix: empty")
if len(digits) > 1 and digits[:1] == b"0":
raise ValueError(f"malformed length prefix: leading zero in {bytes(digits)!r}")
length = int(digits)
return _read_exactly(stream, length)
def read_hello(stream: BinaryIO) -> dict:
"""Read and parse the Hello line from `stream`."""
raise NotImplementedError
line = bytearray()
while True:
byte = stream.read(1)
if not byte:
raise EOFError(f"EOF in Hello line after {len(line)} bytes")
if byte == b"\n":
break
line += byte
if len(line) > MAX_HELLO_BYTES:
raise ValueError(f"Hello line longer than {MAX_HELLO_BYTES} bytes")
return parse_hello(bytes(line))
__all__ = ["json", "hello", "parse_hello", "frame", "read_frame", "read_hello", "MAGIC"]
def _read_exactly(stream: BinaryIO, length: int) -> bytes:
"""Read exactly `length` bytes or raise EOFError.
Reads in chunks so a bogus (huge) length prefix cannot make us allocate a
buffer for data that is not there.
"""
if length == 0:
return b""
out = bytearray()
while len(out) < length:
chunk = stream.read(min(_READ_CHUNK, length - len(out)))
if not chunk:
raise EOFError(
f"truncated payload: wanted {length} bytes, got {len(out)}"
)
out += chunk
return bytes(out)
__all__ = ["json", "hello", "parse_hello", "frame", "read_frame", "read_hello", "MAGIC"]
+369 -5
View File
@@ -8,31 +8,395 @@ synchronously, and a slow write blocks only that client.
from __future__ import annotations
import argparse
import errno
import logging
import os
import selectors
import signal
import socket
import stat
import sys
import threading
import time
from typing import Iterable
from . import protocol
from .capture import CaptureBackend, CommandCapture
DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock"
#: Contract: the published socket is mode 0660 (ownership is the unit's job).
SOCKET_MODE = 0o660
#: Contract default for `services.hyprland-headless-stream.captureCommand`.
DEFAULT_CAPTURE_COMMAND = ["grim", "-t", "png", "-"]
_BACKLOG = 64
_WAIT_TICK = 0.2 # how often a blocked client thread re-checks for shutdown
log = logging.getLogger("hhstream.server")
class FrameServer:
"""Publishes one capture stream to any number of clients.
A single capture thread holds exactly one frame -- the most recent one --
and every client thread sends whatever is in that slot when it is ready for
another frame. That is how frames get dropped for a slow client instead of
queued: there is no queue, and memory does not grow with the number of
stalled clients.
"""
def __init__(self, socket_path: str, capture: CaptureBackend, fps: int,
fmt: str = "image/png") -> None:
raise NotImplementedError
if isinstance(fps, bool) or not isinstance(fps, int) or fps <= 0:
raise ValueError(f"fps must be a positive int, got {fps!r}")
self.socket_path = socket_path
self.capture = capture
self.fps = fps
self.fmt = fmt
#: set once the socket is bound and listening (tests wait on it)
self.ready = threading.Event()
self.frames_captured = 0
self.capture_failures = 0
self._cond = threading.Condition()
self._frame: bytes | None = None
self._seq = 0
self._hello: bytes | None = None
self._stop = threading.Event()
self._listener: socket.socket | None = None
self._bound_inode: tuple[int, int] | None = None
self._clients: list[threading.Thread] = []
# Closing a listening socket does not reliably interrupt a blocked
# accept(), so the accept loop selects on this pair as well and stop()
# pokes it.
self._wake_r, self._wake_w = socket.socketpair()
# -- serving ---------------------------------------------------------
def serve_forever(self) -> None:
"""Bind, then serve until stopped. A stale socket file is replaced."""
raise NotImplementedError
try:
self._bind()
listener = self._listener
assert listener is not None
threading.Thread(target=self._capture_loop, name="hhstream-capture",
daemon=True).start()
log.info("serving %s at %d fps (%s)",
self.socket_path, self.fps, self.fmt)
self._accept_loop(listener)
finally:
self.stop()
self._wake_r.close()
self._wake_w.close()
def _accept_loop(self, listener: socket.socket) -> None:
with selectors.DefaultSelector() as selector:
try:
selector.register(listener, selectors.EVENT_READ)
selector.register(self._wake_r, selectors.EVENT_READ)
except (OSError, ValueError):
if self._stop.is_set():
return # stopped between binding and the accept loop
raise
while not self._stop.is_set():
try:
events = selector.select()
except OSError as exc:
if self._stop.is_set():
return
log.warning("select failed: %s", exc)
self._stop.wait(0.05) # never spin on a repeating error
continue
if any(key.fileobj is self._wake_r for key, _ in events):
return
try:
conn, _ = listener.accept()
except OSError as exc:
if self._stop.is_set():
return
log.warning("accept failed: %s", exc)
self._stop.wait(0.05)
continue
self._clients = [t for t in self._clients if t.is_alive()]
thread = threading.Thread(
target=self._serve_client, args=(conn,),
name="hhstream-client", daemon=True,
)
self._clients.append(thread)
thread.start()
def stop(self) -> None:
"""Ask the accept loop, the capture thread and every client to finish."""
self._stop.set()
with self._cond:
self._cond.notify_all()
try:
self._wake_w.send(b"\x00") # unblock the accept loop
except OSError:
pass
listener, self._listener = self._listener, None
if listener is not None:
try:
listener.close()
except OSError:
pass
self._unlink_own_socket()
# -- capture ---------------------------------------------------------
def _capture_loop(self) -> None:
interval = 1.0 / self.fps
while not self._stop.is_set():
started = time.monotonic()
try:
payload = self.capture.grab()
width, height = self.capture.size()
except Exception as exc: # a backend may raise anything
self.capture_failures += 1
# Contract: capture erroring keeps the socket up and retries; it
# never exits and never publishes a partial frame.
log.warning("capture failed (%d so far): %s",
self.capture_failures, exc)
else:
self._publish(payload, width, height)
remaining = interval - (time.monotonic() - started)
if remaining > 0:
self._stop.wait(remaining)
def _publish(self, payload: bytes, width: int, height: int) -> None:
with self._cond:
if self._hello is None:
if width > 0 and height > 0:
# Contract: never a Hello with zero size.
self._hello = protocol.hello(width, height, self.fmt, self.fps)
else:
log.warning("ignoring frame with zero size %dx%d", width, height)
return
self._frame = payload
self._seq += 1
self.frames_captured += 1
self._cond.notify_all()
# -- one client ------------------------------------------------------
def _serve_client(self, conn: socket.socket) -> None:
peer = conn.fileno()
drain = threading.Thread(
target=self._drain, args=(conn,), name="hhstream-drain", daemon=True
)
drain.start()
try:
hello = self._wait_for_hello()
if hello is None:
return
conn.sendall(hello)
last_seq = 0
while not self._stop.is_set():
payload, last_seq = self._wait_for_frame(last_seq)
if payload is None:
return
conn.sendall(protocol.frame(payload))
except OSError as exc:
# The whole point: one client dying mid-frame is this thread's
# problem and nobody else's.
log.info("client %s went away: %s", peer, exc)
except Exception:
log.exception("client %s failed", peer)
finally:
try:
conn.shutdown(socket.SHUT_RDWR)
except OSError:
pass
try:
conn.close()
except OSError:
pass
def _drain(self, conn: socket.socket) -> None:
"""Read and discard anything a client sends (contract: v1 reserved)."""
try:
while not self._stop.is_set():
if not conn.recv(4096):
return
except OSError:
return
def _wait_for_hello(self) -> bytes | None:
"""Block until the Hello is known (a frame has been captured)."""
with self._cond:
while self._hello is None and not self._stop.is_set():
self._cond.wait(_WAIT_TICK)
return self._hello
def _wait_for_frame(self, last_seq: int) -> tuple[bytes | None, int]:
"""Block until a frame newer than `last_seq` exists, then take the latest.
Everything captured while this client was busy is simply skipped.
"""
with self._cond:
while self._seq == last_seq and not self._stop.is_set():
self._cond.wait(_WAIT_TICK)
if self._seq == last_seq:
return None, last_seq
return self._frame, self._seq
# -- socket ----------------------------------------------------------
def _bind(self) -> None:
path = self.socket_path
parent = os.path.dirname(os.path.abspath(path))
if parent:
os.makedirs(parent, exist_ok=True)
self._replace_stale(path)
listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
try:
listener.bind(path)
os.chmod(path, SOCKET_MODE)
listener.listen(_BACKLOG)
except OSError:
listener.close()
raise
self._listener = listener
info = os.lstat(path)
self._bound_inode = (info.st_dev, info.st_ino)
self.ready.set()
@staticmethod
def _replace_stale(path: str) -> None:
"""Remove a leftover socket file so a stale one cannot block startup."""
try:
info = os.lstat(path)
except FileNotFoundError:
return
if not stat.S_ISSOCK(info.st_mode):
raise OSError(
errno.EEXIST,
f"{path} exists and is not a socket; refusing to remove it",
)
os.unlink(path)
def _unlink_own_socket(self) -> None:
"""Tidy the socket file away, but only if it is still the one we bound.
A restart that has already put its own socket there must keep it.
"""
if self._bound_inode is None:
return
try:
info = os.lstat(self.socket_path)
if (info.st_dev, info.st_ino) == self._bound_inode:
os.unlink(self.socket_path)
except OSError:
pass
self._bound_inode = None
# -- CLI -----------------------------------------------------------------
#: `--format png` is the module's spelling; the Hello carries the MIME type.
_MIME = {"png": "image/png", "jpeg": "image/jpeg"}
_CAPTURE_FLAG = "--capture-command"
def build_parser() -> argparse.ArgumentParser:
raise NotImplementedError
parser = argparse.ArgumentParser(
prog="hhstream-server",
description="Publish a headless Hyprland session's frames on a Unix socket.",
)
parser.add_argument(
"--socket", default=DEFAULT_SOCKET, metavar="PATH",
help="socket to publish frames on (default: %(default)s)",
)
parser.add_argument(
"--fps", type=_positive_int, default=30, metavar="N",
help="target capture rate, advertised in the Hello (default: %(default)s)",
)
parser.add_argument(
"--format", choices=sorted(_MIME), default="png",
help="frame encoding (default: %(default)s)",
)
parser.add_argument(
_CAPTURE_FLAG, action="append", dest="capture_command", metavar="TOKEN",
help="one argv token of the capture command; repeat once per token "
"(default: %s). Use --capture-command=-t for tokens starting "
"with a dash." % " ".join(DEFAULT_CAPTURE_COMMAND),
)
return parser
def main(argv: Iterable[str] | None = None) -> int:
raise NotImplementedError
args = build_parser().parse_args(_join_capture_tokens(argv))
logging.basicConfig(
level=logging.INFO, stream=sys.stderr,
format="%(asctime)s %(levelname)s %(message)s",
)
capture_command = args.capture_command or _default_capture_command(args.format)
server = FrameServer(
args.socket,
CommandCapture(capture_command),
args.fps,
fmt=_MIME[args.format],
)
_install_signal_handlers(server)
try:
server.serve_forever()
except KeyboardInterrupt:
server.stop()
except OSError as exc:
log.error("cannot serve on %s: %s", args.socket, exc)
return 1
return 0
def _default_capture_command(fmt: str) -> list[str]:
return ["grim", "-t", fmt, "-"]
def _positive_int(text: str) -> int:
value = int(text)
if value <= 0:
raise argparse.ArgumentTypeError(f"must be positive, got {text!r}")
return value
def _join_capture_tokens(argv: Iterable[str] | None) -> list[str] | None:
"""Rewrite `--capture-command X` as `--capture-command=X`.
Capture tokens are argv tokens, and real ones start with a dash (`-t`, `-`
in the default `grim -t png -`). argparse would read those as options, so
the separated form is folded into the `=` form before it sees them.
"""
if argv is None:
argv = sys.argv[1:]
tokens = list(argv)
out: list[str] = []
i = 0
while i < len(tokens):
token = tokens[i]
if token == "--": # everything after this is positional; leave it alone
out.extend(tokens[i:])
break
if token == _CAPTURE_FLAG and i + 1 < len(tokens):
out.append(f"{_CAPTURE_FLAG}={tokens[i + 1]}")
i += 2
continue
out.append(token)
i += 1
return out
def _install_signal_handlers(server: FrameServer) -> None:
def handler(signum, _frame): # pragma: no cover - needs a real signal
log.info("signal %d, shutting down", signum)
server.stop()
for signum in (signal.SIGINT, signal.SIGTERM):
try:
signal.signal(signum, handler)
except ValueError:
pass # not the main thread (embedded in a test); nothing to do
__all__ = ["FrameServer", "DEFAULT_SOCKET", "CaptureBackend", "CommandCapture",
"socket", "build_parser", "main"]
"socket", "build_parser", "main"]
+27
View File
@@ -32,6 +32,15 @@ done
run systemctl --no-pager --full list-dependencies "$SERVICE_UNIT"
say "graphics devices"
# The one piece of hardware a headless Hyprland still needs. A NixOS test
# machine gets QEMU's default bochs-drm adapter, which gives a card0 and *no*
# renderD*; aquamarine's headless backend wants a render node and aborts with
# "CBackend::create() failed!" without one. So "card0 but no renderD128" here
# is the signature of a machine that needs a virtio GPU in qemu.options.
ls -l /dev/dri 2>&1 || echo "[no /dev/dri: this machine has no DRM device at all]"
run cat /proc/fb
say "socket and runtime directories"
ls -la /run/hyprland-headless-stream 2>&1 || echo "[no /run/hyprland-headless-stream]"
ls -la /run/user 2>&1 || echo "[no /run/user]"
@@ -39,6 +48,24 @@ for d in /run/user/*; do
[ -d "$d" ] && ls -la "$d" 2>&1
done
say "wayland socket vs WAYLAND_DISPLAY"
# The other silent killer: the frame server waits for
# $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY, so if the compositor bound a different
# socket name the unit just sits in ExecStartPre until the test times out, with
# a healthy compositor next to it. Print both names side by side.
systemctl show -p Environment --value "$SERVICE_UNIT" 2>&1 \
| tr ' ' '\n' | grep -E '^(WAYLAND_DISPLAY|XDG_RUNTIME_DIR)=' \
|| echo "[no WAYLAND_DISPLAY/XDG_RUNTIME_DIR in the unit environment]"
for d in /run/hyprland-headless-stream /run/user/*; do
[ -d "$d" ] || continue
found_sock=$(find "$d" -xdev -maxdepth 1 -name 'wayland-*' ! -name '*.lock' 2>/dev/null)
if [ -n "$found_sock" ]; then
echo "bound sockets in $d: $found_sock"
else
echo "bound sockets in $d: [none]"
fi
done
say "hyprland logs"
# hyprland.log lives beside the compositor's IPC sockets; -xdev keeps this out
# of /nix/store and /proc.
+56 -14
View File
@@ -1,22 +1,36 @@
"""Shared fixtures for the unit suite.
Everything here is standard library. The tests never touch a socket outside
their own `tmp_path`, never spawn a compositor, and never read the host's
configuration: the capture backend is a `python3 -c` one-liner and the server is
driven in-process.
Two workstreams wrote fixtures for this directory (the server's own, and the
test harness's); this file is the merge of both. Everything here is standard
library. The tests never touch a socket outside their own ``tmp_path``, never
spawn a compositor, and never read the host's configuration: the capture
backend is an inline ``python3 -c`` program and the server is driven in-process.
"""
from __future__ import annotations
import contextlib
import os
import pathlib
import shutil
import socket
import struct
import sys
import tempfile
import threading
import zlib
import pytest
_HERE = pathlib.Path(__file__).resolve().parent
_SRC = _HERE.parents[1] / "src"
for _path in (str(_HERE), str(_SRC)):
if _path not in sys.path:
sys.path.insert(0, _path)
from hhstream.server import FrameServer # noqa: E402 (needs sys.path above)
#: The path named in docs/CONTRACT.md and in the module's option default.
CONTRACT_SOCKET = "/run/hyprland-headless-stream/stream.sock"
# AF_UNIX addresses are capped near 108 bytes; a long tmp_path would fail with a
@@ -50,14 +64,47 @@ def tiny_png() -> bytes:
@pytest.fixture
def sock_path(tmp_path) -> str:
"""A short, unused AF_UNIX path inside the test's own directory."""
path = str(tmp_path / "s.sock")
def workdir():
"""A short-lived directory with a short path (AF_UNIX paths are ~108 bytes)."""
path = tempfile.mkdtemp(prefix="hhs")
try:
yield pathlib.Path(path)
finally:
shutil.rmtree(path, ignore_errors=True)
@pytest.fixture
def sock_path(workdir):
path = str(workdir / "s.sock")
if len(path) > SUN_PATH_MAX:
pytest.skip(f"tmp_path too long for an AF_UNIX socket: {len(path)} bytes")
pytest.skip(f"workdir too long for an AF_UNIX socket: {len(path)} bytes")
return path
@pytest.fixture
def serve():
"""`with serve(path, capture, fps=...) as server:` -- bound and listening."""
started: list[tuple[FrameServer, threading.Thread]] = []
@contextlib.contextmanager
def _serve(path, capture, fps=20, fmt="image/png"):
server = FrameServer(path, capture, fps, fmt=fmt)
thread = threading.Thread(target=server.serve_forever, daemon=True)
started.append((server, thread))
thread.start()
assert server.ready.wait(5), "server never bound its socket"
try:
yield server
finally:
server.stop()
thread.join(5)
yield _serve
for server, thread in started:
server.stop()
thread.join(5)
@pytest.fixture
def emit_bytes():
"""Build an argv that writes exactly `data` to stdout and exits 0."""
@@ -149,11 +196,7 @@ def connect():
@pytest.fixture
def run_bg():
"""Run a callable on a daemon thread and surface the exception it raised.
The server's public surface has no shutdown hook (see README.dev.md), so the
thread is a daemon and the interpreter is allowed to drop it at exit.
"""
"""Run a callable on a daemon thread and surface the exception it raised."""
threads: list[tuple[threading.Thread, list]] = []
@@ -195,7 +238,6 @@ def rejects():
stubs' own `NotImplementedError` -- a test that is green precisely because
nothing is written yet. This refuses that one exception explicitly.
"""
import contextlib
@contextlib.contextmanager
def _rejects(*allowed: type[BaseException]):
+102
View File
@@ -0,0 +1,102 @@
#!/usr/bin/env python3
"""A stand-in for `grim`: writes one fake PNG frame to stdout.
Injected through `captureCommand` (see docs/CONTRACT.md) so no unit test needs a
compositor or a GPU. One script plays every part the server has to cope with: a
healthy backend, a broken one, a silent one, a slow one, and one that only
starts working later.
"""
from __future__ import annotations
import argparse
import os
import struct
import sys
import time
import zlib
def png_bytes(width: int = 16, height: int = 8, color: tuple[int, int, int] = (0, 0, 0),
level: int = 6) -> bytes:
"""A real, decodable RGB PNG of a solid colour.
`level` 0 stores the pixels uncompressed, which is how the tests get a frame
big enough to fill a socket buffer.
"""
def chunk(tag: bytes, data: bytes) -> bytes:
return (struct.pack(">I", len(data)) + tag + data
+ struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF))
ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
row = bytes(color) * width
raw = b"".join(b"\x00" + row for _ in range(height))
return (b"\x89PNG\r\n\x1a\n"
+ chunk(b"IHDR", ihdr)
+ chunk(b"IDAT", zlib.compress(raw, level))
+ chunk(b"IEND", b""))
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--width", type=int, default=16)
parser.add_argument("--height", type=int, default=8)
parser.add_argument("--counter", metavar="PATH",
help="file holding a call count; each frame's colour "
"differs so frames are distinguishable")
parser.add_argument("--gate", metavar="PATH",
help="fail until this path exists (a compositor that "
"is not up yet)")
parser.add_argument("--fail", action="store_true", help="exit non-zero")
parser.add_argument("--empty", action="store_true",
help="exit 0 having written nothing")
parser.add_argument("--garbage", action="store_true",
help="write output that is not an image")
parser.add_argument("--delay", type=float, default=0.0,
help="sleep this long before answering")
parser.add_argument("--big", action="store_true",
help="store the pixels uncompressed (a large frame)")
parser.add_argument("--message", default="fake_capture: simulated failure")
return parser
def main(argv: list[str] | None = None) -> int:
args = build_parser().parse_args(argv)
if args.delay:
time.sleep(args.delay)
if args.gate and not os.path.exists(args.gate):
sys.stderr.write(f"fake_capture: gate {args.gate} is missing\n")
return 4
if args.fail:
sys.stderr.write(args.message + "\n")
return 3
if args.empty:
sys.stderr.write("fake_capture: nothing to capture\n")
return 0
count = 0
if args.counter:
try:
with open(args.counter) as handle:
count = int(handle.read() or 0)
except FileNotFoundError:
count = 0
count += 1
with open(args.counter, "w") as handle:
handle.write(str(count))
if args.garbage:
sys.stdout.buffer.write(b"fake_capture: not an image, sorry\n")
sys.stdout.buffer.flush()
return 0
colour = (count % 251, (count * 7) % 251, (count * 13) % 251)
sys.stdout.buffer.write(
png_bytes(args.width, args.height, colour, 0 if args.big else 6)
)
sys.stdout.buffer.flush()
return 0
if __name__ == "__main__":
raise SystemExit(main())
+64
View File
@@ -0,0 +1,64 @@
"""Test doubles: an in-process capture backend and the fake capture command."""
from __future__ import annotations
import pathlib
import socket
import struct
import sys
import threading
import time
from fake_capture import png_bytes # noqa: F401 (re-exported for the tests)
from hhstream.capture import CaptureError
#: argv prefix for the fake `grim`; append its flags.
FAKE_CAPTURE = [sys.executable, str(pathlib.Path(__file__).with_name("fake_capture.py"))]
class FakeCapture:
"""A `CaptureBackend` with no subprocess: deterministic, fast, scriptable."""
def __init__(self, frames=None, size=(1280, 720), fail_until=0, delay=0.0):
self.frames = list(frames) if frames else [png_bytes(4, 2)]
self._size = size
self.fail_until = fail_until
self.delay = delay
self.calls = 0
self._lock = threading.Lock()
def grab(self) -> bytes:
with self._lock:
self.calls += 1
call = self.calls
if self.delay:
time.sleep(self.delay)
if call <= self.fail_until:
raise CaptureError(f"simulated capture failure {call}")
return self.frames[(call - 1 - self.fail_until) % len(self.frames)]
def size(self) -> tuple[int, int]:
if self.calls <= self.fail_until:
raise CaptureError("size is not known yet")
return self._size
def distinct_frames(count: int) -> list[bytes]:
"""`count` unique, decodable PNGs, in order."""
return [png_bytes(4, 2, (i % 251, (i * 7) % 251, (i * 13) % 251))
for i in range(1, count + 1)]
def connect(path: str, timeout: float = 5.0, rcvbuf: int | None = None) -> socket.socket:
conn = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
if rcvbuf is not None:
conn.setsockopt(socket.SOL_SOCKET, socket.SO_RCVBUF, rcvbuf)
conn.settimeout(timeout)
conn.connect(path)
return conn
def abort(conn: socket.socket) -> None:
"""Close with SO_LINGER 0: the peer sees the connection torn down, not EOF."""
conn.setsockopt(socket.SOL_SOCKET, socket.SO_LINGER, struct.pack("ii", 1, 0))
conn.close()
+86 -64
View File
@@ -1,94 +1,116 @@
"""`CommandCapture`: the injected capture backend.
docs/CONTRACT.md fixes the *shape* of this backend (a command that writes one
frame to stdout, plus the pixel size that goes into the Hello) but not the
mechanism by which the size is discovered. So these tests assert the observable
contract -- the bytes are whatever the command wrote, and `size()` agrees with
the frame `grab()` returns -- and never how the size is obtained.
"""
"""The capture backend, driven by the fake capture command (no compositor)."""
from __future__ import annotations
import struct
import subprocess
import os
import sys
from hhstream.capture import CommandCapture
import pytest
from helpers import FAKE_CAPTURE, png_bytes
from conftest import make_png
from hhstream.capture import CaptureError, CommandCapture, image_size
def png_size(data: bytes) -> tuple[int, int]:
w, h = struct.unpack(">II", data[16:24])
return w, h
def fake(*flags: str) -> list[str]:
return [*FAKE_CAPTURE, *flags]
def test_grab_returns_exactly_what_the_command_wrote(emit_bytes, tiny_png):
cap = CommandCapture(emit_bytes(tiny_png))
assert cap.grab() == tiny_png
def test_grab_returns_the_frame_and_size_comes_from_its_header():
capture = CommandCapture(fake("--width", "1280", "--height", "720"))
frame = capture.grab()
assert frame.startswith(b"\x89PNG\r\n\x1a\n")
assert capture.size() == (1280, 720)
def test_grab_is_binary_safe(emit_bytes):
payload = bytes(range(256)) + b"\n\r\x00\xff"
assert CommandCapture(emit_bytes(payload)).grab() == payload
def test_size_grabs_once_when_nothing_has_been_captured_yet():
capture = CommandCapture(fake("--width", "64", "--height", "32"))
assert capture.size() == (64, 32)
def test_grab_can_be_called_repeatedly(emit_bytes, tiny_png):
cap = CommandCapture(emit_bytes(tiny_png))
assert cap.grab() == cap.grab() == tiny_png
def test_a_failing_command_raises_and_reports_its_stderr(capfd):
capture = CommandCapture(fake("--fail", "--message", "grim: no outputs"))
with pytest.raises(CaptureError) as excinfo:
capture.grab()
assert "exited 3" in str(excinfo.value)
assert "grim: no outputs" in str(excinfo.value)
out, err = capfd.readouterr()
assert (out, err) == ("", ""), "the helper must not write to our stdio"
def test_grab_raises_when_the_command_fails(python_argv, rejects):
cap = CommandCapture(python_argv("import sys;sys.exit(3)"))
with rejects():
cap.grab()
def test_empty_output_is_a_failure_not_an_empty_frame(capfd):
with pytest.raises(CaptureError) as excinfo:
CommandCapture(fake("--empty")).grab()
assert "no output" in str(excinfo.value)
assert capfd.readouterr() == ("", "")
def test_grab_raises_when_the_command_does_not_exist(tmp_path, rejects):
cap = CommandCapture([str(tmp_path / "definitely-not-a-program")])
with rejects(OSError):
cap.grab()
def test_a_hanging_command_times_out():
capture = CommandCapture(fake("--delay", "10"), timeout=0.5)
with pytest.raises(CaptureError) as excinfo:
capture.grab()
assert "timed out" in str(excinfo.value)
def test_grab_does_not_swallow_stderr_noise(python_argv, tiny_png):
"""A capture tool that warns on stderr but succeeds still yields its frame."""
cap = CommandCapture(
python_argv(
"import sys;sys.stderr.write('warning: no XDG_RUNTIME_DIR\\n');"
"sys.stdout.buffer.write(bytes.fromhex(sys.argv[1]))",
tiny_png.hex(),
)
)
assert cap.grab() == tiny_png
def test_a_missing_command_is_a_capture_error():
with pytest.raises(CaptureError) as excinfo:
CommandCapture(["hhstream-no-such-program"]).grab()
assert "could not be run" in str(excinfo.value)
def test_env_is_handed_to_the_child(python_argv):
"""The compositor is reached through WAYLAND_DISPLAY/XDG_RUNTIME_DIR in env."""
cap = CommandCapture(
python_argv("import os,sys;sys.stdout.write(os.environ['WAYLAND_DISPLAY'])"),
env={"WAYLAND_DISPLAY": "wayland-9", "PATH": "/nonexistent"},
)
assert cap.grab().strip() == b"wayland-9"
def test_unmeasurable_output_cannot_produce_a_hello():
capture = CommandCapture(fake("--garbage"))
assert capture.grab() == b"fake_capture: not an image, sorry\n"
with pytest.raises(CaptureError) as excinfo:
capture.size()
assert "pixel size" in str(excinfo.value)
def test_timeout_is_enforced(python_argv, rejects):
cap = CommandCapture(python_argv("import time;time.sleep(30)"), timeout=0.5)
with rejects(subprocess.TimeoutExpired, OSError):
cap.grab()
def test_a_failure_after_a_good_frame_keeps_the_known_size():
good = CommandCapture(fake("--width", "100", "--height", "50"))
assert good.size() == (100, 50)
good.argv = fake("--fail")
with pytest.raises(CaptureError):
good.grab()
assert good.size() == (100, 50)
def test_size_reports_the_size_of_the_frame_it_captures(emit_bytes):
frame = make_png(width=640, height=360)
cap = CommandCapture(emit_bytes(frame))
assert cap.size() == png_size(cap.grab()) == (640, 360)
def test_env_is_overlaid_on_our_own_environment():
argv = [sys.executable, "-c",
"import os,sys;sys.stdout.write(os.environ['WAYLAND_DISPLAY']+':'+"
"('PATH' in os.environ and 'haspath' or 'nopath'))"]
capture = CommandCapture(argv, env={"WAYLAND_DISPLAY": "wayland-9"})
assert capture.grab() == b"wayland-9:haspath"
assert "WAYLAND_DISPLAY" not in os.environ, "our own environment was mutated"
def test_size_is_a_pair_of_positive_ints(emit_bytes, tiny_png):
w, h = CommandCapture(emit_bytes(tiny_png)).size()
assert isinstance(w, int) and isinstance(h, int)
assert w > 0 and h > 0, "the contract forbids a Hello with zero size"
def test_empty_argv_and_bad_timeout_are_rejected_up_front():
with pytest.raises(ValueError):
CommandCapture([])
with pytest.raises(ValueError):
CommandCapture(["true"], timeout=0)
def test_size_never_reports_zero_for_a_real_frame(emit_bytes):
cap = CommandCapture(emit_bytes(make_png(width=1, height=1)))
assert cap.size() == (1, 1)
def test_the_helpers_stdin_is_closed_so_it_cannot_steal_ours():
code = ("import sys;"
"sys.stdout.buffer.write(b'EMPTY' if not sys.stdin.read() else b'DATA')")
assert CommandCapture([sys.executable, "-c", code]).grab() == b"EMPTY"
@pytest.mark.parametrize("width,height", [(1, 1), (16, 9), (3840, 2160)])
def test_image_size_reads_png_headers(width, height):
assert image_size(png_bytes(width, height)) == (width, height)
def test_image_size_reads_a_jpeg_sof_header():
jpeg = (b"\xff\xd8"
+ b"\xff\xe0" + (16).to_bytes(2, "big") + b"JFIF\x00" + b"\x00" * 9
+ b"\xff\xc0" + (17).to_bytes(2, "big") + b"\x08"
+ (720).to_bytes(2, "big") + (1280).to_bytes(2, "big")
+ b"\x03" + b"\x00" * 9)
assert image_size(jpeg) == (1280, 720)
@pytest.mark.parametrize("data", [b"", b"not an image", b"\x89PNG\r\n\x1a\n",
b"\xff\xd8", b"\xff\xd8\xff\xc0\x00\x11"])
def test_image_size_returns_none_when_it_cannot_tell(data):
assert image_size(data) is None
+172
View File
@@ -0,0 +1,172 @@
"""The command line: the flag names the NixOS module passes, end to end.
The server and the client run as real processes here, with the fake capture
command standing in for `grim`, so nothing needs a compositor.
"""
from __future__ import annotations
import json
import os
import pathlib
import subprocess
import sys
import time
import pytest
from helpers import FAKE_CAPTURE
from hhstream import client, server
SRC = str(pathlib.Path(__file__).resolve().parents[2] / "src")
RUN_SERVER = [sys.executable, "-c",
"from hhstream.server import main; raise SystemExit(main())"]
RUN_CLIENT = [sys.executable, "-c",
"from hhstream.client import main; raise SystemExit(main())"]
def child_env() -> dict[str, str]:
env = dict(os.environ)
env["PYTHONPATH"] = SRC + (os.pathsep + env["PYTHONPATH"] if "PYTHONPATH" in env else "")
return env
def capture_flags(*flags: str) -> list[str]:
"""`--capture-command` once per argv token, as the module passes it."""
out = []
for token in (*FAKE_CAPTURE, *flags):
out += ["--capture-command", token]
return out
def wait_for_socket(path: str, proc: subprocess.Popen, timeout: float = 10.0) -> None:
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
if os.path.exists(path):
return
if proc.poll() is not None:
raise AssertionError(f"server exited {proc.returncode}: {proc.stderr.read()}")
time.sleep(0.05)
raise AssertionError(f"{path} never appeared")
# -- argument parsing ----------------------------------------------------
def test_server_defaults_match_the_contract():
args = server.build_parser().parse_args([])
assert args.socket == "/run/hyprland-headless-stream/stream.sock"
assert (args.fps, args.format, args.capture_command) == (30, "png", None)
assert server.DEFAULT_CAPTURE_COMMAND == ["grim", "-t", "png", "-"]
def test_capture_command_is_one_argv_token_per_flag():
argv = ["--capture-command", "grim", "--capture-command", "-t",
"--capture-command", "png", "--capture-command", "-"]
parsed = server.build_parser().parse_args(server._join_capture_tokens(argv))
assert parsed.capture_command == ["grim", "-t", "png", "-"]
def test_capture_command_also_accepts_the_equals_form():
argv = ["--capture-command=grim", "--capture-command=-t", "--capture-command=-"]
parsed = server.build_parser().parse_args(server._join_capture_tokens(argv))
assert parsed.capture_command == ["grim", "-t", "-"]
@pytest.mark.parametrize("bad", [["--fps", "0"], ["--fps", "-3"],
["--format", "webp"]])
def test_the_server_rejects_bad_flags(bad):
with pytest.raises(SystemExit):
server.build_parser().parse_args(bad)
def test_client_defaults():
args = client.build_parser().parse_args([])
assert (args.socket, args.count, args.out, args.timeout) == (
client.DEFAULT_SOCKET, 1, None, 10.0)
# -- the real thing ------------------------------------------------------
def test_server_and_client_processes_talk_to_each_other(workdir):
sock = str(workdir / "s.sock")
server_proc = subprocess.Popen(
[*RUN_SERVER, "--socket", sock, "--fps", "10", "--format", "png",
*capture_flags("--width", "1280", "--height", "720", "--counter",
str(workdir / "n"))],
env=child_env(), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
)
try:
wait_for_socket(sock, server_proc)
done = subprocess.run(
[*RUN_CLIENT, "--socket", sock, "--count", "2",
"--out", str(workdir / "frame.png"), "--timeout", "10"],
env=child_env(), capture_output=True, text=True, timeout=30,
)
assert done.returncode == 0, done.stderr
lines = done.stdout.splitlines()
assert json.loads(lines[0]) == {
"magic": "HHS1", "width": 1280, "height": 720,
"format": "image/png", "fps": 10,
}
assert len(lines) == 3
first = (workdir / "frame-1.png").read_bytes()
second = (workdir / "frame-2.png").read_bytes()
assert first.startswith(b"\x89PNG\r\n\x1a\n")
assert second.startswith(b"\x89PNG\r\n\x1a\n")
assert first != second, "the two frames should be two different captures"
assert server_proc.poll() is None, "the server must still be running"
finally:
server_proc.terminate()
out, err = server_proc.communicate(timeout=10)
assert server_proc.returncode == 0
assert out == "", "the server must keep its stdout clean"
assert os.path.exists(sock) is False, "the socket file should be cleaned up"
def test_the_format_flag_becomes_the_mime_type_in_the_hello(workdir):
sock = str(workdir / "s.sock")
server_proc = subprocess.Popen(
[*RUN_SERVER, "--socket", sock, "--fps", "5", "--format", "jpeg",
*capture_flags("--width", "640", "--height", "480")],
env=child_env(), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
)
try:
wait_for_socket(sock, server_proc)
hello, frames = client.read_stream(sock, count=1, timeout=10)
assert hello == {"magic": "HHS1", "width": 640, "height": 480,
"format": "image/jpeg", "fps": 5}
assert len(frames) == 1
finally:
server_proc.terminate()
server_proc.communicate(timeout=10)
def test_a_broken_capture_command_does_not_kill_the_server(workdir):
sock = str(workdir / "s.sock")
server_proc = subprocess.Popen(
[*RUN_SERVER, "--socket", sock, "--fps", "20", *capture_flags("--fail")],
env=child_env(), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
)
try:
wait_for_socket(sock, server_proc)
time.sleep(1.0)
assert server_proc.poll() is None, "the server exited on a capture failure"
assert os.path.exists(sock), "the socket went away"
finally:
server_proc.terminate()
out, err = server_proc.communicate(timeout=10)
assert out == ""
assert "capture failed" in err
assert "simulated failure" in err, "the helper's stderr should be reported"
def test_the_server_exits_nonzero_when_the_socket_cannot_be_bound(workdir):
blocked = workdir / "regular-file"
blocked.write_text("not a socket")
done = subprocess.run(
[*RUN_SERVER, "--socket", str(blocked), *capture_flags()],
env=child_env(), capture_output=True, text=True, timeout=30,
)
assert done.returncode == 1
assert "cannot serve" in done.stderr
assert blocked.read_text() == "not a socket"
+108 -116
View File
@@ -1,155 +1,147 @@
"""`hhstream.client` read against a hand-written, contract-conformant server.
The stand-in server is written straight from docs/CONTRACT.md rather than with
`hhstream.protocol`, so `fetch` is measured against the document instead of
against its own framing helpers.
"""
"""The client, against the real server and against a hand-written stub server."""
from __future__ import annotations
import contextlib
import json
import os
import socket
import threading
import pytest
from helpers import FakeCapture, connect, distinct_frames
from hhstream import client
from conftest import make_png
from hhstream import client, protocol
class ContractServer:
"""Writes the Hello and `frames` exactly as docs/CONTRACT.md specifies."""
@contextlib.contextmanager
def stub_server(path: str, payload: bytes):
"""A server that writes exactly `payload` to one client, then hangs up."""
listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
listener.bind(path)
listener.listen(1)
def __init__(self, path: str, frames, width=1280, height=720, fps=30,
fmt="image/png", send_hello=True, hang=False):
self.path = path
self.frames = list(frames)
self.meta = dict(magic="HHS1", width=width, height=height, format=fmt, fps=fps)
self.send_hello = send_hello
self.hang = hang
self.connections = 0
self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
if os.path.exists(path):
os.unlink(path)
self.sock.bind(path)
os.chmod(path, 0o660)
self.sock.listen(8)
self._stop = threading.Event()
self._thread = threading.Thread(target=self._serve, daemon=True)
self._thread.start()
def _serve(self):
while not self._stop.is_set():
try:
conn, _ = self.sock.accept()
except OSError:
return
self.connections += 1
threading.Thread(target=self._handle, args=(conn,), daemon=True).start()
def _handle(self, conn):
def run():
try:
if self.hang:
self._stop.wait(30)
return
if self.send_hello:
conn.sendall(json.dumps(self.meta).encode("utf-8") + b"\n")
for payload in self.frames:
conn.sendall(str(len(payload)).encode("ascii") + b"\n" + payload)
self._stop.wait(5)
conn, _ = listener.accept()
except OSError:
pass
finally:
conn.close()
return
with conn:
try:
conn.sendall(payload)
except OSError:
pass
def close(self):
self._stop.set()
self.sock.close()
thread = threading.Thread(target=run, daemon=True)
thread.start()
try:
yield
finally:
listener.close()
thread.join(5)
@pytest.fixture
def contract_server(sock_path):
made = []
def build(frames, **kw):
srv = ContractServer(sock_path, frames, **kw)
made.append(srv)
return srv
yield build
for srv in made:
srv.close()
def test_fetch_returns_the_payloads(sock_path, serve):
frames = distinct_frames(30)
with serve(sock_path, FakeCapture(frames=frames), fps=50):
got = client.fetch(sock_path, count=3, timeout=5)
assert len(got) == 3
assert all(payload in frames for payload in got)
def test_fetch_returns_one_payload_by_default(contract_server, sock_path):
frame = make_png(width=32, height=16)
contract_server([frame] * 4)
assert client.fetch(sock_path) == [frame]
def test_read_stream_also_returns_the_hello(sock_path, serve):
with serve(sock_path, FakeCapture(frames=distinct_frames(5)), fps=25):
hello, frames = client.read_stream(sock_path, count=1, timeout=5)
assert hello == {"magic": "HHS1", "width": 1280, "height": 720,
"format": "image/png", "fps": 25}
assert len(frames) == 1
def test_fetch_consumes_the_hello_and_returns_only_payloads(contract_server, sock_path):
frames = [make_png(value=v) for v in (0x11, 0x22, 0x33)]
contract_server(frames)
got = client.fetch(sock_path, count=3)
assert got == frames
assert not any(b"HHS1" in payload for payload in got)
def test_fetch_returns_fewer_frames_when_the_server_hangs_up(sock_path):
wire = protocol.hello(4, 2, "image/png", 1) + protocol.frame(b"only one")
with stub_server(sock_path, wire):
assert client.fetch(sock_path, count=5, timeout=5) == [b"only one"]
def test_fetch_stops_at_count(contract_server, sock_path):
contract_server([make_png()] * 10)
assert len(client.fetch(sock_path, count=2)) == 2
def test_fetch_on_a_missing_socket_raises_oserror(sock_path):
with pytest.raises(OSError):
client.fetch(sock_path, count=1, timeout=1)
def test_fetch_handles_a_payload_with_a_newline_in_it(contract_server, sock_path):
payload = b"12\n" + bytes(range(256))
contract_server([payload, payload])
assert client.fetch(sock_path, count=2) == [payload, payload]
def test_fetch_rejects_a_bad_hello(sock_path):
with stub_server(sock_path, b'{"magic":"NOPE"}\n'):
with pytest.raises(ValueError):
client.fetch(sock_path, count=1, timeout=5)
def test_fetch_raises_when_the_socket_does_not_exist(tmp_path, rejects):
with rejects(OSError):
client.fetch(str(tmp_path / "absent.sock"))
def test_fetch_rejects_a_truncated_frame(sock_path):
wire = protocol.hello(4, 2, "image/png", 1) + b"100\nshort"
with stub_server(sock_path, wire):
with pytest.raises(EOFError):
client.fetch(sock_path, count=1, timeout=5)
def test_fetch_times_out_on_a_silent_server(contract_server, sock_path, rejects):
contract_server([], hang=True)
with rejects(OSError, EOFError, TimeoutError):
client.fetch(sock_path, count=1, timeout=1.0)
# -- the CLI -------------------------------------------------------------
def test_main_prints_the_hello_and_writes_one_frame(sock_path, serve, workdir, capsys):
frames = distinct_frames(5)
with serve(sock_path, FakeCapture(frames=frames), fps=25):
out = workdir / "frame.png"
assert client.main(["--socket", sock_path, "--count", "1",
"--out", str(out), "--timeout", "5"]) == 0
printed = capsys.readouterr().out.splitlines()
assert json.loads(printed[0])["magic"] == "HHS1"
assert f"-> {out}" in printed[1]
assert out.read_bytes() in frames
def test_fetch_does_not_hang_when_the_server_hangs_up_early(
contract_server, sock_path, rejects
):
contract_server([make_png()])
with rejects(OSError, EOFError, TimeoutError):
client.fetch(sock_path, count=5, timeout=2.0)
def test_main_suffixes_the_output_when_count_is_more_than_one(sock_path, serve,
workdir, capsys):
with serve(sock_path, FakeCapture(frames=distinct_frames(20)), fps=50):
assert client.main(["--socket", sock_path, "--count", "2",
"--out", str(workdir / "shot.png"), "--timeout", "5"]) == 0
assert (workdir / "shot-1.png").exists()
assert (workdir / "shot-2.png").exists()
assert not (workdir / "shot.png").exists()
assert len(capsys.readouterr().out.splitlines()) == 3 # hello + two frames
def test_build_parser_matches_the_documented_invocation():
# README.md: hhstream-client --socket <path> --count 1 --out frame.png
parser = client.build_parser()
args = parser.parse_args(["--socket", "/run/x.sock", "--count", "1", "--out", "frame.png"])
assert args.socket == "/run/x.sock"
assert args.count == 1
assert args.out == "frame.png"
def test_main_writes_payloads_to_stdout_with_out_dash(sock_path, serve, capsysbinary):
frame = distinct_frames(1)[0]
with serve(sock_path, FakeCapture(frames=[frame]), fps=25):
assert client.main(["--socket", sock_path, "--count", "2", "--out", "-",
"--timeout", "5"]) == 0
captured = capsysbinary.readouterr()
assert captured.out == frame * 2, "payloads must be the only thing on stdout"
assert b'"magic":"HHS1"' in captured.err
def test_parser_defaults_to_the_contract_socket():
args = client.build_parser().parse_args([])
assert args.socket == client.DEFAULT_SOCKET == "/run/hyprland-headless-stream/stream.sock"
def test_main_reports_a_missing_socket_without_a_traceback(sock_path, capsys):
assert client.main(["--socket", sock_path, "--timeout", "1"]) == 1
assert "hhstream-client:" in capsys.readouterr().err
def test_main_writes_the_frame_it_read(contract_server, sock_path, tmp_path):
frame = make_png(width=8, height=8)
contract_server([frame])
out = tmp_path / "frame.png"
rc = client.main(["--socket", sock_path, "--count", "1", "--out", str(out)])
assert rc == 0
assert out.read_bytes() == frame
def test_main_reports_a_short_stream(sock_path, capsys):
wire = protocol.hello(4, 2, "image/png", 1) + protocol.frame(b"one")
with stub_server(sock_path, wire):
assert client.main(["--socket", sock_path, "--count", "3",
"--timeout", "5"]) == 1
assert "wanted 3 frames, got 1" in capsys.readouterr().err
def test_main_reports_failure_without_a_traceback(tmp_path):
rc = client.main(["--socket", str(tmp_path / "absent.sock"), "--count", "1"])
assert rc != 0
def test_main_rejects_a_negative_count(sock_path, capsys):
assert client.main(["--socket", sock_path, "--count", "-1"]) == 2
assert "--count" in capsys.readouterr().err
def test_default_socket_matches_the_contract():
assert client.DEFAULT_SOCKET == "/run/hyprland-headless-stream/stream.sock"
assert client.build_parser().parse_args([]).socket == client.DEFAULT_SOCKET
def test_a_client_can_be_interrupted_without_disturbing_the_server(sock_path, serve):
"""Two sequential fetches: the first client's exit leaves the socket usable."""
with serve(sock_path, FakeCapture(frames=distinct_frames(40)), fps=50):
assert len(client.fetch(sock_path, count=2, timeout=5)) == 2
conn = connect(sock_path)
conn.close() # leave mid-stream
assert len(client.fetch(sock_path, count=2, timeout=5)) == 2
+171 -154
View File
@@ -1,10 +1,4 @@
"""Framing, byte for byte, against docs/CONTRACT.md.
The contract is unusually specific about the length prefix ("plain ASCII digits;
no leading zeros, no `+`, no spaces"), so these tests assert on exact bytes
rather than on round-trips alone -- a reader and writer that agree with each
other but not with the document would pass a round-trip test.
"""
"""The framing. Other people's clients depend on these bytes being exact."""
from __future__ import annotations
@@ -13,157 +7,180 @@ import json
import pytest
from hhstream import protocol
from hhstream import MAGIC, protocol
# -- Hello ----------------------------------------------------------------
# -- Hello ---------------------------------------------------------------
def test_hello_is_one_json_line():
line = protocol.hello(1280, 720, "image/png", 30)
assert isinstance(line, bytes)
assert line.endswith(b"\n")
assert line.count(b"\n") == 1, "the Hello is exactly one line"
def test_hello_fields_match_the_contract():
obj = json.loads(protocol.hello(1280, 720, "image/png", 30).decode("utf-8"))
assert obj["magic"] == "HHS1"
assert obj["width"] == 1280
assert obj["height"] == 720
assert obj["format"] == "image/png"
assert obj["fps"] == 30
def test_hello_carries_the_jpeg_format_too():
obj = json.loads(protocol.hello(640, 480, "image/jpeg", 15).decode("utf-8"))
assert obj["format"] == "image/jpeg"
def test_hello_round_trips_through_parse_hello():
obj = protocol.parse_hello(protocol.hello(1920, 1080, "image/png", 60))
assert obj["magic"] == "HHS1"
assert (obj["width"], obj["height"]) == (1920, 1080)
assert obj["fps"] == 60
def test_parse_hello_tolerates_the_trailing_newline_or_not():
line = protocol.hello(800, 600, "image/png", 24)
assert protocol.parse_hello(line) == protocol.parse_hello(line.rstrip(b"\n"))
def test_parse_hello_rejects_a_foreign_magic(rejects):
bad = json.dumps(
{"magic": "HHS0", "width": 1, "height": 1, "format": "image/png", "fps": 1}
).encode()
with rejects():
protocol.parse_hello(bad)
@pytest.mark.parametrize("missing", ["width", "height", "format", "fps"])
def test_parse_hello_rejects_a_missing_field(missing, rejects):
obj = {
"magic": "HHS1",
"width": 1280,
"height": 720,
"format": "image/png",
"fps": 30,
}
del obj[missing]
with rejects():
protocol.parse_hello(json.dumps(obj).encode())
@pytest.mark.parametrize("junk", [b"", b"not json", b"[]", b"null", b'{"magic":"HHS1"'])
def test_parse_hello_rejects_junk(junk, rejects):
with rejects():
protocol.parse_hello(junk)
# -- frames ---------------------------------------------------------------
def test_frame_prefixes_the_payload_length_in_ascii():
assert protocol.frame(b"hello") == b"5\n" + b"hello"
def test_frame_length_counts_the_payload_only():
payload = b"\x00" * 1234
framed = protocol.frame(payload)
prefix, _, body = framed.partition(b"\n")
assert prefix == b"1234"
assert int(prefix) == len(payload) == len(body)
def test_frame_length_has_no_leading_zeros_sign_or_spaces():
for n in (1, 7, 10, 99, 100, 65536):
prefix = protocol.frame(b"x" * n).split(b"\n", 1)[0]
assert prefix == str(n).encode()
assert not prefix.startswith(b"0")
assert not prefix.startswith(b"+")
assert b" " not in prefix
def test_frame_is_binary_safe():
payload = bytes(range(256)) + b"\n42\n" + b"\xff\xfe"
framed = protocol.frame(payload)
assert framed == str(len(payload)).encode() + b"\n" + payload
def test_read_frame_round_trips():
payload = bytes(range(256)) * 8
assert protocol.read_frame(io.BytesIO(protocol.frame(payload))) == payload
def test_read_frame_reads_exactly_one_frame_and_stops():
stream = io.BytesIO(protocol.frame(b"aaa") + protocol.frame(b"bbbb"))
assert protocol.read_frame(stream) == b"aaa"
assert protocol.read_frame(stream) == b"bbbb"
assert protocol.read_frame(stream) is None
def test_read_frame_returns_none_on_a_clean_eof():
assert protocol.read_frame(io.BytesIO(b"")) is None
def test_read_frame_raises_on_a_truncated_payload(rejects):
with rejects(EOFError):
protocol.read_frame(io.BytesIO(b"10\nshort"))
@pytest.mark.parametrize(
"bad",
[
b"007\n0000000", # leading zeros
b"+5\nhello", # sign
b" 5\nhello", # leading space
b"5 \nhello", # trailing space
b"abc\nhello", # not a number
b"-1\n", # negative
b"1_0\nxxxxxxxxxx", # python's int() accepts this; the contract does not
],
)
def test_read_frame_rejects_a_malformed_length_prefix(bad, rejects):
with rejects(ValueError):
protocol.read_frame(io.BytesIO(bad))
def test_read_frame_handles_a_megabyte_payload():
payload = bytes(range(256)) * 4096
assert len(payload) == 1024 * 1024
assert protocol.read_frame(io.BytesIO(protocol.frame(payload))) == payload
def test_read_hello_then_frames_is_the_contract_sequence():
wire = (
protocol.hello(1280, 720, "image/png", 30)
+ protocol.frame(b"one")
+ protocol.frame(b"two")
def test_hello_matches_the_contract_byte_for_byte():
assert protocol.hello(1280, 720, "image/png", 30) == (
b'{"magic":"HHS1","width":1280,"height":720,"format":"image/png","fps":30}\n'
)
stream = io.BytesIO(wire)
hello = protocol.read_hello(stream)
assert hello["magic"] == "HHS1"
assert (hello["width"], hello["height"]) == (1280, 720)
def test_hello_round_trip():
line = protocol.hello(640, 480, "image/jpeg", 15)
assert line.endswith(b"\n") and line.count(b"\n") == 1
assert protocol.parse_hello(line) == {
"magic": MAGIC, "width": 640, "height": 480,
"format": "image/jpeg", "fps": 15,
}
def test_parse_hello_tolerates_a_missing_trailing_newline():
line = protocol.hello(8, 8, "image/png", 1)
assert protocol.parse_hello(line.rstrip(b"\n")) == protocol.parse_hello(line)
@pytest.mark.parametrize("width,height,fps", [(0, 720, 30), (1280, 0, 30),
(1280, 720, 0), (-1, 720, 30)])
def test_hello_refuses_a_zero_or_negative_size(width, height, fps):
with pytest.raises(ValueError):
protocol.hello(width, height, "image/png", fps)
@pytest.mark.parametrize("payload", [
b"",
b"not json at all",
b"[1,2,3]",
b'"a string"',
b'{"magic":"HHS0","width":1,"height":1,"format":"image/png","fps":1}',
b'{"width":1,"height":1,"format":"image/png","fps":1}',
b'{"magic":"HHS1","height":1,"format":"image/png","fps":1}',
b'{"magic":"HHS1","width":1,"height":1,"fps":1}',
b'{"magic":"HHS1","width":1,"height":1,"format":"image/png"}',
b'{"magic":"HHS1","width":0,"height":1,"format":"image/png","fps":1}',
b'{"magic":"HHS1","width":"1","height":1,"format":"image/png","fps":1}',
b'{"magic":"HHS1","width":true,"height":1,"format":"image/png","fps":1}',
b'{"magic":"HHS1","width":1,"height":1,"format":"","fps":1}',
b'{"magic":"HHS1","width":1,"height":1,"format":"image/png","fps":1}\xff',
])
def test_parse_hello_rejects_bad_input(payload):
with pytest.raises(ValueError):
protocol.parse_hello(payload)
def test_read_hello_then_frames_from_one_stream():
stream = io.BytesIO(
protocol.hello(2, 2, "image/png", 5) + protocol.frame(b"one") + protocol.frame(b"two")
)
assert protocol.read_hello(stream)["width"] == 2
assert protocol.read_frame(stream) == b"one"
assert protocol.read_frame(stream) == b"two"
assert protocol.read_frame(stream) is None
def test_read_hello_on_a_truncated_line():
with pytest.raises(EOFError):
protocol.read_hello(io.BytesIO(b'{"magic":"HHS1"'))
def test_read_hello_gives_up_on_an_endless_line():
with pytest.raises(ValueError):
protocol.read_hello(_Endless(b"x"))
# -- frames --------------------------------------------------------------
@pytest.mark.parametrize("payload", [
b"",
b"\n",
b"a\nb",
b"\n\n\n",
b"12\n34", # payload that looks like a frame itself
b"\x89PNG\r\n\x1a\n",
bytes(range(256)),
b"x" * (1 << 20),
])
def test_frame_round_trip(payload):
wire = protocol.frame(payload)
assert wire.startswith(str(len(payload)).encode("ascii") + b"\n")
assert len(wire) == len(payload) + len(str(len(payload))) + 1
assert protocol.read_frame(io.BytesIO(wire)) == payload
def test_zero_length_frame_is_a_frame_not_an_eof():
stream = io.BytesIO(protocol.frame(b"") + protocol.frame(b"after"))
assert protocol.frame(b"") == b"0\n"
assert protocol.read_frame(stream) == b""
assert protocol.read_frame(stream) == b"after"
def test_payload_containing_newlines_is_not_resplit():
payload = b"row1\nrow2\n" * 500
stream = io.BytesIO(protocol.frame(payload) + protocol.frame(b"next"))
assert protocol.read_frame(stream) == payload
assert protocol.read_frame(stream) == b"next"
def test_length_prefix_has_no_leading_zeros_and_no_sign():
assert protocol.frame(b"abc") == b"3\nabc"
assert not protocol.frame(b"x" * 10).startswith(b"+")
def test_read_frame_stops_exactly_at_the_end_of_the_payload():
stream = io.BytesIO(protocol.frame(b"abc") + b"LEFTOVER")
assert protocol.read_frame(stream) == b"abc"
assert stream.read() == b"LEFTOVER"
def test_clean_eof_between_frames_is_none():
assert protocol.read_frame(io.BytesIO(b"")) is None
@pytest.mark.parametrize("wire", [
b"\nabc", # empty length prefix
b"007\nabcdefg", # leading zero
b"0012\n", # leading zeros
b"12x\nabc", # not a digit
b" 3\nabc", # leading space
b"+3\nabc", # sign
b"-3\nabc", # negative
b"3.0\nabc", # not an integer
b"1" * 21 + b"\n", # absurdly long prefix
])
def test_garbage_length_prefix_raises_value_error(wire):
with pytest.raises(ValueError):
protocol.read_frame(io.BytesIO(wire))
@pytest.mark.parametrize("wire", [
b"5\nabc", # payload short
b"5\n", # payload absent
b"1048576\n" + b"x" * 1000,
b"12", # EOF inside the length prefix
])
def test_truncated_payload_raises_eof_error(wire):
with pytest.raises(EOFError):
protocol.read_frame(io.BytesIO(wire))
def test_read_frame_gives_up_on_endless_digits_instead_of_hanging():
with pytest.raises(ValueError):
protocol.read_frame(_Endless(b"1"))
def test_a_huge_length_prefix_does_not_preallocate():
# 10**19 bytes is not going to arrive; we must notice the EOF, not the RAM.
with pytest.raises(EOFError):
protocol.read_frame(io.BytesIO(b"9999999999999999999\nshort"))
def test_frame_rejects_non_bytes():
with pytest.raises(ValueError):
protocol.frame("a str is not bytes") # type: ignore[arg-type]
def test_hello_is_valid_json_with_the_documented_field_order():
line = protocol.hello(1280, 720, "image/png", 30).decode("utf-8")
assert list(json.loads(line)) == ["magic", "width", "height", "format", "fps"]
class _Endless:
"""A stream that never ends and never blocks -- proves we bail out."""
def __init__(self, byte: bytes):
self.byte = byte
def read(self, size: int = -1) -> bytes:
return self.byte * (1 if size in (-1, None) else size)
+222 -171
View File
@@ -1,202 +1,253 @@
"""`FrameServer` against a real (temporary) socket.
These drive the server in-process on a daemon thread and talk to it over an
AF_UNIX socket inside `tmp_path`. Nothing here touches the host: no compositor,
no /run, no network. The reader is `hhstream.protocol`, which its own tests pin
to the document.
"""
"""The server's obligations from docs/CONTRACT.md, none of which need a GPU."""
from __future__ import annotations
import os
import socket
import stat
import threading
import time
import pytest
from helpers import (FAKE_CAPTURE, FakeCapture, abort, connect, distinct_frames,
png_bytes)
from hhstream import protocol
from hhstream.capture import CommandCapture
from hhstream.server import FrameServer
from conftest import make_png
HELLO_WAIT = 5.0
def wait_for_socket(path: str, deadline: float = 10.0) -> None:
end = time.monotonic() + deadline
while time.monotonic() < end:
if os.path.exists(path):
return
time.sleep(0.02)
raise AssertionError(f"server never bound {path}")
def read_hello(conn, timeout=HELLO_WAIT):
conn.settimeout(timeout)
return protocol.read_hello(conn.makefile("rb"))
def read_stream(sock: socket.socket):
"""A file object over the socket, for protocol.read_* to consume."""
return sock.makefile("rb")
def test_fps_must_be_positive(sock_path):
for bad in (0, -1, True, 1.5):
with pytest.raises(ValueError):
FrameServer(sock_path, FakeCapture(), bad)
def test_serves_the_hello_then_frames(sock_path, stub_capture, run_bg, connect):
cap = stub_capture(frames=[make_png(width=64, height=32)], size=(64, 32))
box = run_bg(FrameServer(sock_path, cap, fps=30).serve_forever)
wait_for_socket(sock_path)
with read_stream(connect(sock_path)) as stream:
hello = protocol.read_hello(stream)
assert hello["magic"] == "HHS1"
assert (hello["width"], hello["height"]) == (64, 32)
assert hello["format"] == "image/png"
assert hello["fps"] == 30
first = protocol.read_frame(stream)
second = protocol.read_frame(stream)
assert not box, f"server thread died: {box}"
assert first and second
assert len(first) > 0 and len(second) > 0
def test_hello_format_follows_the_constructor(sock_path, stub_capture, run_bg, connect):
cap = stub_capture()
run_bg(FrameServer(sock_path, cap, fps=15, fmt="image/jpeg").serve_forever)
wait_for_socket(sock_path)
with read_stream(connect(sock_path)) as stream:
hello = protocol.read_hello(stream)
assert hello["format"] == "image/jpeg"
assert hello["fps"] == 15
def test_socket_mode_is_0660(sock_path, stub_capture, run_bg):
# docs/CONTRACT.md -> Socket: "mode 0660".
run_bg(FrameServer(sock_path, stub_capture(), fps=30).serve_forever)
wait_for_socket(sock_path)
assert os.stat(sock_path).st_mode & 0o777 == 0o660
def test_a_stale_socket_file_does_not_prevent_startup(sock_path, stub_capture, run_bg, connect):
# docs/CONTRACT.md: "The socket path is removed and recreated on start."
with open(sock_path, "wb") as fh:
fh.write(b"leftover from a crashed run")
run_bg(FrameServer(sock_path, stub_capture(), fps=30).serve_forever)
wait_for_socket(sock_path)
with read_stream(connect(sock_path)) as stream:
assert protocol.read_hello(stream)["magic"] == "HHS1"
def test_every_client_gets_its_own_hello_and_frames(sock_path, stub_capture, run_bg, connect):
# docs/CONTRACT.md: "Each client gets its own copy of the header and of
# every subsequent frame."
run_bg(FrameServer(sock_path, stub_capture(size=(128, 96)), fps=30).serve_forever)
wait_for_socket(sock_path)
streams = [read_stream(connect(sock_path)) for _ in range(3)]
try:
def test_two_clients_each_get_their_own_hello_and_frames(sock_path, serve):
capture = FakeCapture(frames=distinct_frames(20), size=(1280, 720))
with serve(sock_path, capture, fps=30):
first, second = connect(sock_path), connect(sock_path)
streams = [first.makefile("rb"), second.makefile("rb")]
hellos = [protocol.read_hello(s) for s in streams]
assert hellos[0] == hellos[1] == {
"magic": "HHS1", "width": 1280, "height": 720,
"format": "image/png", "fps": 30,
}
for stream in streams:
hello = protocol.read_hello(stream)
assert (hello["width"], hello["height"]) == (128, 96)
assert len(protocol.read_frame(stream)) > 0
finally:
for stream in streams:
stream.close()
for _ in range(3):
payload = protocol.read_frame(stream)
assert payload and payload.startswith(b"\x89PNG\r\n\x1a\n")
first.close()
second.close()
def test_a_client_disconnecting_does_not_take_the_server_down(
sock_path, stub_capture, run_bg, connect
):
# docs/CONTRACT.md: "A client disconnecting (or dying mid-frame) must never
# take the server down and must never disturb the other clients."
box = run_bg(FrameServer(sock_path, stub_capture(), fps=30).serve_forever)
wait_for_socket(sock_path)
survivor = read_stream(connect(sock_path))
assert protocol.read_hello(survivor)["magic"] == "HHS1"
for _ in range(3):
doomed = connect(sock_path)
doomed.recv(1) # take one byte of the Hello, then die mid-message
doomed.close()
assert len(protocol.read_frame(survivor)) > 0
survivor.close()
with read_stream(connect(sock_path)) as latecomer:
assert protocol.read_hello(latecomer)["magic"] == "HHS1"
assert not box, f"server thread died: {box}"
def test_a_client_arriving_later_is_served_too(sock_path, serve):
with serve(sock_path, FakeCapture(frames=distinct_frames(50)), fps=50):
early = connect(sock_path)
early_stream = early.makefile("rb")
protocol.read_hello(early_stream)
assert protocol.read_frame(early_stream)
time.sleep(0.3) # let a pile of frames go by
late = connect(sock_path)
late_stream = late.makefile("rb")
assert protocol.read_hello(late_stream)["width"] == 1280
assert protocol.read_frame(late_stream) # not made to wait for a backlog
early.close()
late.close()
def test_a_stalled_client_does_not_stall_the_others(sock_path, stub_capture, run_bg, connect):
# docs/CONTRACT.md: "A client that stalls or reads slowly is *slowed*, not
# queued" -- observably, it must not hold up anybody else.
run_bg(FrameServer(sock_path, stub_capture(), fps=30).serve_forever)
wait_for_socket(sock_path)
def test_a_stalled_client_does_not_block_another(sock_path, serve):
"""Contract: a stalled client is slowed, not queued -- and it is alone."""
big = png_bytes(1024, 1024, (1, 2, 3), level=0) # ~3 MiB, fills any buffer
assert len(big) > 2 << 20
with serve(sock_path, FakeCapture(frames=[big]), fps=20):
stalled = connect(sock_path, rcvbuf=2048)
assert read_hello(stalled)["width"] == 1280
# ...and now `stalled` reads nothing at all, so the server's write to it
# blocks part-way through a frame.
time.sleep(0.5)
stalled = connect(sock_path) # connects and never reads
with read_stream(connect(sock_path)) as stream:
started = time.monotonic()
healthy = connect(sock_path)
stream = healthy.makefile("rb")
assert protocol.read_hello(stream)["width"] == 1280
assert len(protocol.read_frame(stream)) == len(big)
assert len(protocol.read_frame(stream)) == len(big)
assert time.monotonic() - started < HELLO_WAIT, "the stall spread"
healthy.close()
stalled.close()
def test_frames_are_dropped_for_a_slow_client_not_queued(sock_path, serve):
frames = distinct_frames(400)
index_of = {payload: i for i, payload in enumerate(frames, start=1)}
capture = FakeCapture(frames=frames)
with serve(sock_path, capture, fps=100) as server:
conn = connect(sock_path)
stream = conn.makefile("rb")
protocol.read_hello(stream)
seen = []
for _ in range(3):
time.sleep(0.2) # far slower than 100 fps
seen.append(index_of[protocol.read_frame(stream)])
conn.close()
assert server.frames_captured > len(seen) + 2, "capture did not outrun the client"
assert seen == sorted(seen)
assert seen[-1] > len(seen), f"frames were queued, not dropped: {seen}"
def test_server_survives_a_client_dying_mid_frame(sock_path, serve):
big = png_bytes(1024, 1024, (9, 9, 9), level=0)
with serve(sock_path, FakeCapture(frames=[big]), fps=20) as server:
doomed = connect(sock_path, rcvbuf=2048)
stream = doomed.makefile("rb")
assert protocol.read_hello(stream)["width"] == 1280
assert len(stream.read(4096)) == 4096 # a fragment of the first frame
abort(doomed) # torn down mid-frame, with an RST
survivor = connect(sock_path)
survivor_stream = survivor.makefile("rb")
assert protocol.read_hello(survivor_stream)["width"] == 1280
assert len(protocol.read_frame(survivor_stream)) == len(big)
survivor.close()
assert server.ready.is_set()
def test_server_survives_many_clients_connecting_and_vanishing(sock_path, serve):
with serve(sock_path, FakeCapture(frames=distinct_frames(10)), fps=50):
for _ in range(25):
conn = connect(sock_path)
protocol.read_hello(conn.makefile("rb"))
abort(conn)
survivor = connect(sock_path)
stream = survivor.makefile("rb")
assert protocol.read_hello(stream)["width"] == 1280
assert protocol.read_frame(stream)
survivor.close()
def test_bytes_sent_by_a_client_are_read_and_ignored(sock_path, serve):
with serve(sock_path, FakeCapture(frames=distinct_frames(10)), fps=30):
conn = connect(sock_path)
conn.sendall(b"v2 control channel?\n" * 500)
stream = conn.makefile("rb")
assert protocol.read_hello(stream)["magic"] == "HHS1"
for _ in range(5):
assert len(protocol.read_frame(stream)) > 0
stalled.close()
assert protocol.read_frame(stream)
conn.sendall(b"more chatter")
assert protocol.read_frame(stream)
conn.close()
def test_bytes_sent_by_a_client_are_read_and_ignored(sock_path, stub_capture, run_bg, connect):
# docs/CONTRACT.md -> "Client -> server direction": reserved in v1.
box = run_bg(FrameServer(sock_path, stub_capture(), fps=30).serve_forever)
wait_for_socket(sock_path)
sock = connect(sock_path)
sock.sendall(b"a future control channel says hello\n" * 64)
with read_stream(sock) as stream:
assert protocol.read_hello(stream)["magic"] == "HHS1"
assert len(protocol.read_frame(stream)) > 0
assert not box, f"server thread died: {box}"
def test_a_failing_capture_does_not_kill_the_server(sock_path, stub_capture, run_bg, connect):
# docs/CONTRACT.md -> Failure semantics: "the server keeps the socket up and
# retries; it does not exit and it does not send partial frames."
cap = stub_capture(raise_first=3)
box = run_bg(FrameServer(sock_path, cap, fps=30).serve_forever)
wait_for_socket(sock_path)
with read_stream(connect(sock_path)) as stream:
assert protocol.read_hello(stream)["magic"] == "HHS1"
payload = protocol.read_frame(stream)
assert payload and payload.startswith(b"\x89PNG"), "no partial frame was sent"
assert cap.grabs > 3, "the server never retried after the capture failed"
assert not box, f"server thread died: {box}"
def test_never_announces_a_zero_size_hello(sock_path, stub_capture, run_bg, connect):
# docs/CONTRACT.md -> Failure semantics: "It never sends a Hello with zero
# size." The size only becomes known after the first successful capture.
cap = stub_capture(size=(0, 0))
cap_sizes = [(0, 0), (0, 0), (1280, 720)]
calls = {"n": 0}
def size():
n = calls["n"]
calls["n"] = min(n + 1, len(cap_sizes) - 1)
return cap_sizes[n]
cap.size = size
run_bg(FrameServer(sock_path, cap, fps=30).serve_forever)
wait_for_socket(sock_path)
with read_stream(connect(sock_path)) as stream:
hello = protocol.read_hello(stream)
assert hello["width"] > 0 and hello["height"] > 0
def test_build_parser_exposes_the_options_the_module_needs():
from hhstream import server
parser = server.build_parser()
args = parser.parse_args(
["--socket", "/run/x.sock", "--fps", "24", "--format", "png", "--", "grim", "-t", "png", "-"]
def test_capture_failure_keeps_the_server_up_and_holds_the_hello(sock_path, serve,
workdir):
"""Contract: no compositor -> keep the socket up, retry, send no Hello yet."""
gate = workdir / "gate"
capture = CommandCapture(
[*FAKE_CAPTURE, "--gate", str(gate), "--width", "800", "--height", "600"],
timeout=10,
)
assert args.socket == "/run/x.sock"
assert args.fps == 24
with serve(sock_path, capture, fps=20) as server:
waiting = connect(sock_path, timeout=1.0)
with pytest.raises(TimeoutError):
protocol.read_hello(waiting.makefile("rb"))
assert server.capture_failures > 0
assert server.frames_captured == 0
waiting.close()
gate.write_text("the compositor is up now\n")
recovered = connect(sock_path)
stream = recovered.makefile("rb")
hello = protocol.read_hello(stream)
assert (hello["width"], hello["height"]) == (800, 600)
assert protocol.read_frame(stream).startswith(b"\x89PNG\r\n\x1a\n")
recovered.close()
assert server.frames_captured > 0
def test_main_rejects_an_unknown_flag():
from hhstream import server
def test_capture_failing_in_the_middle_does_not_break_the_stream(sock_path, serve):
capture = FakeCapture(frames=distinct_frames(10))
with serve(sock_path, capture, fps=50) as server:
conn = connect(sock_path)
stream = conn.makefile("rb")
protocol.read_hello(stream)
assert protocol.read_frame(stream)
capture.fail_until = capture.calls + 20 # a burst of failures
time.sleep(0.3)
assert server.capture_failures >= 1
assert protocol.read_frame(stream) # recovers without a reconnect
conn.close()
with pytest.raises(SystemExit):
server.main(["--definitely-not-a-flag"])
def test_a_stale_socket_file_does_not_prevent_startup(sock_path, serve):
stale = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
stale.bind(sock_path)
stale.close()
assert stat.S_ISSOCK(os.lstat(sock_path).st_mode)
with serve(sock_path, FakeCapture(), fps=20):
conn = connect(sock_path)
assert protocol.read_hello(conn.makefile("rb"))["magic"] == "HHS1"
conn.close()
def test_the_socket_is_mode_0660(sock_path, serve):
with serve(sock_path, FakeCapture(), fps=20):
assert stat.S_IMODE(os.stat(sock_path).st_mode) == 0o660
def test_a_non_socket_file_in_the_way_is_never_deleted(workdir):
precious = workdir / "precious"
precious.write_text("someone else's data")
server = FrameServer(str(precious), FakeCapture(), 20)
with pytest.raises(OSError):
server.serve_forever()
assert precious.read_text() == "someone else's data"
def test_the_socket_path_is_created_and_removed_around_the_run(workdir, serve):
path = workdir / "nested" / "dir" / "s.sock"
with serve(str(path), FakeCapture(), fps=20):
assert path.is_socket()
assert not path.exists(), "the socket file outlived the server"
def test_stop_releases_the_client_threads(sock_path, serve):
with serve(sock_path, FakeCapture(frames=distinct_frames(5)), fps=30) as server:
conn = connect(sock_path)
stream = conn.makefile("rb")
protocol.read_hello(stream)
assert protocol.read_frame(stream)
server.stop()
deadline = time.monotonic() + 5
while time.monotonic() < deadline:
if not any(t.name.startswith("hhstream-client") and t.is_alive()
for t in threading.enumerate()):
break
time.sleep(0.05)
else:
pytest.fail("a client thread outlived stop()")
conn.close()
def test_stopping_twice_does_not_delete_a_restarts_socket(sock_path, serve):
"""A second stop() after a restart must not take the new server's socket."""
first = FrameServer(sock_path, FakeCapture(), 20)
thread = threading.Thread(target=first.serve_forever, daemon=True)
thread.start()
assert first.ready.wait(5)
first.stop()
thread.join(5)
assert not os.path.exists(sock_path)
with serve(sock_path, FakeCapture(), fps=20): # the "restart"
first.stop() # a late, duplicate stop from the old instance
assert os.path.exists(sock_path), "the restart's socket was removed"
conn = connect(sock_path)
assert protocol.read_hello(conn.makefile("rb"))["magic"] == "HHS1"
conn.close()