Compare commits

..
Author SHA1 Message Date
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
24 changed files with 1670 additions and 1995 deletions

No files matched your search

-241
View File
@@ -1,241 +0,0 @@
# Developing and testing `hyprland-headless-stream-plugin`
The interface everything here asserts is [`docs/CONTRACT.md`](docs/CONTRACT.md).
That document is authoritative: if a test and the code disagree, the document
decides, and if the document is wrong it gets a version bump, not an edit.
## Prerequisites
- Nix with flakes enabled.
- `/dev/kvm` readable, for the two VM checks. They are `nixosTest`s; without
KVM they still run, just slowly enough that the timeouts below get tight.
- No GPU. Nothing in the test suite needs one — the compositor runs on
Hyprland's headless backend over software rendering.
Nothing in the checks touches the host: no `/etc/nixos`, no network, and no
socket outside the build sandbox or the test VM.
## The dev shell
```bash
nix develop
```
Puts `python3`, `pytest`, `hyprland`, `grim`, `ffmpeg`, `jq` and `tmux` on PATH
and sets `PYTHONPATH=$PWD/src`, so `import hhstream` picks up the working tree
rather than an installed copy.
## Build
```bash
nix build .#hhstream # the package (server + client)
ls result/bin # hhstream-server, hhstream-client
```
Both entry points currently exit with `NotImplementedError` — see "Known gaps"
at the bottom. The package builds; it does not yet run.
## The checks
| Check | What it proves | Needs a VM |
|---|---|---|
| `unit` | the framing, the capture backend, the server's client handling, the client — in-process, against the `nix/package.nix` build | no |
| `vm-basic` | the NixOS module brings up both units and publishes a contract-conformant socket, with a **fake** capture backend | yes |
| `vm-hyprland` | the same, capturing the **real** headless compositor through `grim` | yes |
All three at once:
```bash
nix flake check -L
```
`nix flake check` stops at the first failing check, which makes it a poor way to
see the whole picture while the tree is still red. Prefer running them
individually — they are independent:
```bash
nix build -L .#checks.x86_64-linux.unit
nix build -L .#checks.x86_64-linux.vm-basic
nix build -L .#checks.x86_64-linux.vm-hyprland
```
`-L` is not optional in practice: without it, Nix hides the build log, and the
build log *is* the test report.
### `unit`
pytest over `tests/unit/`, run in the build sandbox with `PYTHONPATH` pointing at
what `nix/package.nix` installed (`nix/package.nix` sets `doCheck = false` on
purpose, so this is the only place the suite runs in a build).
The check fails if the suite is **empty**, not just if it is red. `pytest` exits
5 on "collected nothing", but it exits 0 when every test was skipped or
deselected, so `checks/lib/check_report.py` parses the JUnit report and refuses
a run with zero collected or zero executed tests. A green check that tested
nothing is worse than no check. On success the report is copied to
`result/junit.xml`.
To run the same tests directly, without Nix:
```bash
nix develop
pytest tests/unit -v # PYTHONPATH=$PWD/src comes from the shell
pytest tests/unit/test_protocol.py -v # one file
pytest tests/unit -k "hello or frame" -v # one theme
pytest tests/unit -x --ff # stop at the first failure, failures first
```
Note that the unit suite's *negative* tests use the `rejects` fixture from
`tests/unit/conftest.py` rather than `pytest.raises(Exception)`. `rejects`
treats `NotImplementedError` as a failure, because a plain `raises(Exception)`
is satisfied by an unimplemented stub — the test would then be green precisely
because nothing had been written.
### `vm-basic`
Boots one machine with `services.hyprland-headless-stream.enable = true` and
`captureCommand` pointed at `tests/fake_capture.py`, which writes one fixed,
deterministic PNG of the configured size to stdout. Because the image never
changes, "two frames arrived and they are the *same bytes*" is a real assertion
about the framing rather than a coincidence.
It checks, in order: both units start; the socket exists and is
`hhstream:hhstream` mode `0660`; the Hello parses with `magic = "HHS1"` and
non-zero width/height matching the configured output; two frames arrive with
length > 0, identical bytes, and an IHDR matching the Hello; two clients are
served concurrently; and a client that dies mid-frame leaves the server serving.
The reader is `tests/assert_stream.py`, a second, independent implementation of
the contract that shares no code with `hhstream.client` — so a framing bug
present in both the server's writer and the shipped client's reader still fails
the test. It validates the length prefix strictly (`0|[1-9][0-9]*`: no leading
zeros, no sign, no spaces), never reads past a newline, and prints the Hello,
every frame's size and SHA-256, and the parsed IHDR before it decides anything.
### `vm-hyprland`
The same machine with **no** `captureCommand` override, so the module's default
(`grim`) captures the real compositor.
This is the check expected to be flaky, so it is deliberately impatient: every
wait has a bounded timeout, nothing is retried in a loop, and any failure dumps
diagnostics before it propagates. It asserts a frame is a valid PNG whose IHDR
dimensions match the configured output, and that it is more than a blank buffer:
- the IDAT must decompress;
- the decompressed scanlines must contain a non-zero byte and at least two
distinct byte values — a zero-filled framebuffer fails both;
- the payload must be larger than a best-case blank PNG of the same geometry
(`blank_png_size()` in `tests/assert_stream.py`: an all-zero raster at zlib
level 9, i.e. the smallest a blank frame of that size can be encoded).
It also runs `grim` directly against the session as a separate subtest, which
separates "grim cannot see the compositor" from "the server is wrong" — the two
failures that look identical from the socket.
## When `vm-hyprland` fails: where the logs are
Every failing subtest in both VM checks runs `hhs-hyprland-diagnostics`
(`tests/hyprland_diagnostics.sh`) in the guest first and prints its output to the
build log. So the answer to "where are the logs" is usually **in the build log
you already have**, above the traceback, between
`########## diagnostics: ... ##########` markers. Re-read it with:
```bash
nix log .#checks.x86_64-linux.vm-hyprland
```
What the dump contains, and where it comes from in the guest:
| Section | Source |
|---|---|
| `units` | `systemctl list-units --all 'hyprland*'` |
| per-unit `status` / `journalctl` | `hyprland-headless.service` and `hyprland-headless-stream.service`, 200 lines each |
| `socket and runtime directories` | `/run/hyprland-headless-stream`, `/run/user/*` |
| `hyprland logs` | every `hyprland*.log` found under `/run`, `/var/log`, `/tmp`, `/home` |
| `hyprctl monitors` | run once per instance found, with the right `XDG_RUNTIME_DIR` and `HYPRLAND_INSTANCE_SIGNATURE` |
| `processes` | `ps aux` filtered to `hypr`, `hhstream`, `grim` |
Hyprland writes its log to
`$XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log`, and the
compositor runs on a *private* `XDG_RUNTIME_DIR`, so the path is not knowable in
advance — that is why the script searches for it rather than naming it. The
instance signature is the directory name under `<runtime>/hypr`, which is also
what `hyprctl` needs in the environment:
```bash
XDG_RUNTIME_DIR=/run/user/$(id -u hhstream) \
HYPRLAND_INSTANCE_SIGNATURE=$(ls /run/user/$(id -u hhstream)/hypr | head -1) \
hyprctl monitors
```
### Poking at a live VM
The nicest way to debug a VM failure is to keep the machine:
```bash
nix build .#checks.x86_64-linux.vm-hyprland.driverInteractive
./result/bin/nixos-test-driver
```
That drops you in a Python REPL with `machine` bound. `start_all()`, then
`machine.shell_interact()` for a root shell in the guest, or run the test script
a line at a time. `machine.succeed("hhs-hyprland-diagnostics")` works there too.
## Layout
```
checks/
default.nix wiring only: the three checks the flake exposes
unit.nix pytest in the sandbox, against the nix/package.nix build
vm-basic.nix nixosTest, fake capture backend
vm-hyprland.nix nixosTest, real compositor + grim
lib/test-tools.nix packages the tests/ helpers for the guest
lib/check_report.py JUnit report -> build verdict (and the empty-suite guard)
tests/
fake_capture.py writes one fixed PNG to stdout: hhs-fake-capture
assert_stream.py independent contract reader/asserter: hhs-assert-stream
hyprland_diagnostics.sh the failure dump: hhs-hyprland-diagnostics
unit/ the pytest suite
```
`checks/lib/test-tools.nix` self-tests the two Python helpers at build time
(the fake emits a PNG of the size it was asked for; the asserter starts), because
a broken helper otherwise surfaces as a baffling failure three layers away.
Adding a unit test: drop a `test_*.py` in `tests/unit/`. Nothing needs
registering. Adding a check: one file in `checks/`, one line in
`checks/default.nix`.
## Known gaps in the interface (as of this branch)
These are defects in code this branch does not own; they are recorded here
because the tests are written against the contract and therefore trip over them.
1. **`nix/module.nix` has no `config` side yet.** Neither
`hyprland-headless.service` nor `hyprland-headless-stream.service` exists, so
both VM checks fail at their first wait with
`Unit hyprland-headless.service could not be found.` Nothing in `checks/`
works around this.
2. **`services.hyprland-headless-stream.package` is declared with no default.**
`docs/CONTRACT.md` says the default is "the flake's own build", but the option
has no `default`, so reading it fails with
```
error: The option `services.hyprland-headless-stream.package' was accessed but
has no value defined. Try setting the option.
```
Today that only bites code that reads `cfg.package`, which the unwritten
`config` side does not yet do; it will bite every consumer that sets only
`enable = true` the moment it does. Both VM checks set `package` explicitly.
3. **`src/hhstream/*.py` is stubs.** Every function raises
`NotImplementedError`, so 66 of the 70 unit tests fail. The 4 that pass are
`tests/unit/test_package.py`, which only reads constants — they are the
canary for the `unit` check's own wiring.
4. **The frame server's command line is unspecified.** `docs/CONTRACT.md` fixes
the module's option surface and the wire format but never says how the module
invokes `hhstream-server`. `tests/unit/test_server.py::test_build_parser_exposes_the_options_the_module_needs`
currently assumes `--socket PATH --fps N --format png -- <captureCommand...>`.
That is a guess; if the module ends up passing something else, that one test
is the thing to change, not the server.
-28
View File
@@ -1,28 +0,0 @@
# The flake's `checks` output. One file per check; this is only the wiring.
#
# unit -- pytest over tests/unit/, against the nix/package.nix build
# vm-basic -- nixosTest with a fake capture backend: module + wire contract
# vm-hyprland -- nixosTest with the real compositor and grim
#
# Everything the guests need lives in checks/lib/test-tools.nix.
{
pkgs,
self,
system,
}:
let
hhstream = self.packages.${system}.hhstream;
hhsModule = self.nixosModules.default;
testTools = pkgs.callPackage ./lib/test-tools.nix { };
in
{
unit = pkgs.callPackage ./unit.nix { inherit hhstream; };
vm-basic = pkgs.callPackage ./vm-basic.nix {
inherit hhstream hhsModule testTools;
};
vm-hyprland = pkgs.callPackage ./vm-hyprland.nix {
inherit hhstream hhsModule testTools;
};
}
-90
View File
@@ -1,90 +0,0 @@
#!/usr/bin/env python3
"""Turn a pytest JUnit report into a build verdict.
Two jobs pytest's exit code alone does not do well inside a Nix build:
* say out loud how many tests ran, and which ones failed, in the build log;
* refuse a suite that collected nothing. An empty suite exits 5, but it also
exits 0 if every test was deselected or skipped away, and a check that passes
because it tested nothing is worse than no check at all.
Exit codes: 0 all good, 1 the suite is empty or the report is unusable,
2 the suite ran and some tests failed. The caller distinguishes them so the
build log does not accuse an empty suite of being a failing one.
"""
from __future__ import annotations
import sys
import xml.etree.ElementTree as ET
def main(argv: list[str]) -> int:
if len(argv) != 2:
print("usage: check_report.py <junit.xml>", file=sys.stderr)
return 2
path = argv[1]
try:
root = ET.parse(path).getroot()
except FileNotFoundError:
print(
f"ERROR: pytest wrote no report at {path}: it collected nothing, or died "
"before it could run a single test.",
file=sys.stderr,
)
return 1
except ET.ParseError as exc:
print(f"ERROR: {path} is not parseable JUnit XML: {exc}", file=sys.stderr)
return 1
suites = root.findall("testsuite") or ([root] if root.tag == "testsuite" else [])
total = errors = failures = skipped = 0
failing: list[str] = []
for suite in suites:
total += int(suite.get("tests", 0))
errors += int(suite.get("errors", 0))
failures += int(suite.get("failures", 0))
skipped += int(suite.get("skipped", 0))
for case in suite.iter("testcase"):
for kind in ("failure", "error"):
for node in case.findall(kind):
name = f"{case.get('classname', '')}::{case.get('name', '')}"
message = (node.get("message") or "").splitlines()
head = message[0][:160] if message else node.get("type", kind)
failing.append(f" {kind.upper():7} {name}\n {head}")
executed = total - skipped
print(
f"unit suite: {total} collected, {executed} executed, "
f"{failures} failed, {errors} errored, {skipped} skipped"
)
if total == 0:
print(
"ERROR: the unit suite collected no tests. An empty suite is not a "
"passing suite -- check that tests/unit/ is in the build and that the "
"files are named test_*.py.",
file=sys.stderr,
)
return 1
if executed == 0:
print(
f"ERROR: all {total} collected tests were skipped; nothing was actually "
"exercised.",
file=sys.stderr,
)
return 1
if failing:
print(f"\n{len(failing)} failing test(s):")
for line in failing:
print(line)
return 2
print("unit suite: all executed tests passed")
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv))
-32
View File
@@ -1,32 +0,0 @@
# The helper programs the checks need inside the guest (and, for the fake
# capture, inside the guest's `captureCommand`). Plain python3/sh scripts from
# `tests/`, put on PATH with their shebangs pointing at the store.
{
runCommandLocal,
python3,
coreutils,
gnugrep,
findutils,
systemd,
}:
runCommandLocal "hhstream-test-tools"
{
nativeBuildInputs = [ python3 ];
# hhs-hyprland-diagnostics runs on a failing guest, where PATH is whatever
# systemd left behind; give it the tools it needs explicitly.
diagPath = "${coreutils}/bin:${gnugrep}/bin:${findutils}/bin:${systemd}/bin";
meta.description = "Fake capture backend and contract asserter for the hhstream checks";
} ''
install -Dm755 ${../../tests/fake_capture.py} $out/bin/hhs-fake-capture
install -Dm755 ${../../tests/assert_stream.py} $out/bin/hhs-assert-stream
install -Dm755 ${../../tests/hyprland_diagnostics.sh} $out/bin/hhs-hyprland-diagnostics
patchShebangs $out/bin
substituteInPlace $out/bin/hhs-hyprland-diagnostics --replace-fail '@diagPath@' "$diagPath"
# A broken helper shows up as a baffling test failure three layers away, so
# prove here that both python programs start and produce what they promise.
$out/bin/hhs-fake-capture --width 8 --height 4 > frame.png
python3 -c 'import struct,sys; d=open("frame.png","rb").read(); assert d[:8]==b"\x89PNG\r\n\x1a\n", d[:8]; assert struct.unpack(">II", d[16:24])==(8,4), d[16:24]'
$out/bin/hhs-assert-stream --help > /dev/null
$out/bin/hhs-hyprland-diagnostics --self-test > /dev/null
''
-74
View File
@@ -1,74 +0,0 @@
# checks.<system>.unit -- the Python unit suite from tests/unit/, run against the
# package built by nix/package.nix, inside the build sandbox.
#
# nix/package.nix sets doCheck = false deliberately, so this is the only place
# the suite runs in a build.
{
lib,
runCommand,
python3,
hhstream,
}:
let
pytestEnv = python3.withPackages (ps: [ ps.pytest ]);
# Only the suite itself, so an editor's droppings or a local .pytest_cache
# cannot change the derivation's hash.
testSrc = lib.cleanSourceWith {
name = "hhstream-unit-tests";
src = ../tests/unit;
filter =
path: type:
let
base = baseNameOf (toString path);
in
!(type == "directory" && (base == "__pycache__" || base == ".pytest_cache"))
&& !lib.hasSuffix ".pyc" base;
};
in
runCommand "hhstream-unit"
{
nativeBuildInputs = [ pytestEnv ];
passthru.testSrc = testSrc;
meta.description = "hhstream unit tests (pytest)";
} ''
cp -r ${testSrc} suite
chmod -R u+w suite
# The package is an application, so its library is not on the default path:
# point PYTHONPATH at what nix/package.nix installed. Importing it here rather
# than letting pytest do it makes a packaging problem distinguishable from a
# test failure.
export PYTHONPATH=${hhstream}/${python3.sitePackages}
export PYTHONDONTWRITEBYTECODE=1
export HOME=$PWD
python3 -c 'import hhstream; print("testing hhstream", hhstream.__version__, "from", hhstream.__file__)'
set +e
pytest suite \
--color=no -rf -q \
--junit-xml=report.xml \
-p no:cacheprovider \
--strict-markers \
--strict-config
pytest_rc=$?
set -e
echo
set +e
python3 ${./lib/check_report.py} report.xml
report_rc=$?
set -e
if [ "$report_rc" -eq 1 ]; then
echo "unit check: the suite is empty or its report is unusable -- failing." >&2
exit 1
fi
if [ "$report_rc" -ne 0 ] || [ "$pytest_rc" -ne 0 ]; then
echo "unit check: the suite ran but did not pass (pytest exit $pytest_rc)." >&2
exit 1
fi
mkdir -p $out
cp report.xml $out/junit.xml
''
-145
View File
@@ -1,145 +0,0 @@
# checks.<system>.vm-basic -- boot a real machine with the module enabled, point
# `captureCommand` at a fake capture program, and read the socket.
#
# This check is about the module's wiring and the wire contract, not about
# Hyprland: the fake capture emits one fixed PNG, so "two frames arrived and
# they are the same image" is a real assertion rather than a coincidence.
{
testers,
hhstream,
testTools,
hhsModule,
width ? 1280,
height ? 720,
fps ? 30,
socketPath ? "/run/hyprland-headless-stream/stream.sock",
}:
testers.runNixOSTest {
name = "hhstream-vm-basic";
# KVM is available, so this is a minute or two; cap it so a hang is a failure
# rather than a wedged builder.
globalTimeout = 900;
nodes.machine = {
imports = [ hhsModule ];
services.hyprland-headless-stream = {
enable = true;
# The module declares `package` with no default (see README.dev.md), so the
# test has to supply the flake's build.
package = hhstream;
inherit socketPath;
frameRate = fps;
format = "png";
outputs = [
{
name = "HEADLESS-1";
inherit width height;
refresh = fps;
}
];
captureCommand = [
"${testTools}/bin/hhs-fake-capture"
"--width"
(toString width)
"--height"
(toString height)
];
};
environment.systemPackages = [
testTools
hhstream
];
virtualisation = {
memorySize = 1024;
cores = 2;
diskSize = 3072;
graphics = false;
};
};
testScript = ''
SOCKET = "${socketPath}"
ASSERT = "hhs-assert-stream --socket " + SOCKET
def dump(label):
print(f"########## diagnostics: {label} ##########")
print(machine.execute("hhs-hyprland-diagnostics")[1])
start_all()
with subtest("the module's two units come up"):
try:
machine.wait_for_unit("hyprland-headless.service", timeout=120)
machine.wait_for_unit("hyprland-headless-stream.service", timeout=120)
except Exception:
dump("units did not start")
raise
with subtest("the socket exists, owned by the service user, mode 0660"):
try:
machine.wait_for_file(SOCKET, timeout=60)
print(machine.succeed(f"stat -c 'owner=%U group=%G mode=%a type=%F' {SOCKET}"))
machine.succeed(f"[ \"$(stat -c %a {SOCKET})\" = 660 ]")
machine.succeed(f"[ \"$(stat -c %U {SOCKET})\" = hhstream ]")
machine.succeed(f"[ \"$(stat -c %G {SOCKET})\" = hhstream ]")
machine.succeed(f"[ \"$(stat -c %F {SOCKET})\" = socket ]")
except Exception:
dump("socket missing or wrong ownership")
raise
with subtest("the Hello parses, magic is HHS1, size is non-zero"):
try:
print(machine.succeed(f"{ASSERT} --frames 1 --timeout 30"))
except Exception:
dump("Hello did not parse")
raise
with subtest("two frames arrive, non-empty, byte-identical, matching the Hello"):
try:
print(
machine.succeed(
f"{ASSERT} --frames 2 --timeout 60"
" --expect-width ${toString width} --expect-height ${toString height}"
" --expect-format image/png --expect-fps ${toString fps}"
" --require-png --identical-frames --min-bytes 1"
)
)
except Exception:
dump("frames did not satisfy the contract")
raise
with subtest("two clients are served concurrently and independently"):
try:
print(
machine.succeed(
f"{ASSERT} --frames 3 --timeout 60 --require-png > /tmp/a.log 2>&1 & p1=$!; "
f"{ASSERT} --frames 3 --timeout 60 --require-png > /tmp/b.log 2>&1 & p2=$!; "
"wait $p1; r1=$?; wait $p2; r2=$?; "
"echo '--- client a ---'; cat /tmp/a.log; "
"echo '--- client b ---'; cat /tmp/b.log; "
"exit $((r1 + r2))"
)
)
except Exception:
dump("concurrent clients were not both served")
raise
with subtest("a client dying mid-stream leaves the server serving"):
try:
machine.succeed(
"timeout 5 python3 -c 'import socket;"
f"s=socket.socket(socket.AF_UNIX);s.connect(\"{SOCKET}\");s.recv(1);s.close()'"
)
print(machine.succeed(f"{ASSERT} --frames 2 --timeout 60 --require-png"))
machine.succeed("systemctl is-active hyprland-headless-stream.service")
except Exception:
dump("server did not survive a client dying mid-frame")
raise
'';
}
-157
View File
@@ -1,157 +0,0 @@
# checks.<system>.vm-hyprland -- the real one. Same machine as vm-basic, but no
# `captureCommand` override, so the server captures the actual headless
# compositor through grim.
#
# This is the check expected to be flaky, so it is deliberately impatient: every
# wait has a bounded timeout, nothing is retried in a loop, and any failure dumps
# the compositor's log and `hyprctl monitors` before it propagates. A flake you
# can read is worth more than a flake that eventually goes green.
{
testers,
hhstream,
testTools,
hhsModule,
hyprland,
grim,
width ? 1280,
height ? 720,
fps ? 30,
socketPath ? "/run/hyprland-headless-stream/stream.sock",
}:
testers.runNixOSTest {
name = "hhstream-vm-hyprland";
globalTimeout = 1800;
nodes.machine = {
imports = [ hhsModule ];
services.hyprland-headless-stream = {
enable = true;
package = hhstream;
hyprlandPackage = hyprland;
inherit socketPath;
frameRate = fps;
format = "png";
outputs = [
{
name = "HEADLESS-1";
inherit width height;
refresh = fps;
}
];
# No captureCommand: the module's default (grim) is the point of this check.
};
# hyprctl and grim are here for the diagnostics dump and for the manual
# cross-check below, not for the code path under test.
environment.systemPackages = [
testTools
hhstream
hyprland
grim
];
# 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.
virtualisation = {
memorySize = 2048;
cores = 2;
diskSize = 4096;
graphics = false;
};
};
testScript = ''
SOCKET = "${socketPath}"
WIDTH, HEIGHT = ${toString width}, ${toString height}
def dump(label):
print(f"########## diagnostics: {label} ##########")
status, out = machine.execute("hhs-hyprland-diagnostics", timeout=120)
print(out)
print(f"########## end diagnostics (exit {status}) ##########")
start_all()
with subtest("the compositor unit comes up"):
try:
machine.wait_for_unit("hyprland-headless.service", timeout=180)
except Exception:
dump("hyprland-headless.service did not start")
raise
with subtest("the compositor reports the configured headless output"):
try:
# Proves the compositor is really running a 1280x720 HEADLESS-1
# before we blame the capture for a wrong-sized frame.
out = machine.succeed("hhs-hyprland-diagnostics", timeout=120)
print(out)
assert "HEADLESS-1" in out, (
"hyprctl never reported a HEADLESS-1 monitor; see the dump above"
)
assert f"{WIDTH}x{HEIGHT}" in out, (
f"hyprctl never reported a {WIDTH}x{HEIGHT} mode; see the dump above"
)
except Exception:
dump("compositor output not as configured")
raise
with subtest("the frame server unit comes up and publishes the socket"):
try:
machine.wait_for_unit("hyprland-headless-stream.service", timeout=180)
machine.wait_for_file(SOCKET, timeout=120)
except Exception:
dump("frame server did not publish the socket")
raise
with subtest("grim can capture the session at all"):
# Separates "grim cannot see the compositor" from "the server is wrong",
# which are the two failures that look identical from the socket.
try:
print(
machine.succeed(
"systemd-run --pipe --wait --uid=hhstream"
" --setenv=XDG_RUNTIME_DIR=/run/user/$(id -u hhstream)"
" grim -t png /tmp/direct.png 2>&1 || true",
timeout=120,
)
)
print(machine.execute("stat -c '%s bytes' /tmp/direct.png")[1])
except Exception:
dump("direct grim capture failed")
raise
with subtest("a frame off the socket is a real PNG of the configured size"):
try:
print(
machine.succeed(
f"hhs-assert-stream --socket {SOCKET} --frames 1 --timeout 60"
f" --expect-width {WIDTH} --expect-height {HEIGHT}"
" --expect-format image/png --require-png --reject-blank",
timeout=180,
)
)
except Exception:
dump("frame off the socket failed the PNG assertions")
raise
with subtest("the stream keeps producing frames"):
try:
print(
machine.succeed(
f"hhs-assert-stream --socket {SOCKET} --frames 3 --timeout 60"
f" --expect-width {WIDTH} --expect-height {HEIGHT}"
" --require-png --reject-blank",
timeout=240,
)
)
machine.succeed("systemctl is-active hyprland-headless-stream.service")
except Exception:
dump("the stream stopped after the first frame")
raise
'';
}
+2 -8
View File
@@ -8,10 +8,6 @@
outputs = { self, nixpkgs, ... }: let outputs = { self, nixpkgs, ... }: let
systems = [ "x86_64-linux" "aarch64-linux" ]; systems = [ "x86_64-linux" "aarch64-linux" ];
forAllSystems = f: nixpkgs.lib.genAttrs systems (system: f (import nixpkgs { inherit system; })); forAllSystems = f: nixpkgs.lib.genAttrs systems (system: f (import nixpkgs { inherit system; }));
# `checks` needs the system name as well as the package set, to reach
# self.packages.<system>; forAllSystems only hands over pkgs.
forAllSystems' = f: nixpkgs.lib.genAttrs systems (system:
f { inherit system; pkgs = import nixpkgs { inherit system; }; });
in { in {
packages = forAllSystems (pkgs: rec { packages = forAllSystems (pkgs: rec {
hhstream = pkgs.callPackage ./nix/package.nix {}; hhstream = pkgs.callPackage ./nix/package.nix {};
@@ -23,10 +19,8 @@
default = hyprland-headless-stream; default = hyprland-headless-stream;
}; };
# Unit tests + the two VM integration tests. See checks/default.nix and # `checks` (unit tests + the VM integration test) is owned by the
# README.dev.md; the interface they assert is docs/CONTRACT.md. # test-harness workstream -- see docs/CONTRACT.md for the interface.
checks = forAllSystems' ({ pkgs, system }:
import ./checks { inherit pkgs self system; });
devShells = forAllSystems (pkgs: { devShells = forAllSystems (pkgs: {
default = pkgs.mkShell { default = pkgs.mkShell {
+140 -5
View File
@@ -7,9 +7,24 @@ produces frames in a unit test.
from __future__ import annotations from __future__ import annotations
import os
import struct
import subprocess import subprocess
from typing import Protocol 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): class CaptureBackend(Protocol):
def grab(self) -> bytes: def grab(self) -> bytes:
@@ -22,17 +37,137 @@ class CaptureBackend(Protocol):
class CommandCapture: 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, def __init__(self, argv: list[str], env: dict[str, str] | None = None,
timeout: float = 5.0) -> 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: 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]: 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 from __future__ import annotations
import argparse import argparse
import json
import pathlib
import socket
import sys
from typing import Iterable from typing import Iterable
from . import protocol
DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock" DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock"
def fetch(socket_path: str, count: int = 1, timeout: float = 10.0) -> list[bytes]: def fetch(socket_path: str, count: int = 1, timeout: float = 10.0) -> list[bytes]:
"""Connect and return up to `count` frame payloads (Hello consumed).""" """Connect and return up to `count` frame payloads (Hello consumed).
raise NotImplementedError
`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: 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: 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"]
+114 -5
View File
@@ -10,23 +10,77 @@ from typing import BinaryIO
from . import MAGIC 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: def hello(width: int, height: int, fmt: str, fps: int) -> bytes:
"""The one-line JSON Hello, `\\n`-terminated. """The one-line JSON Hello, `\\n`-terminated.
`fmt` is a MIME type ("image/png" / "image/jpeg"). `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: def parse_hello(line: bytes) -> dict:
"""Inverse of `hello`: validate `magic` and required fields, or raise.""" """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: def frame(payload: bytes) -> bytes:
"""`<ascii length>\\n<payload>` for one complete image.""" """`<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: 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 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. 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: def read_hello(stream: BinaryIO) -> dict:
"""Read and parse the Hello line from `stream`.""" """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))
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"] __all__ = ["json", "hello", "parse_hello", "frame", "read_frame", "read_hello", "MAGIC"]
+368 -4
View File
@@ -8,30 +8,394 @@ synchronously, and a slow write blocks only that client.
from __future__ import annotations from __future__ import annotations
import argparse import argparse
import errno
import logging
import os
import selectors
import signal
import socket import socket
import stat
import sys
import threading
import time
from typing import Iterable from typing import Iterable
from . import protocol
from .capture import CaptureBackend, CommandCapture from .capture import CaptureBackend, CommandCapture
DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock" 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: 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, def __init__(self, socket_path: str, capture: CaptureBackend, fps: int,
fmt: str = "image/png") -> None: 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: def serve_forever(self) -> None:
"""Bind, then serve until stopped. A stale socket file is replaced.""" """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: 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: 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", __all__ = ["FrameServer", "DEFAULT_SOCKET", "CaptureBackend", "CommandCapture",
-307
View File
@@ -1,307 +0,0 @@
#!/usr/bin/env python3
"""Read a hhstream socket and assert it obeys docs/CONTRACT.md.
This is deliberately a *second, independent* implementation of the reader: it
shares no code with `hhstream.client`, so a bug that lives in both the server's
writer and the shipped client's reader still fails the test. Pure standard
library; it runs inside the test VM, where only python3 is guaranteed.
Every run prints what it saw before it decides, so a failure in CI is readable
without reproducing it.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import re
import socket
import struct
import sys
import zlib
MAGIC = "HHS1"
FORMATS = {"image/png", "image/jpeg"}
PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
# Contract: plain ASCII digits, no leading zeros, no `+`, no spaces.
LENGTH_RE = re.compile(rb"\A(?:0|[1-9][0-9]*)\Z")
class ContractError(Exception):
"""The stream violated docs/CONTRACT.md."""
# --------------------------------------------------------------------------
# wire reading
# --------------------------------------------------------------------------
def read_line(sock: socket.socket, limit: int = 4096) -> bytes:
"""Read up to and including the next 0x0A. Never over-reads past it."""
out = bytearray()
while True:
b = sock.recv(1)
if not b:
raise ContractError(
f"socket closed after {len(out)} bytes while reading a line: {bytes(out)!r}"
)
if b == b"\n":
return bytes(out)
out += b
if len(out) > limit:
raise ContractError(f"no newline within {limit} bytes: {bytes(out[:120])!r}...")
def read_exact(sock: socket.socket, n: int) -> bytes:
out = bytearray()
while len(out) < n:
part = sock.recv(min(65536, n - len(out)))
if not part:
raise ContractError(
f"truncated payload: wanted {n} bytes, socket closed after {len(out)}"
)
out += part
return bytes(out)
def read_hello(sock: socket.socket) -> dict:
line = read_line(sock)
try:
obj = json.loads(line.decode("utf-8"))
except (UnicodeDecodeError, json.JSONDecodeError) as exc:
raise ContractError(f"Hello is not UTF-8 JSON ({exc}): {line!r}") from exc
if not isinstance(obj, dict):
raise ContractError(f"Hello is not a JSON object: {line!r}")
if obj.get("magic") != MAGIC:
raise ContractError(f"Hello magic is {obj.get('magic')!r}, contract says {MAGIC!r}")
for key in ("width", "height", "fps"):
val = obj.get(key)
if not isinstance(val, int) or isinstance(val, bool):
raise ContractError(f"Hello {key} is {val!r}, expected an integer")
if val <= 0:
raise ContractError(
f"Hello {key} is {val}; the contract forbids a Hello with zero size"
)
if obj.get("format") not in FORMATS:
raise ContractError(
f"Hello format is {obj.get('format')!r}, expected one of {sorted(FORMATS)}"
)
return obj
def read_frame(sock: socket.socket) -> bytes:
prefix = read_line(sock)
if not LENGTH_RE.match(prefix):
raise ContractError(
f"malformed length prefix {prefix!r}: contract requires plain ASCII "
"digits with no leading zeros, sign or spaces"
)
length = int(prefix)
if length == 0:
raise ContractError("frame length is 0; a frame must carry a complete image")
return read_exact(sock, length)
# --------------------------------------------------------------------------
# PNG inspection
# --------------------------------------------------------------------------
def png_chunks(data: bytes):
off = len(PNG_SIGNATURE)
while off + 8 <= len(data):
(size,) = struct.unpack(">I", data[off : off + 4])
kind = data[off + 4 : off + 8]
body = data[off + 8 : off + 8 + size]
if len(body) != size:
raise ContractError(f"PNG chunk {kind!r} truncated: want {size}, got {len(body)}")
crc = data[off + 8 + size : off + 12 + size]
if len(crc) != 4:
raise ContractError(f"PNG chunk {kind!r} has no CRC")
want = struct.pack(">I", zlib.crc32(kind + body) & 0xFFFFFFFF)
if crc != want:
raise ContractError(f"PNG chunk {kind!r} CRC mismatch: {crc.hex()} != {want.hex()}")
yield kind, body
off += 12 + size
if kind == b"IEND":
return
raise ContractError("PNG ended without an IEND chunk")
def inspect_png(payload: bytes) -> dict:
"""Parse enough of a PNG to know its size and whether it carries a picture."""
if not payload.startswith(PNG_SIGNATURE):
raise ContractError(
f"payload is not a PNG: first 8 bytes are {payload[:8]!r}, "
f"expected {PNG_SIGNATURE!r}"
)
ihdr = None
idat = bytearray()
for kind, body in png_chunks(payload):
if kind == b"IHDR":
if ihdr is not None:
raise ContractError("PNG has more than one IHDR")
if len(body) != 13:
raise ContractError(f"IHDR is {len(body)} bytes, expected 13")
w, h, depth, colour, comp, filt, interlace = struct.unpack(">IIBBBBB", body)
ihdr = dict(
width=w, height=h, bit_depth=depth, colour_type=colour,
compression=comp, filter=filt, interlace=interlace,
)
elif kind == b"IDAT":
if ihdr is None:
raise ContractError("PNG has IDAT before IHDR")
idat += body
if ihdr is None:
raise ContractError("PNG has no IHDR chunk")
if not idat:
raise ContractError("PNG has no IDAT chunk: there is no image data")
try:
raw = zlib.decompress(bytes(idat))
except zlib.error as exc:
raise ContractError(f"PNG image data does not decompress: {exc}") from exc
info = dict(ihdr)
info["payload_bytes"] = len(payload)
info["raw_bytes"] = len(raw)
info["distinct_raw_bytes"] = len(set(raw))
info["nonzero_raw_bytes"] = len(raw) - raw.count(0)
return info
def blank_png_size(width: int, height: int, colour_type: int, bit_depth: int) -> int:
"""Smallest plausible encoding of an all-zero image of the same geometry.
Used as the floor for "bigger than a trivial blank image": a zero-filled
framebuffer, packed with the best compression available, cannot exceed this.
"""
channels = {0: 1, 2: 3, 3: 1, 4: 2, 6: 4}.get(colour_type, 3)
stride = 1 + (width * channels * bit_depth + 7) // 8
raw = b"\x00" * (stride * height)
body = zlib.compress(raw, 9)
# signature + IHDR (25) + IDAT header/crc (12) + IEND (12)
return len(PNG_SIGNATURE) + 25 + 12 + len(body) + 12
# --------------------------------------------------------------------------
# driver
# --------------------------------------------------------------------------
def build_parser() -> argparse.ArgumentParser:
p = argparse.ArgumentParser(description=__doc__)
p.add_argument("--socket", required=True, help="path of the hhstream socket")
p.add_argument("--frames", type=int, default=1, help="how many frames to read")
p.add_argument("--timeout", type=float, default=30.0,
help="per-recv socket timeout, seconds")
p.add_argument("--expect-width", type=int, help="assert Hello/IHDR width")
p.add_argument("--expect-height", type=int, help="assert Hello/IHDR height")
p.add_argument("--expect-fps", type=int, help="assert Hello fps")
p.add_argument("--expect-format", help="assert Hello format, e.g. image/png")
p.add_argument("--min-bytes", type=int, default=1,
help="every payload must be at least this many bytes")
p.add_argument("--require-png", action="store_true",
help="every payload must parse as a PNG whose IHDR matches the Hello")
p.add_argument("--identical-frames", action="store_true",
help="all payloads read must be byte-identical")
p.add_argument("--reject-blank", action="store_true",
help="reject a frame that decodes to an all-zero or single-valued "
"image, or that is no bigger than a best-case blank PNG")
return p
def run(args) -> None:
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.settimeout(args.timeout)
sock.connect(args.socket)
try:
hello = read_hello(sock)
print(f"hello: {json.dumps(hello, sort_keys=True)}", flush=True)
for key, got in (("width", "expect_width"), ("height", "expect_height"),
("fps", "expect_fps"), ("format", "expect_format")):
want = getattr(args, got)
if want is not None and hello[key] != want:
raise ContractError(f"Hello {key} is {hello[key]!r}, expected {want!r}")
if args.require_png and hello["format"] != "image/png":
raise ContractError(
f"--require-png but Hello advertises format {hello['format']!r}"
)
payloads: list[bytes] = []
for i in range(args.frames):
payload = read_frame(sock)
digest = hashlib.sha256(payload).hexdigest()[:16]
print(f"frame {i}: {len(payload)} bytes sha256:{digest}", flush=True)
if len(payload) < args.min_bytes:
raise ContractError(
f"frame {i} is {len(payload)} bytes, below the {args.min_bytes}-byte floor"
)
payloads.append(payload)
if args.require_png:
info = inspect_png(payload)
print(f"frame {i}: png {json.dumps(info, sort_keys=True)}", flush=True)
if (info["width"], info["height"]) != (hello["width"], hello["height"]):
raise ContractError(
f"frame {i} IHDR is {info['width']}x{info['height']} but the Hello "
f"announced {hello['width']}x{hello['height']}"
)
if args.reject_blank:
floor = blank_png_size(
info["width"], info["height"], info["colour_type"], info["bit_depth"]
)
print(f"frame {i}: blank-png floor is {floor} bytes", flush=True)
if info["nonzero_raw_bytes"] == 0:
raise ContractError(
f"frame {i} decodes to {info['raw_bytes']} zero bytes: "
"this is a zero-filled buffer, not a captured frame"
)
if info["distinct_raw_bytes"] < 2:
raise ContractError(
f"frame {i} decodes to a single repeated byte value "
f"({info['raw_bytes']} bytes): a blank image, not a capture"
)
if len(payload) <= floor:
raise ContractError(
f"frame {i} is {len(payload)} bytes, no bigger than a "
f"best-case blank {info['width']}x{info['height']} PNG "
f"({floor} bytes)"
)
if args.identical_frames and len(payloads) > 1:
first = payloads[0]
for i, payload in enumerate(payloads[1:], start=1):
if payload != first:
raise ContractError(
f"frame {i} differs from frame 0 ({len(payload)} vs {len(first)} "
"bytes) but the fake capture emits one fixed image"
)
print(f"all {len(payloads)} frames byte-identical", flush=True)
finally:
sock.close()
def main(argv: list[str] | None = None) -> int:
args = build_parser().parse_args(argv)
if args.frames < 1:
print("assert-stream: --frames must be at least 1", file=sys.stderr)
return 2
try:
run(args)
except ContractError as exc:
print(f"CONTRACT VIOLATION: {exc}", file=sys.stderr)
return 1
except (OSError, socket.timeout) as exc:
print(f"SOCKET ERROR on {args.socket}: {exc!r}", file=sys.stderr)
return 1
print("OK", flush=True)
return 0
if __name__ == "__main__":
sys.exit(main())
-89
View File
@@ -1,89 +0,0 @@
#!/usr/bin/env python3
"""A fake capture backend: writes one deterministic PNG to stdout and exits.
Stands in for `grim` so `vm-basic` can exercise the socket, the Hello and the
framing without a compositor. Two properties matter to the test:
* the bytes are a *valid* PNG of exactly the requested size, so a server that
derives the Hello's width/height from the captured image agrees with a server
that derives them from the configured output;
* the bytes are *byte-identical* on every invocation, so the test can assert
that two frames off the wire are the same image rather than the same length.
Pure standard library (zlib + struct), because the test VM has nothing else.
"""
from __future__ import annotations
import argparse
import struct
import sys
import zlib
def chunk(kind: bytes, data: bytes) -> bytes:
return (
struct.pack(">I", len(data))
+ kind
+ data
+ struct.pack(">I", zlib.crc32(kind + data) & 0xFFFFFFFF)
)
def encode_png(width: int, height: int) -> bytes:
"""A solid frame with one deterministic marker rectangle in the corner.
The marker keeps the image from being uniform, which is what makes it a
believable stand-in for a real capture; being fixed keeps it reproducible.
"""
bg = (0x20, 0x30, 0x40)
fg = (0xE0, 0xC0, 0x10)
mark_w = min(64, width)
mark_h = min(32, height)
plain = b"\x00" + bytes(bg) * width
marked = b"\x00" + bytes(fg) * mark_w + bytes(bg) * (width - mark_w)
raw = marked * mark_h + plain * (height - mark_h)
ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0) # 8-bit truecolour
return (
b"\x89PNG\r\n\x1a\n"
+ chunk(b"IHDR", ihdr)
+ chunk(b"IDAT", zlib.compress(raw, 9))
+ chunk(b"IEND", b"")
)
def build_parser() -> argparse.ArgumentParser:
p = argparse.ArgumentParser(description=__doc__)
p.add_argument("--width", type=int, default=1280)
p.add_argument("--height", type=int, default=720)
# Accepted and ignored so the fake can be dropped in where a grim-shaped
# argv is expected (`-t png -`).
p.add_argument("-t", "--type", default="png")
p.add_argument("output", nargs="?", default="-")
return p
def main(argv: list[str] | None = None) -> int:
args = build_parser().parse_args(argv)
if args.type != "png":
print(f"fake-capture: only png is supported, got {args.type!r}", file=sys.stderr)
return 2
if args.width <= 0 or args.height <= 0:
print("fake-capture: width and height must be positive", file=sys.stderr)
return 2
data = encode_png(args.width, args.height)
out = sys.stdout.buffer if args.output == "-" else open(args.output, "wb")
try:
out.write(data)
out.flush()
finally:
if out is not sys.stdout.buffer:
out.close()
return 0
if __name__ == "__main__":
sys.exit(main())
-82
View File
@@ -1,82 +0,0 @@
#!/bin/sh
# Dump everything worth knowing when `vm-hyprland` fails.
#
# The compositor's own log is the thing you actually want and the thing that is
# hardest to find: Hyprland writes it under
# $XDG_RUNTIME_DIR/hypr/<instance-signature>/hyprland.log, and the service runs
# on a private XDG_RUNTIME_DIR. So rather than guess the path, look for it.
#
# Never fails: a diagnostics dump that exits non-zero hides the real error.
PATH="@diagPath@:$PATH"
export PATH
if [ "$1" = "--self-test" ]; then
echo "hhs-hyprland-diagnostics: ok"
exit 0
fi
SERVICE_UNIT=hyprland-headless-stream.service
COMPOSITOR_UNIT=hyprland-headless.service
say() { printf '\n----- %s -----\n' "$*"; }
run() { say "$*"; "$@" 2>&1 || echo "[exit $?]"; }
say "units"
systemctl --no-pager --plain list-units --all 'hyprland*' 2>&1 || true
for unit in "$COMPOSITOR_UNIT" "$SERVICE_UNIT"; do
run systemctl --no-pager --full status "$unit"
run journalctl --no-pager --boot --lines=200 --unit "$unit"
done
run systemctl --no-pager --full list-dependencies "$SERVICE_UNIT"
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]"
for d in /run/user/*; do
[ -d "$d" ] && ls -la "$d" 2>&1
done
say "hyprland logs"
# hyprland.log lives beside the compositor's IPC sockets; -xdev keeps this out
# of /nix/store and /proc.
found=0
for root in /run /var/log /tmp /home; do
[ -d "$root" ] || continue
for log in $(find "$root" -xdev -maxdepth 6 -name 'hyprland*.log' 2>/dev/null); do
found=1
say "tail -n 200 $log"
tail -n 200 "$log" 2>&1
done
done
[ "$found" = 1 ] || echo "[no hyprland*.log anywhere under /run /var/log /tmp /home]"
say "hyprctl monitors"
# Needs both XDG_RUNTIME_DIR and the instance signature, which is the directory
# name under <runtime>/hypr. Try every instance we can find.
tried=0
for hyprdir in /run/user/*/hypr/* /run/*/hypr/*; do
[ -d "$hyprdir" ] || continue
sig=$(basename "$hyprdir")
runtime=$(dirname "$(dirname "$hyprdir")")
owner=$(stat -c %U "$hyprdir" 2>/dev/null || echo root)
tried=1
say "hyprctl monitors (instance $sig, XDG_RUNTIME_DIR=$runtime, as $owner)"
if command -v hyprctl > /dev/null 2>&1; then
XDG_RUNTIME_DIR="$runtime" HYPRLAND_INSTANCE_SIGNATURE="$sig" \
hyprctl monitors 2>&1 || echo "[exit $?]"
XDG_RUNTIME_DIR="$runtime" HYPRLAND_INSTANCE_SIGNATURE="$sig" \
hyprctl version 2>&1 || echo "[exit $?]"
else
echo "[hyprctl not on PATH; add the hyprlandPackage to environment.systemPackages]"
fi
done
[ "$tried" = 1 ] || echo "[no hypr instance directory found: the compositor never came up]"
say "processes"
ps aux 2>&1 | grep -E 'hypr|hhstream|grim' | grep -v grep || echo "[no hyprland/hhstream/grim process]"
say "end of diagnostics"
exit 0
+36 -197
View File
@@ -1,220 +1,59 @@
"""Shared fixtures for the unit suite. """Shared fixtures. Nothing here touches a compositor, a GPU or the network."""
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.
"""
from __future__ import annotations from __future__ import annotations
import os import contextlib
import socket import pathlib
import struct import shutil
import sys import sys
import tempfile
import threading import threading
import zlib
import pytest import pytest
CONTRACT_SOCKET = "/run/hyprland-headless-stream/stream.sock" _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)
# AF_UNIX addresses are capped near 108 bytes; a long tmp_path would fail with a from hhstream.server import FrameServer # noqa: E402 (needs sys.path above)
# confusing OSError instead of the assertion the test is about.
SUN_PATH_MAX = 100
def make_png(width: int = 4, height: int = 3, value: int = 0x7F) -> bytes:
"""A minimal valid truecolour PNG, built with zlib+struct only."""
def chunk(kind: bytes, data: bytes) -> bytes:
return (
struct.pack(">I", len(data))
+ kind
+ data
+ struct.pack(">I", zlib.crc32(kind + data) & 0xFFFFFFFF)
)
raw = (b"\x00" + bytes([value, value ^ 0x20, value ^ 0x40]) * width) * height
return (
b"\x89PNG\r\n\x1a\n"
+ chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0))
+ chunk(b"IDAT", zlib.compress(raw, 9))
+ chunk(b"IEND", b"")
)
@pytest.fixture @pytest.fixture
def tiny_png() -> bytes: def workdir():
return make_png() """A short-lived directory with a short path (AF_UNIX paths are ~108 bytes)."""
path = tempfile.mkdtemp(prefix="hhs")
@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")
if len(path) > SUN_PATH_MAX:
pytest.skip(f"tmp_path too long for an AF_UNIX socket: {len(path)} bytes")
return path
@pytest.fixture
def emit_bytes():
"""Build an argv that writes exactly `data` to stdout and exits 0."""
def build(data: bytes) -> list[str]:
return [
sys.executable,
"-c",
"import sys;sys.stdout.buffer.write(bytes.fromhex(sys.argv[1]))",
data.hex(),
]
return build
@pytest.fixture
def python_argv():
"""Build an argv running an inline python program with extra arguments."""
def build(program: str, *args: str) -> list[str]:
return [sys.executable, "-c", program, *args]
return build
class StubCapture:
"""A capture backend under the test's control.
Satisfies `hhstream.capture.CaptureBackend` structurally: `grab()` and
`size()`. Counts calls so a test can tell whether the server actually
captured, and can be told to raise so failure semantics are observable.
"""
def __init__(self, frames=None, size=(1280, 720), raise_first: int = 0):
self._frames = list(frames) if frames is not None else [make_png()]
self._size = size
self._raise_first = raise_first
self.grabs = 0
self.lock = threading.Lock()
def grab(self) -> bytes:
with self.lock:
self.grabs += 1
n = self.grabs
if n <= self._raise_first:
raise RuntimeError(f"stub capture failing on purpose (call {n})")
return self._frames[(n - 1) % len(self._frames)]
def size(self) -> tuple[int, int]:
return self._size
@pytest.fixture
def stub_capture():
return StubCapture
@pytest.fixture
def connect():
"""Connect to an AF_UNIX socket, retrying until the server has bound it."""
opened: list[socket.socket] = []
def _connect(path: str, timeout: float = 10.0, deadline: float = 10.0) -> socket.socket:
import time
end = time.monotonic() + deadline
last: Exception | None = None
while time.monotonic() < end:
try: try:
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) yield pathlib.Path(path)
s.settimeout(timeout) finally:
s.connect(path) shutil.rmtree(path, ignore_errors=True)
opened.append(s)
return s
except OSError as exc:
last = exc
s.close()
time.sleep(0.05)
raise AssertionError(f"never connected to {path}: {last!r}")
yield _connect
for s in opened:
try:
s.close()
except OSError:
pass
@pytest.fixture @pytest.fixture
def run_bg(): def sock_path(workdir):
"""Run a callable on a daemon thread and surface the exception it raised. return str(workdir / "s.sock")
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.
"""
threads: list[tuple[threading.Thread, list]] = []
def _run(fn, *args, **kwargs) -> list:
box: list = []
def target():
try:
fn(*args, **kwargs)
except BaseException as exc: # recorded, re-raised by the test
box.append(exc)
t = threading.Thread(target=target, daemon=True)
t.start()
threads.append((t, box))
return box
yield _run
for t, box in threads:
t.join(timeout=0.5)
@pytest.fixture @pytest.fixture
def socket_mode(): def serve():
def _mode(path: str) -> int: """`with serve(path, capture, fps=...) as server:` -- bound and listening."""
return os.stat(path).st_mode & 0o7777 started: list[tuple[FrameServer, threading.Thread]] = []
return _mode
@pytest.fixture(scope="session")
def rejects():
"""`pytest.raises`, but a stub does not count as a rejection.
docs/CONTRACT.md says which inputs are invalid, not which exception type
signals it, so these tests cannot pin the type. A bare
`pytest.raises(Exception)` would then be satisfied by the unimplemented
stubs' own `NotImplementedError` -- a test that is green precisely because
nothing is written yet. This refuses that one exception explicitly.
"""
import contextlib
@contextlib.contextmanager @contextlib.contextmanager
def _rejects(*allowed: type[BaseException]): def _serve(path, capture, fps=20, fmt="image/png"):
expected = allowed or (Exception,) 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: try:
yield yield server
except NotImplementedError as exc: finally:
raise AssertionError( server.stop()
"the code under test raised NotImplementedError, so it did not " thread.join(5)
f"reject anything: {exc!r}"
) from exc
except expected:
return
except BaseException as exc:
raise AssertionError(
f"expected one of {[e.__name__ for e in expected]}, got {exc!r}"
) from exc
raise AssertionError(
f"expected one of {[e.__name__ for e in expected]}, nothing was raised"
)
return _rejects yield _serve
for server, thread in started:
server.stop()
thread.join(5)
+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. """The capture backend, driven by the fake capture command (no compositor)."""
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.
"""
from __future__ import annotations from __future__ import annotations
import struct import os
import subprocess
import sys 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]: def fake(*flags: str) -> list[str]:
w, h = struct.unpack(">II", data[16:24]) return [*FAKE_CAPTURE, *flags]
return w, h
def test_grab_returns_exactly_what_the_command_wrote(emit_bytes, tiny_png): def test_grab_returns_the_frame_and_size_comes_from_its_header():
cap = CommandCapture(emit_bytes(tiny_png)) capture = CommandCapture(fake("--width", "1280", "--height", "720"))
assert cap.grab() == tiny_png 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): def test_size_grabs_once_when_nothing_has_been_captured_yet():
payload = bytes(range(256)) + b"\n\r\x00\xff" capture = CommandCapture(fake("--width", "64", "--height", "32"))
assert CommandCapture(emit_bytes(payload)).grab() == payload assert capture.size() == (64, 32)
def test_grab_can_be_called_repeatedly(emit_bytes, tiny_png): def test_a_failing_command_raises_and_reports_its_stderr(capfd):
cap = CommandCapture(emit_bytes(tiny_png)) capture = CommandCapture(fake("--fail", "--message", "grim: no outputs"))
assert cap.grab() == cap.grab() == tiny_png 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): def test_empty_output_is_a_failure_not_an_empty_frame(capfd):
cap = CommandCapture(python_argv("import sys;sys.exit(3)")) with pytest.raises(CaptureError) as excinfo:
with rejects(): CommandCapture(fake("--empty")).grab()
cap.grab() assert "no output" in str(excinfo.value)
assert capfd.readouterr() == ("", "")
def test_grab_raises_when_the_command_does_not_exist(tmp_path, rejects): def test_a_hanging_command_times_out():
cap = CommandCapture([str(tmp_path / "definitely-not-a-program")]) capture = CommandCapture(fake("--delay", "10"), timeout=0.5)
with rejects(OSError): with pytest.raises(CaptureError) as excinfo:
cap.grab() capture.grab()
assert "timed out" in str(excinfo.value)
def test_grab_does_not_swallow_stderr_noise(python_argv, tiny_png): def test_a_missing_command_is_a_capture_error():
"""A capture tool that warns on stderr but succeeds still yields its frame.""" with pytest.raises(CaptureError) as excinfo:
cap = CommandCapture( CommandCapture(["hhstream-no-such-program"]).grab()
python_argv( assert "could not be run" in str(excinfo.value)
"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_env_is_handed_to_the_child(python_argv): def test_unmeasurable_output_cannot_produce_a_hello():
"""The compositor is reached through WAYLAND_DISPLAY/XDG_RUNTIME_DIR in env.""" capture = CommandCapture(fake("--garbage"))
cap = CommandCapture( assert capture.grab() == b"fake_capture: not an image, sorry\n"
python_argv("import os,sys;sys.stdout.write(os.environ['WAYLAND_DISPLAY'])"), with pytest.raises(CaptureError) as excinfo:
env={"WAYLAND_DISPLAY": "wayland-9", "PATH": "/nonexistent"}, capture.size()
) assert "pixel size" in str(excinfo.value)
assert cap.grab().strip() == b"wayland-9"
def test_timeout_is_enforced(python_argv, rejects): def test_a_failure_after_a_good_frame_keeps_the_known_size():
cap = CommandCapture(python_argv("import time;time.sleep(30)"), timeout=0.5) good = CommandCapture(fake("--width", "100", "--height", "50"))
with rejects(subprocess.TimeoutExpired, OSError): assert good.size() == (100, 50)
cap.grab() 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): def test_env_is_overlaid_on_our_own_environment():
frame = make_png(width=640, height=360) argv = [sys.executable, "-c",
cap = CommandCapture(emit_bytes(frame)) "import os,sys;sys.stdout.write(os.environ['WAYLAND_DISPLAY']+':'+"
assert cap.size() == png_size(cap.grab()) == (640, 360) "('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): def test_empty_argv_and_bad_timeout_are_rejected_up_front():
w, h = CommandCapture(emit_bytes(tiny_png)).size() with pytest.raises(ValueError):
assert isinstance(w, int) and isinstance(h, int) CommandCapture([])
assert w > 0 and h > 0, "the contract forbids a Hello with zero size" with pytest.raises(ValueError):
CommandCapture(["true"], timeout=0)
def test_size_never_reports_zero_for_a_real_frame(emit_bytes): def test_the_helpers_stdin_is_closed_so_it_cannot_steal_ours():
cap = CommandCapture(emit_bytes(make_png(width=1, height=1))) code = ("import sys;"
assert cap.size() == (1, 1) "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"
+104 -112
View File
@@ -1,155 +1,147 @@
"""`hhstream.client` read against a hand-written, contract-conformant server. """The client, against the real server and against a hand-written stub 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.
"""
from __future__ import annotations from __future__ import annotations
import contextlib
import json import json
import os
import socket import socket
import threading import threading
import pytest import pytest
from helpers import FakeCapture, connect, distinct_frames
from hhstream import client from hhstream import client, protocol
from conftest import make_png
class ContractServer: @contextlib.contextmanager
"""Writes the Hello and `frames` exactly as docs/CONTRACT.md specifies.""" 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, def run():
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: try:
conn, _ = self.sock.accept() conn, _ = listener.accept()
except OSError: except OSError:
return return
self.connections += 1 with conn:
threading.Thread(target=self._handle, args=(conn,), daemon=True).start()
def _handle(self, conn):
try: try:
if self.hang: conn.sendall(payload)
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)
except OSError: except OSError:
pass pass
thread = threading.Thread(target=run, daemon=True)
thread.start()
try:
yield
finally: finally:
conn.close() listener.close()
thread.join(5)
def close(self):
self._stop.set()
self.sock.close()
@pytest.fixture def test_fetch_returns_the_payloads(sock_path, serve):
def contract_server(sock_path): frames = distinct_frames(30)
made = [] with serve(sock_path, FakeCapture(frames=frames), fps=50):
got = client.fetch(sock_path, count=3, timeout=5)
def build(frames, **kw): assert len(got) == 3
srv = ContractServer(sock_path, frames, **kw) assert all(payload in frames for payload in got)
made.append(srv)
return srv
yield build
for srv in made:
srv.close()
def test_fetch_returns_one_payload_by_default(contract_server, sock_path): def test_read_stream_also_returns_the_hello(sock_path, serve):
frame = make_png(width=32, height=16) with serve(sock_path, FakeCapture(frames=distinct_frames(5)), fps=25):
contract_server([frame] * 4) hello, frames = client.read_stream(sock_path, count=1, timeout=5)
assert client.fetch(sock_path) == [frame] 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): def test_fetch_returns_fewer_frames_when_the_server_hangs_up(sock_path):
frames = [make_png(value=v) for v in (0x11, 0x22, 0x33)] wire = protocol.hello(4, 2, "image/png", 1) + protocol.frame(b"only one")
contract_server(frames) with stub_server(sock_path, wire):
got = client.fetch(sock_path, count=3) assert client.fetch(sock_path, count=5, timeout=5) == [b"only one"]
assert got == frames
assert not any(b"HHS1" in payload for payload in got)
def test_fetch_stops_at_count(contract_server, sock_path): def test_fetch_on_a_missing_socket_raises_oserror(sock_path):
contract_server([make_png()] * 10) with pytest.raises(OSError):
assert len(client.fetch(sock_path, count=2)) == 2 client.fetch(sock_path, count=1, timeout=1)
def test_fetch_handles_a_payload_with_a_newline_in_it(contract_server, sock_path): def test_fetch_rejects_a_bad_hello(sock_path):
payload = b"12\n" + bytes(range(256)) with stub_server(sock_path, b'{"magic":"NOPE"}\n'):
contract_server([payload, payload]) with pytest.raises(ValueError):
assert client.fetch(sock_path, count=2) == [payload, payload] client.fetch(sock_path, count=1, timeout=5)
def test_fetch_raises_when_the_socket_does_not_exist(tmp_path, rejects): def test_fetch_rejects_a_truncated_frame(sock_path):
with rejects(OSError): wire = protocol.hello(4, 2, "image/png", 1) + b"100\nshort"
client.fetch(str(tmp_path / "absent.sock")) 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): # -- the CLI -------------------------------------------------------------
contract_server([], hang=True)
with rejects(OSError, EOFError, TimeoutError): def test_main_prints_the_hello_and_writes_one_frame(sock_path, serve, workdir, capsys):
client.fetch(sock_path, count=1, timeout=1.0) 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( def test_main_suffixes_the_output_when_count_is_more_than_one(sock_path, serve,
contract_server, sock_path, rejects workdir, capsys):
): with serve(sock_path, FakeCapture(frames=distinct_frames(20)), fps=50):
contract_server([make_png()]) assert client.main(["--socket", sock_path, "--count", "2",
with rejects(OSError, EOFError, TimeoutError): "--out", str(workdir / "shot.png"), "--timeout", "5"]) == 0
client.fetch(sock_path, count=5, timeout=2.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(): def test_main_writes_payloads_to_stdout_with_out_dash(sock_path, serve, capsysbinary):
# README.md: hhstream-client --socket <path> --count 1 --out frame.png frame = distinct_frames(1)[0]
parser = client.build_parser() with serve(sock_path, FakeCapture(frames=[frame]), fps=25):
args = parser.parse_args(["--socket", "/run/x.sock", "--count", "1", "--out", "frame.png"]) assert client.main(["--socket", sock_path, "--count", "2", "--out", "-",
assert args.socket == "/run/x.sock" "--timeout", "5"]) == 0
assert args.count == 1 captured = capsysbinary.readouterr()
assert args.out == "frame.png" 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(): def test_main_reports_a_missing_socket_without_a_traceback(sock_path, capsys):
args = client.build_parser().parse_args([]) assert client.main(["--socket", sock_path, "--timeout", "1"]) == 1
assert args.socket == client.DEFAULT_SOCKET == "/run/hyprland-headless-stream/stream.sock" assert "hhstream-client:" in capsys.readouterr().err
def test_main_writes_the_frame_it_read(contract_server, sock_path, tmp_path): def test_main_reports_a_short_stream(sock_path, capsys):
frame = make_png(width=8, height=8) wire = protocol.hello(4, 2, "image/png", 1) + protocol.frame(b"one")
contract_server([frame]) with stub_server(sock_path, wire):
out = tmp_path / "frame.png" assert client.main(["--socket", sock_path, "--count", "3",
rc = client.main(["--socket", sock_path, "--count", "1", "--out", str(out)]) "--timeout", "5"]) == 1
assert rc == 0 assert "wanted 3 frames, got 1" in capsys.readouterr().err
assert out.read_bytes() == frame
def test_main_reports_failure_without_a_traceback(tmp_path): def test_main_rejects_a_negative_count(sock_path, capsys):
rc = client.main(["--socket", str(tmp_path / "absent.sock"), "--count", "1"]) assert client.main(["--socket", sock_path, "--count", "-1"]) == 2
assert rc != 0 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
-38
View File
@@ -1,38 +0,0 @@
"""The parts of the package that are plain constants, checked against the contract.
These are the only tests here that do not depend on an implementation, which
makes them the canary for the `unit` check's own wiring: if they fail, the
package is not importable from the build sandbox and nothing else means anything.
"""
from __future__ import annotations
import hhstream
from hhstream import capture, client, protocol, server
from conftest import CONTRACT_SOCKET
def test_magic_matches_the_contract():
# docs/CONTRACT.md: {"magic":"HHS1", ...}
assert hhstream.MAGIC == "HHS1"
assert protocol.MAGIC == "HHS1"
def test_default_socket_path_matches_the_contract():
assert server.DEFAULT_SOCKET == CONTRACT_SOCKET
assert client.DEFAULT_SOCKET == CONTRACT_SOCKET
def test_public_surface_is_present():
for name in ("hello", "parse_hello", "frame", "read_frame", "read_hello"):
assert callable(getattr(protocol, name)), f"protocol.{name}"
assert callable(client.fetch)
assert callable(client.main)
assert callable(server.main)
assert isinstance(server.FrameServer, type)
assert isinstance(capture.CommandCapture, type)
def test_version_is_the_packaged_version():
assert hhstream.__version__ == "0.1.0"
+161 -144
View File
@@ -1,10 +1,4 @@
"""Framing, byte for byte, against docs/CONTRACT.md. """The framing. Other people's clients depend on these bytes being exact."""
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.
"""
from __future__ import annotations from __future__ import annotations
@@ -13,157 +7,180 @@ import json
import pytest import pytest
from hhstream import protocol from hhstream import MAGIC, protocol
# -- Hello ---------------------------------------------------------------- # -- Hello ---------------------------------------------------------------
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'
)
def test_hello_is_one_json_line(): def test_hello_round_trip():
line = protocol.hello(1280, 720, "image/png", 30) line = protocol.hello(640, 480, "image/jpeg", 15)
assert isinstance(line, bytes) assert line.endswith(b"\n") and line.count(b"\n") == 1
assert line.endswith(b"\n") assert protocol.parse_hello(line) == {
assert line.count(b"\n") == 1, "the Hello is exactly one line" "magic": MAGIC, "width": 640, "height": 480,
"format": "image/jpeg", "fps": 15,
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_tolerates_a_missing_trailing_newline():
def test_parse_hello_rejects_junk(junk, rejects): line = protocol.hello(8, 8, "image/png", 1)
with rejects(): assert protocol.parse_hello(line.rstrip(b"\n")) == protocol.parse_hello(line)
protocol.parse_hello(junk)
# -- frames --------------------------------------------------------------- @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)
def test_frame_prefixes_the_payload_length_in_ascii(): @pytest.mark.parametrize("payload", [
assert protocol.frame(b"hello") == b"5\n" + b"hello" 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_frame_length_counts_the_payload_only(): def test_read_hello_then_frames_from_one_stream():
payload = b"\x00" * 1234 stream = io.BytesIO(
framed = protocol.frame(payload) protocol.hello(2, 2, "image/png", 5) + protocol.frame(b"one") + protocol.frame(b"two")
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): assert protocol.read_hello(stream)["width"] == 2
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")
)
stream = io.BytesIO(wire)
hello = protocol.read_hello(stream)
assert hello["magic"] == "HHS1"
assert (hello["width"], hello["height"]) == (1280, 720)
assert protocol.read_frame(stream) == b"one" assert protocol.read_frame(stream) == b"one"
assert protocol.read_frame(stream) == b"two" assert protocol.read_frame(stream) == b"two"
assert protocol.read_frame(stream) is None 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)
+219 -168
View File
@@ -1,202 +1,253 @@
"""`FrameServer` against a real (temporary) socket. """The server's obligations from docs/CONTRACT.md, none of which need a GPU."""
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.
"""
from __future__ import annotations from __future__ import annotations
import os import os
import socket import socket
import stat
import threading
import time import time
import pytest import pytest
from helpers import (FAKE_CAPTURE, FakeCapture, abort, connect, distinct_frames,
png_bytes)
from hhstream import protocol from hhstream import protocol
from hhstream.capture import CommandCapture
from hhstream.server import FrameServer 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: def read_hello(conn, timeout=HELLO_WAIT):
end = time.monotonic() + deadline conn.settimeout(timeout)
while time.monotonic() < end: return protocol.read_hello(conn.makefile("rb"))
if os.path.exists(path):
return
time.sleep(0.02)
raise AssertionError(f"server never bound {path}")
def read_stream(sock: socket.socket): def test_fps_must_be_positive(sock_path):
"""A file object over the socket, for protocol.read_* to consume.""" for bad in (0, -1, True, 1.5):
return sock.makefile("rb") with pytest.raises(ValueError):
FrameServer(sock_path, FakeCapture(), bad)
def test_serves_the_hello_then_frames(sock_path, stub_capture, run_bg, connect): def test_two_clients_each_get_their_own_hello_and_frames(sock_path, serve):
cap = stub_capture(frames=[make_png(width=64, height=32)], size=(64, 32)) capture = FakeCapture(frames=distinct_frames(20), size=(1280, 720))
box = run_bg(FrameServer(sock_path, cap, fps=30).serve_forever) with serve(sock_path, capture, fps=30):
wait_for_socket(sock_path) first, second = connect(sock_path), connect(sock_path)
streams = [first.makefile("rb"), second.makefile("rb")]
with read_stream(connect(sock_path)) as stream: hellos = [protocol.read_hello(s) for s in streams]
hello = protocol.read_hello(stream) assert hellos[0] == hellos[1] == {
assert hello["magic"] == "HHS1" "magic": "HHS1", "width": 1280, "height": 720,
assert (hello["width"], hello["height"]) == (64, 32) "format": "image/png", "fps": 30,
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:
for stream in streams: 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()
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): for _ in range(3):
doomed = connect(sock_path) payload = protocol.read_frame(stream)
doomed.recv(1) # take one byte of the Hello, then die mid-message assert payload and payload.startswith(b"\x89PNG\r\n\x1a\n")
doomed.close() first.close()
second.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_stalled_client_does_not_stall_the_others(sock_path, stub_capture, run_bg, connect): def test_a_client_arriving_later_is_served_too(sock_path, serve):
# docs/CONTRACT.md: "A client that stalls or reads slowly is *slowed*, not with serve(sock_path, FakeCapture(frames=distinct_frames(50)), fps=50):
# queued" -- observably, it must not hold up anybody else. early = connect(sock_path)
run_bg(FrameServer(sock_path, stub_capture(), fps=30).serve_forever) early_stream = early.makefile("rb")
wait_for_socket(sock_path) 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()
stalled = connect(sock_path) # connects and never reads
with read_stream(connect(sock_path)) as stream: def test_a_stalled_client_does_not_block_another(sock_path, serve):
assert protocol.read_hello(stream)["magic"] == "HHS1" """Contract: a stalled client is slowed, not queued -- and it is alone."""
for _ in range(5): big = png_bytes(1024, 1024, (1, 2, 3), level=0) # ~3 MiB, fills any buffer
assert len(protocol.read_frame(stream)) > 0 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)
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() stalled.close()
def test_bytes_sent_by_a_client_are_read_and_ignored(sock_path, stub_capture, run_bg, connect): def test_frames_are_dropped_for_a_slow_client_not_queued(sock_path, serve):
# docs/CONTRACT.md -> "Client -> server direction": reserved in v1. frames = distinct_frames(400)
box = run_bg(FrameServer(sock_path, stub_capture(), fps=30).serve_forever) index_of = {payload: i for i, payload in enumerate(frames, start=1)}
wait_for_socket(sock_path) 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}"
sock = connect(sock_path)
sock.sendall(b"a future control channel says hello\n" * 64) def test_server_survives_a_client_dying_mid_frame(sock_path, serve):
with read_stream(sock) as stream: 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" assert protocol.read_hello(stream)["magic"] == "HHS1"
assert len(protocol.read_frame(stream)) > 0 assert protocol.read_frame(stream)
assert not box, f"server thread died: {box}" conn.sendall(b"more chatter")
assert protocol.read_frame(stream)
conn.close()
def test_a_failing_capture_does_not_kill_the_server(sock_path, stub_capture, run_bg, connect): def test_capture_failure_keeps_the_server_up_and_holds_the_hello(sock_path, serve,
# docs/CONTRACT.md -> Failure semantics: "the server keeps the socket up and workdir):
# retries; it does not exit and it does not send partial frames." """Contract: no compositor -> keep the socket up, retry, send no Hello yet."""
cap = stub_capture(raise_first=3) gate = workdir / "gate"
box = run_bg(FrameServer(sock_path, cap, fps=30).serve_forever) capture = CommandCapture(
wait_for_socket(sock_path) [*FAKE_CAPTURE, "--gate", str(gate), "--width", "800", "--height", "600"],
timeout=10,
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", "-"]
) )
assert args.socket == "/run/x.sock" with serve(sock_path, capture, fps=20) as server:
assert args.fps == 24 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(): def test_capture_failing_in_the_middle_does_not_break_the_stream(sock_path, serve):
from hhstream import server 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()