Compare commits
7
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
a37b3dd485 | ||
|
|
db886faa38 | ||
|
|
578e14286d | ||
|
|
72f359932a | ||
|
|
0fb515cc83 | ||
|
|
4af6f7072a | ||
|
|
75a05cd72f |
No files matched your search
+241
@@ -0,0 +1,241 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,28 @@
|
||||
# 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;
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,90 @@
|
||||
#!/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))
|
||||
@@ -0,0 +1,84 @@
|
||||
# What a NixOS test machine has to be given before Hyprland 0.56.2 will start.
|
||||
#
|
||||
# Imported by both VM checks. It is a machine definition, not a test: nothing
|
||||
# here relaxes anything either check asserts, it only supplies hardware and
|
||||
# session facts that a default `nodes.machine` does not have.
|
||||
#
|
||||
# The failure it fixes is the same one every time -- the compositor aborts with
|
||||
#
|
||||
# terminate called after throwing an instance of 'std::runtime_error'
|
||||
# what(): CBackend::create() failed!
|
||||
#
|
||||
# and systemd restarts it until the test's timeout expires. `CBackend::create()`
|
||||
# is aquamarine's, and reading aquamarine 0.15.1 rather than guessing at it, it
|
||||
# needs three separate things that a bare test machine does not provide. Each is
|
||||
# one of the blocks below, and each was confirmed in the guest by removing it
|
||||
# again and watching the compositor die on the next line down.
|
||||
#
|
||||
# A note for whoever hits this next: none of it is visible in the journal until
|
||||
# you also set `debug:disable_logs = false`, because Hyprland mutes aquamarine
|
||||
# by default and the abort is all that survives. That is how the three causes
|
||||
# below were separated.
|
||||
{ ... }:
|
||||
{
|
||||
# 1. A DRM render node.
|
||||
#
|
||||
# `virtualisation.graphics = false` still leaves QEMU's default bochs-drm
|
||||
# adapter in the guest, which offers /dev/dri/card0 and *no* renderD*. Measured
|
||||
# in the guest, not assumed:
|
||||
#
|
||||
# (default) card0 (bochs-drm)
|
||||
# -vga virtio card0, renderD128 (virtio_gpu)
|
||||
# -device virtio-gpu-pci card0, card1, renderD128 (bochs + virtio)
|
||||
# -vga none -device virtio-gpu-pci card0, renderD128 (virtio_gpu)
|
||||
#
|
||||
# `-vga virtio` *replaces* the default adapter, so it is the one-option form of
|
||||
# the last line. `-device virtio-gpu-pci` on its own only *adds* a second card
|
||||
# next to bochs-drm, so it would need `-vga none` beside it to leave the guest
|
||||
# with a single DRM device.
|
||||
virtualisation.qemu.options = [ "-vga virtio" ];
|
||||
|
||||
# 2. Mesa, where the GBM loader looks for it.
|
||||
#
|
||||
# aquamarine's allocator is gbm_create_device() on that node. On NixOS the GBM
|
||||
# backends live under /run/opengl-driver, which only exists when
|
||||
# hardware.graphics is enabled -- a test machine has it off. Without it:
|
||||
#
|
||||
# MESA-LOADER: failed to open dri: /run/opengl-driver/lib/gbm/dri_gbm.so:
|
||||
# cannot open shared object file: No such file or directory
|
||||
# ERR from aquamarine ]: Couldn't open a GBM device at fd 21
|
||||
# CRIT from aquamarine ]: Cannot open backend: no allocator available
|
||||
hardware.graphics.enable = true;
|
||||
|
||||
# 3. A seat that is not bound to a VT.
|
||||
#
|
||||
# This one is not really the test machine's business, and it is flagged rather
|
||||
# than fixed: it belongs in nix/module.nix, which this slice may not edit.
|
||||
#
|
||||
# Only the DRM backend ever yields a buffer allocator --
|
||||
# `CHeadlessBackend::drmFD()` returns -1 unconditionally (aquamarine
|
||||
# src/backend/Headless.cpp), and CBackend::start() takes the allocator from the
|
||||
# first implementation with a drm fd. So "headless" here does not mean "no
|
||||
# GPU": the headless backend still rides on the DRM backend's allocator, and if
|
||||
# the DRM backend fails there is none, whatever /dev/dri holds.
|
||||
#
|
||||
# The DRM backend opens /dev/dri/card0 through libseat. For this unit libseat
|
||||
# finds no /run/seatd.sock and no logind session (it is a system service, not a
|
||||
# login), so it falls back to its embedded seatd -- whose seat is VT-bound by
|
||||
# default. It then tries to open /dev/tty0, which the unprivileged `hhstream`
|
||||
# user cannot, so the client never becomes active and every device open is
|
||||
# refused:
|
||||
#
|
||||
# ERR ]: [libseat] [common/terminal.c:162] Could not open target tty: Permission denied
|
||||
# ERR ]: [libseat] [seatd/seat.c:557] Could not open VT for client
|
||||
# ERR ]: libseat: Couldn't open device at /dev/dri/card0
|
||||
# ERR ]: drm: Skipping device /sys/devices/.../drm/card0, not a KMS device
|
||||
# ERR ]: drm: Found no gpus to use, cannot continue
|
||||
# ERR ]: DRM Backend failed
|
||||
#
|
||||
# SEATD_VTBOUND=0 (seatd/server.c) asks that embedded seatd for a seat with no
|
||||
# VT at all, which is the truth about this session: there is no terminal to
|
||||
# switch away from. A headless session run as a system user will need this on
|
||||
# any machine, not just in the test.
|
||||
systemd.services.hyprland-headless.environment.SEATD_VTBOUND = "0";
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
# 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
|
||||
''
|
||||
@@ -0,0 +1,74 @@
|
||||
# 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
|
||||
''
|
||||
@@ -0,0 +1,157 @@
|
||||
# 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,
|
||||
python3,
|
||||
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 = {
|
||||
# gpu-session.nix is what makes the compositor able to start at all; see
|
||||
# that file for the three things a bare test machine is missing.
|
||||
imports = [ hhsModule ./lib/gpu-session.nix ];
|
||||
|
||||
services.hyprland-headless-stream = {
|
||||
enable = true;
|
||||
# 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
|
||||
# The "client dying mid-stream" subtest opens the socket from a python
|
||||
# one-liner in the guest. hhstream's own interpreter is reachable only
|
||||
# through its wrapper, so without this the subtest dies on exit code 127
|
||||
# (`python3: command not found`) rather than on anything it asserts.
|
||||
python3
|
||||
];
|
||||
|
||||
# Mesa and the compositor together need more than the fake capture alone
|
||||
# did; the GPU itself comes from gpu-session.nix.
|
||||
virtualisation = {
|
||||
memorySize = 2048;
|
||||
cores = 2;
|
||||
diskSize = 4096;
|
||||
graphics = false;
|
||||
};
|
||||
};
|
||||
|
||||
testScript = ''
|
||||
SOCKET = "${socketPath}"
|
||||
ASSERT = "hhs-assert-stream --socket " + SOCKET
|
||||
|
||||
|
||||
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 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
|
||||
'';
|
||||
}
|
||||
@@ -0,0 +1,160 @@
|
||||
# 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 = {
|
||||
# gpu-session.nix is what makes the compositor able to start at all; see
|
||||
# that file for the three things a bare test machine is missing.
|
||||
imports = [ hhsModule ./lib/gpu-session.nix ];
|
||||
|
||||
services.hyprland-headless-stream = {
|
||||
enable = true;
|
||||
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. The virtio GPU from gpu-session.nix is there for its
|
||||
# render node and its DRM backend, not for acceleration: rendering is still
|
||||
# Mesa's software path.
|
||||
virtualisation = {
|
||||
memorySize = 2048;
|
||||
cores = 2;
|
||||
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
|
||||
'';
|
||||
}
|
||||
@@ -0,0 +1,76 @@
|
||||
# Architecture
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────┐
|
||||
│ hyprland-headless.service │
|
||||
│ Hyprland 0.56.2, no physical monitor │
|
||||
│ private XDG_RUNTIME_DIR, as `user` │
|
||||
│ outputs come from `outputs[]` │
|
||||
└───────────────┬──────────────────────────┘
|
||||
│ Wayland session
|
||||
▼
|
||||
┌──────────────────────────────────────────┐
|
||||
│ hyprland-headless-stream.service │
|
||||
│ hhstream-server │
|
||||
│ capture ──▶ one "latest frame" slot │
|
||||
│ accept ──▶ a thread per client │
|
||||
└───────────────┬──────────────────────────┘
|
||||
│ AF_UNIX, mode 0660
|
||||
▼
|
||||
many clients ── hhstream-client / any socket reader
|
||||
```
|
||||
|
||||
Three pieces, deliberately separate:
|
||||
|
||||
1. **The compositor** (`Hyprland`, unchanged upstream) renders into virtual
|
||||
outputs. It knows nothing about frames on a socket.
|
||||
2. **The frame server** (`hhstream`) captures, holds exactly one frame, and
|
||||
publishes it. It owns the socket, the framing and the drop policy.
|
||||
3. **The client** is any process that can open a Unix socket and read the
|
||||
contract's byte format. The shipped `hhstream-client` is a convenience, not a
|
||||
requirement.
|
||||
|
||||
## Why one frame, not a queue
|
||||
|
||||
The server keeps a single slot holding the most recent frame. Each client thread
|
||||
sends whatever is in that slot when it is ready. A client that cannot keep up
|
||||
therefore misses frames instead of forcing the server to buffer them: memory use
|
||||
does not grow with the number of stalled clients, and a stalled client cannot
|
||||
delay the others. See `docs/CONTRACT.md` for exactly what a client observes.
|
||||
|
||||
## Capture
|
||||
|
||||
Capturing is a separate program (by default `grim`, a wlr-screencopy client) run
|
||||
inside the compositor's session and pointed at stdout. That choice is what keeps
|
||||
`hhstream` free of Wayland and GPU code — the awkward part lives in a tool that
|
||||
already exists and is already tested — and it is why the capture command is a
|
||||
module option: tests inject a fake, and a future backend (a native screencopy
|
||||
client, a hardware encoder) is a command-line swap rather than a rewrite.
|
||||
|
||||
## The hardware requirement, stated plainly
|
||||
|
||||
`Hyprland` 0.56.2 asks aquamarine for its **headless backend as mandatory**
|
||||
(`src/Compositor.cpp`) and does not accept the DRM backend if it is
|
||||
unavailable. Aquamarine's headless backend still needs an EGL/GBM **render
|
||||
node**; there is no software-only path that works without one. Consequently a
|
||||
host with no graphics device at all (`/dev/dri` missing) cannot run this, and
|
||||
Pyprland fails with `CBackend::create() failed!` before any of its managers come
|
||||
up.
|
||||
|
||||
So the requirements are:
|
||||
|
||||
- a render node, i.e. `/dev/dri/renderD*` — from a real GPU, a virtual GPU
|
||||
(`virtio-gpu`, `virtio-gpu-gl`, QXL) or a NixOS test VM's own QEMU display;
|
||||
- the `video`/`render` groups for whichever user runs it (the module sets them).
|
||||
|
||||
## Testing, and what each layer proves
|
||||
|
||||
| Layer | Proves |
|
||||
|---|---|
|
||||
| `tests/unit` | the framing, the capture wrapper and the server's client handling, with no compositor and no GPU |
|
||||
| `checks.vm-basic` | the module actually starts both units, the socket appears with the right owner/mode, the Hello parses and two frames arrive — with a fake capture program |
|
||||
| `checks.vm-hyprland` | the real thing: headless Hyprland comes up in the VM and `grim` captures a frame of the configured size |
|
||||
|
||||
`vm-hyprland` is the only check that can fail for reasons outside this repo, so
|
||||
it is kept separate from `vm-basic` on purpose: when it fails, the compositor's
|
||||
log is the answer and the other two layers are already known good.
|
||||
+34
-3
@@ -59,8 +59,17 @@ breaking v1 readers, which never expect inbound data.)
|
||||
|
||||
- Compositor not running / capture tool erroring: the server keeps the socket up
|
||||
and retries; it does **not** exit and it does **not** send partial frames.
|
||||
- If a Hello cannot be produced (no output size known yet), the server waits
|
||||
until it can, then sends it. It never sends a Hello with zero size.
|
||||
- **Hello timing.** The Hello is written the moment the server can produce it,
|
||||
which in practice is the moment of the first successful capture. A client that
|
||||
connects before that has received zero bytes and simply waits: the server
|
||||
never sends a Hello with a zero or unknown size. ("Immediately" above means
|
||||
"before any frame", not "before the first capture".)
|
||||
- `width`/`height` in the Hello are **measured from the captured frame**, not
|
||||
taken from configuration, so they cannot disagree with the pixels actually
|
||||
being sent.
|
||||
- A client that is torn down or killed *mid-frame* may see a truncated final
|
||||
frame. "Never sends partial frames" is about the server failing to capture,
|
||||
not about a client that has already gone away.
|
||||
|
||||
## NixOS module surface
|
||||
|
||||
@@ -84,4 +93,26 @@ Services (names are part of the contract, tests refer to them):
|
||||
- `hyprland-headless.service` — the compositor, running as `user`, on a private
|
||||
`XDG_RUNTIME_DIR`, with no physical output.
|
||||
- `hyprland-headless-stream.service` — the frame server, `After=` the compositor,
|
||||
with `Restart=always`, connected to the same session.
|
||||
with `Restart=always`, connected to the same session.
|
||||
|
||||
## Server command line
|
||||
|
||||
The module drives the server, so its flags are an interface too — the same
|
||||
status as the wire format. Exactly this shape, and no others:
|
||||
|
||||
```
|
||||
hhstream-server --socket <socketPath> --fps <frameRate> --format <png|jpeg> \
|
||||
[--capture-command <token> ...]
|
||||
```
|
||||
|
||||
- `--format` takes the **short name** (`png`, `jpeg`), not a MIME type; the
|
||||
server maps it to `image/png` / `image/jpeg` for the Hello.
|
||||
- `--capture-command` is **repeated, one argv token per occurrence**:
|
||||
`--capture-command grim --capture-command -t --capture-command png
|
||||
--capture-command -`. A single shell string cannot carry a leading `-`
|
||||
unambiguously. The `--capture-command=<token>` form is accepted as well, and
|
||||
the two may be mixed. When absent, the server derives `grim -t <format> -`.
|
||||
- There is deliberately **no** `--width` / `--height`: the Hello reports the
|
||||
captured frame's real size (see above).
|
||||
- The socket's **mode** (0660) is the server's business; its **ownership** is
|
||||
the systemd unit's (`user`/`group`), because the server cannot chown.
|
||||
@@ -8,6 +8,10 @@
|
||||
outputs = { self, nixpkgs, ... }: let
|
||||
systems = [ "x86_64-linux" "aarch64-linux" ];
|
||||
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 {
|
||||
packages = forAllSystems (pkgs: rec {
|
||||
hhstream = pkgs.callPackage ./nix/package.nix {};
|
||||
@@ -19,8 +23,10 @@
|
||||
default = hyprland-headless-stream;
|
||||
};
|
||||
|
||||
# `checks` (unit tests + the VM integration test) is owned by the
|
||||
# test-harness workstream -- see docs/CONTRACT.md for the interface.
|
||||
# Unit tests + the two VM integration tests. See checks/default.nix and
|
||||
# README.dev.md; the interface they assert is docs/CONTRACT.md.
|
||||
checks = forAllSystems' ({ pkgs, system }:
|
||||
import ./checks { inherit pkgs self system; });
|
||||
|
||||
devShells = forAllSystems (pkgs: {
|
||||
default = pkgs.mkShell {
|
||||
|
||||
+140
-5
@@ -7,9 +7,24 @@ produces frames in a unit test.
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import struct
|
||||
import subprocess
|
||||
from typing import Protocol
|
||||
|
||||
#: MIME types the contract allows, and the pixel-size probe for each.
|
||||
_SOF_MARKERS = frozenset(
|
||||
m for m in range(0xC0, 0xD0) if m not in (0xC4, 0xC8, 0xCC)
|
||||
)
|
||||
|
||||
|
||||
class CaptureError(RuntimeError):
|
||||
"""One capture attempt failed; the server catches this and keeps serving.
|
||||
|
||||
Covers every way the helper command can let us down: it is missing, it
|
||||
exits non-zero, it times out, or it writes nothing.
|
||||
"""
|
||||
|
||||
|
||||
class CaptureBackend(Protocol):
|
||||
def grab(self) -> bytes:
|
||||
@@ -22,17 +37,137 @@ class CaptureBackend(Protocol):
|
||||
|
||||
|
||||
class CommandCapture:
|
||||
"""Runs a helper that writes one frame to stdout (default: grim)."""
|
||||
"""Runs a helper that writes one frame to stdout (default: grim).
|
||||
|
||||
`env` is overlaid on the server's own environment (that is how the session
|
||||
variables -- `WAYLAND_DISPLAY`, `XDG_RUNTIME_DIR` -- reach the helper
|
||||
without having to restate `PATH`). The helper's stdout is the frame and its
|
||||
stderr is captured, so a chatty or failing helper never writes to the
|
||||
server's own stdout/stderr; the message ends up in the raised
|
||||
`CaptureError` instead.
|
||||
"""
|
||||
|
||||
def __init__(self, argv: list[str], env: dict[str, str] | None = None,
|
||||
timeout: float = 5.0) -> None:
|
||||
raise NotImplementedError
|
||||
argv = list(argv)
|
||||
if not argv:
|
||||
raise ValueError("capture command must not be empty")
|
||||
if timeout is not None and timeout <= 0:
|
||||
raise ValueError(f"capture timeout must be positive, got {timeout!r}")
|
||||
self.argv = argv
|
||||
self.env = dict(env) if env is not None else None
|
||||
self.timeout = timeout
|
||||
self._size: tuple[int, int] | None = None
|
||||
|
||||
def grab(self) -> bytes:
|
||||
raise NotImplementedError
|
||||
"""Run the helper once and return the bytes it wrote to stdout."""
|
||||
child_env = None
|
||||
if self.env is not None:
|
||||
child_env = dict(os.environ)
|
||||
child_env.update(self.env)
|
||||
try:
|
||||
proc = subprocess.run(
|
||||
self.argv,
|
||||
stdin=subprocess.DEVNULL,
|
||||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.PIPE,
|
||||
env=child_env,
|
||||
timeout=self.timeout,
|
||||
check=False,
|
||||
)
|
||||
except subprocess.TimeoutExpired as exc:
|
||||
raise CaptureError(
|
||||
f"capture command {self.argv!r} timed out after {self.timeout}s"
|
||||
) from exc
|
||||
except OSError as exc:
|
||||
raise CaptureError(
|
||||
f"capture command {self.argv!r} could not be run: {exc}"
|
||||
) from exc
|
||||
if proc.returncode != 0:
|
||||
raise CaptureError(
|
||||
f"capture command {self.argv!r} exited {proc.returncode}: "
|
||||
f"{_tail(proc.stderr)}"
|
||||
)
|
||||
if not proc.stdout:
|
||||
raise CaptureError(
|
||||
f"capture command {self.argv!r} produced no output: "
|
||||
f"{_tail(proc.stderr)}"
|
||||
)
|
||||
measured = image_size(proc.stdout)
|
||||
if measured is not None:
|
||||
self._size = measured
|
||||
return proc.stdout
|
||||
|
||||
def size(self) -> tuple[int, int]:
|
||||
raise NotImplementedError
|
||||
"""Pixel size of the captured output, for the Hello.
|
||||
|
||||
Measured from the frame itself (the PNG/JPEG header), so no compositor
|
||||
query is needed and an injected fake command works the same way. The
|
||||
first successful measurement is remembered; `grab` refreshes it, so
|
||||
after a frame has been captured this costs nothing.
|
||||
"""
|
||||
if self._size is None:
|
||||
self.grab()
|
||||
if self._size is None:
|
||||
raise CaptureError(
|
||||
f"cannot determine pixel size from the output of {self.argv!r} "
|
||||
"(not a PNG or JPEG?)"
|
||||
)
|
||||
return self._size
|
||||
|
||||
|
||||
__all__ = ["CaptureBackend", "CommandCapture", "subprocess"]
|
||||
def image_size(data: bytes) -> tuple[int, int] | None:
|
||||
"""Pixel size of a PNG or JPEG frame, or None if it cannot be read."""
|
||||
return _png_size(data) or _jpeg_size(data)
|
||||
|
||||
|
||||
def _png_size(data: bytes) -> tuple[int, int] | None:
|
||||
if not data.startswith(b"\x89PNG\r\n\x1a\n") or len(data) < 24:
|
||||
return None
|
||||
if data[12:16] != b"IHDR":
|
||||
return None
|
||||
width, height = struct.unpack(">II", data[16:24])
|
||||
return (width, height) if width and height else None
|
||||
|
||||
|
||||
def _jpeg_size(data: bytes) -> tuple[int, int] | None:
|
||||
if not data.startswith(b"\xff\xd8"):
|
||||
return None
|
||||
i, n = 2, len(data)
|
||||
while i + 1 < n:
|
||||
if data[i] != 0xFF:
|
||||
i += 1 # resync on the next marker
|
||||
continue
|
||||
marker = data[i + 1]
|
||||
if marker == 0xFF:
|
||||
i += 1 # fill byte
|
||||
continue
|
||||
if marker in (0x01, 0xD8, 0xD9) or 0xD0 <= marker <= 0xD7:
|
||||
i += 2 # standalone marker, no payload
|
||||
continue
|
||||
if i + 4 > n:
|
||||
return None
|
||||
seglen = int.from_bytes(data[i + 2:i + 4], "big")
|
||||
if seglen < 2:
|
||||
return None
|
||||
if marker in _SOF_MARKERS:
|
||||
if i + 9 > n:
|
||||
return None
|
||||
height = int.from_bytes(data[i + 5:i + 7], "big")
|
||||
width = int.from_bytes(data[i + 7:i + 9], "big")
|
||||
return (width, height) if width and height else None
|
||||
i += 2 + seglen
|
||||
return None
|
||||
|
||||
|
||||
def _tail(stderr: bytes | None, limit: int = 400) -> str:
|
||||
if not stderr:
|
||||
return "no stderr"
|
||||
text = stderr.decode("utf-8", "replace").strip()
|
||||
if len(text) > limit:
|
||||
text = "..." + text[-limit:]
|
||||
return text or "no stderr"
|
||||
|
||||
|
||||
__all__ = ["CaptureBackend", "CommandCapture", "CaptureError", "image_size",
|
||||
"subprocess"]
|
||||
+102
-5
@@ -3,22 +3,119 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import pathlib
|
||||
import socket
|
||||
import sys
|
||||
from typing import Iterable
|
||||
|
||||
from . import protocol
|
||||
|
||||
DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock"
|
||||
|
||||
|
||||
def fetch(socket_path: str, count: int = 1, timeout: float = 10.0) -> list[bytes]:
|
||||
"""Connect and return up to `count` frame payloads (Hello consumed)."""
|
||||
raise NotImplementedError
|
||||
"""Connect and return up to `count` frame payloads (Hello consumed).
|
||||
|
||||
`timeout` bounds each socket operation, not the whole call: at the
|
||||
advertised fps a frame is expected well inside it. Fewer than `count`
|
||||
frames come back if the server closes the connection first.
|
||||
"""
|
||||
return read_stream(socket_path, count, timeout)[1]
|
||||
|
||||
|
||||
def read_stream(socket_path: str, count: int = 1,
|
||||
timeout: float = 10.0) -> tuple[dict, list[bytes]]:
|
||||
"""Like `fetch`, but also returns the parsed Hello."""
|
||||
conn = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
||||
conn.settimeout(timeout)
|
||||
try:
|
||||
conn.connect(socket_path)
|
||||
with conn.makefile("rb") as stream:
|
||||
hello = protocol.read_hello(stream)
|
||||
frames: list[bytes] = []
|
||||
while len(frames) < count:
|
||||
payload = protocol.read_frame(stream)
|
||||
if payload is None:
|
||||
break # server closed; return what we got
|
||||
frames.append(payload)
|
||||
return hello, frames
|
||||
finally:
|
||||
conn.close()
|
||||
|
||||
|
||||
def build_parser() -> argparse.ArgumentParser:
|
||||
raise NotImplementedError
|
||||
parser = argparse.ArgumentParser(
|
||||
prog="hhstream-client",
|
||||
description="Read frames from a hyprland-headless-stream socket.",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--socket", default=DEFAULT_SOCKET, metavar="PATH",
|
||||
help="socket to read from (default: %(default)s)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--count", type=int, default=1, metavar="N",
|
||||
help="how many frames to read (default: %(default)s)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--out", metavar="PATH",
|
||||
help="write each frame here, suffixed when --count > 1; "
|
||||
"'-' writes the payloads to stdout",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--timeout", type=float, default=10.0, metavar="SECONDS",
|
||||
help="per-read socket timeout (default: %(default)s)",
|
||||
)
|
||||
return parser
|
||||
|
||||
|
||||
def main(argv: Iterable[str] | None = None) -> int:
|
||||
raise NotImplementedError
|
||||
args = build_parser().parse_args(argv)
|
||||
if args.count < 0:
|
||||
print("--count must not be negative", file=sys.stderr)
|
||||
return 2
|
||||
to_stdout = args.out == "-"
|
||||
# Keep stdout for the payloads when they are going there.
|
||||
report = sys.stderr if to_stdout else sys.stdout
|
||||
|
||||
try:
|
||||
hello, frames = read_stream(args.socket, args.count, args.timeout)
|
||||
except (OSError, EOFError, ValueError) as exc:
|
||||
print(f"hhstream-client: {exc}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
print(json.dumps(hello, separators=(",", ":")), file=report)
|
||||
for index, payload in enumerate(frames, start=1):
|
||||
if to_stdout:
|
||||
sys.stdout.buffer.write(payload)
|
||||
sys.stdout.buffer.flush()
|
||||
print(f"frame {index}: {len(payload)} bytes", file=report)
|
||||
elif args.out:
|
||||
target = output_path(args.out, index, args.count)
|
||||
target.write_bytes(payload)
|
||||
print(f"frame {index}: {len(payload)} bytes -> {target}", file=report)
|
||||
else:
|
||||
print(f"frame {index}: {len(payload)} bytes", file=report)
|
||||
report.flush()
|
||||
|
||||
if len(frames) < args.count:
|
||||
print(
|
||||
f"hhstream-client: wanted {args.count} frames, got {len(frames)} "
|
||||
"(server closed the connection)",
|
||||
file=sys.stderr,
|
||||
)
|
||||
return 1
|
||||
return 0
|
||||
|
||||
|
||||
__all__ = ["fetch", "DEFAULT_SOCKET", "build_parser", "main"]
|
||||
def output_path(out: str, index: int, count: int) -> pathlib.Path:
|
||||
"""`frame.png` -> itself for one frame, `frame-1.png`, `frame-2.png` beyond."""
|
||||
path = pathlib.Path(out)
|
||||
if count <= 1:
|
||||
return path
|
||||
width = len(str(count))
|
||||
return path.with_name(f"{path.stem}-{index:0{width}d}{path.suffix}")
|
||||
|
||||
|
||||
__all__ = ["fetch", "read_stream", "DEFAULT_SOCKET", "build_parser", "main",
|
||||
"output_path"]
|
||||
+115
-6
@@ -10,23 +10,77 @@ from typing import BinaryIO
|
||||
|
||||
from . import MAGIC
|
||||
|
||||
#: Longest length prefix we will read before giving up. The contract allows
|
||||
#: plain ASCII digits with no bound; 20 digits is past 2**63 and keeps a garbage
|
||||
#: stream from making us read forever.
|
||||
MAX_LENGTH_DIGITS = 20
|
||||
|
||||
#: Longest Hello line we will read before giving up, for the same reason.
|
||||
MAX_HELLO_BYTES = 65536
|
||||
|
||||
_READ_CHUNK = 1 << 20
|
||||
|
||||
|
||||
def hello(width: int, height: int, fmt: str, fps: int) -> bytes:
|
||||
"""The one-line JSON Hello, `\\n`-terminated.
|
||||
|
||||
`fmt` is a MIME type ("image/png" / "image/jpeg").
|
||||
"""
|
||||
raise NotImplementedError
|
||||
for name, value in (("width", width), ("height", height), ("fps", fps)):
|
||||
if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
|
||||
raise ValueError(f"{name} must be a positive int, got {value!r}")
|
||||
if not isinstance(fmt, str) or not fmt:
|
||||
raise ValueError(f"format must be a non-empty str, got {fmt!r}")
|
||||
obj = {
|
||||
"magic": MAGIC,
|
||||
"width": width,
|
||||
"height": height,
|
||||
"format": fmt,
|
||||
"fps": fps,
|
||||
}
|
||||
line = json.dumps(obj, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
|
||||
if b"\n" in line:
|
||||
raise ValueError("Hello would contain a newline")
|
||||
return line + b"\n"
|
||||
|
||||
|
||||
def parse_hello(line: bytes) -> dict:
|
||||
"""Inverse of `hello`: validate `magic` and required fields, or raise."""
|
||||
raise NotImplementedError
|
||||
if not isinstance(line, (bytes, bytearray)):
|
||||
raise ValueError(f"Hello must be bytes, got {type(line).__name__}")
|
||||
text = bytes(line)
|
||||
if text.endswith(b"\n"):
|
||||
text = text[:-1]
|
||||
if not text:
|
||||
raise ValueError("empty Hello line")
|
||||
try:
|
||||
obj = json.loads(text.decode("utf-8"))
|
||||
except UnicodeDecodeError as exc:
|
||||
raise ValueError(f"Hello is not UTF-8: {exc}") from exc
|
||||
except json.JSONDecodeError as exc:
|
||||
raise ValueError(f"Hello is not valid JSON: {exc}") from exc
|
||||
if not isinstance(obj, dict):
|
||||
raise ValueError(f"Hello must be a JSON object, got {type(obj).__name__}")
|
||||
if obj.get("magic") != MAGIC:
|
||||
raise ValueError(f"bad magic {obj.get('magic')!r}, expected {MAGIC!r}")
|
||||
for name in ("width", "height", "format", "fps"):
|
||||
if name not in obj:
|
||||
raise ValueError(f"Hello is missing {name!r}")
|
||||
for name in ("width", "height", "fps"):
|
||||
value = obj[name]
|
||||
if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
|
||||
raise ValueError(f"Hello {name} must be a positive int, got {value!r}")
|
||||
if not isinstance(obj["format"], str) or not obj["format"]:
|
||||
raise ValueError(f"Hello format must be a non-empty str, got {obj['format']!r}")
|
||||
return obj
|
||||
|
||||
|
||||
def frame(payload: bytes) -> bytes:
|
||||
"""`<ascii length>\\n<payload>` for one complete image."""
|
||||
raise NotImplementedError
|
||||
if not isinstance(payload, (bytes, bytearray, memoryview)):
|
||||
raise ValueError(f"payload must be bytes, got {type(payload).__name__}")
|
||||
body = bytes(payload)
|
||||
return str(len(body)).encode("ascii") + b"\n" + body
|
||||
|
||||
|
||||
def read_frame(stream: BinaryIO) -> bytes | None:
|
||||
@@ -35,12 +89,67 @@ def read_frame(stream: BinaryIO) -> bytes | None:
|
||||
Returns None on a clean EOF before any byte of the next frame. Raises
|
||||
ValueError on a malformed length prefix and EOFError on a truncated payload.
|
||||
"""
|
||||
raise NotImplementedError
|
||||
digits = bytearray()
|
||||
while True:
|
||||
byte = stream.read(1)
|
||||
if not byte:
|
||||
if not digits:
|
||||
return None # clean EOF between frames
|
||||
raise EOFError(
|
||||
f"EOF in length prefix after {bytes(digits)!r}"
|
||||
)
|
||||
if byte == b"\n":
|
||||
break
|
||||
if not (b"0" <= byte <= b"9"):
|
||||
raise ValueError(
|
||||
f"malformed length prefix: unexpected byte {byte!r} "
|
||||
f"after {bytes(digits)!r}"
|
||||
)
|
||||
digits += byte
|
||||
if len(digits) > MAX_LENGTH_DIGITS:
|
||||
raise ValueError(
|
||||
f"length prefix longer than {MAX_LENGTH_DIGITS} digits"
|
||||
)
|
||||
if not digits:
|
||||
raise ValueError("malformed length prefix: empty")
|
||||
if len(digits) > 1 and digits[:1] == b"0":
|
||||
raise ValueError(f"malformed length prefix: leading zero in {bytes(digits)!r}")
|
||||
length = int(digits)
|
||||
return _read_exactly(stream, length)
|
||||
|
||||
|
||||
def read_hello(stream: BinaryIO) -> dict:
|
||||
"""Read and parse the Hello line from `stream`."""
|
||||
raise NotImplementedError
|
||||
line = bytearray()
|
||||
while True:
|
||||
byte = stream.read(1)
|
||||
if not byte:
|
||||
raise EOFError(f"EOF in Hello line after {len(line)} bytes")
|
||||
if byte == b"\n":
|
||||
break
|
||||
line += byte
|
||||
if len(line) > MAX_HELLO_BYTES:
|
||||
raise ValueError(f"Hello line longer than {MAX_HELLO_BYTES} bytes")
|
||||
return parse_hello(bytes(line))
|
||||
|
||||
|
||||
__all__ = ["json", "hello", "parse_hello", "frame", "read_frame", "read_hello", "MAGIC"]
|
||||
def _read_exactly(stream: BinaryIO, length: int) -> bytes:
|
||||
"""Read exactly `length` bytes or raise EOFError.
|
||||
|
||||
Reads in chunks so a bogus (huge) length prefix cannot make us allocate a
|
||||
buffer for data that is not there.
|
||||
"""
|
||||
if length == 0:
|
||||
return b""
|
||||
out = bytearray()
|
||||
while len(out) < length:
|
||||
chunk = stream.read(min(_READ_CHUNK, length - len(out)))
|
||||
if not chunk:
|
||||
raise EOFError(
|
||||
f"truncated payload: wanted {length} bytes, got {len(out)}"
|
||||
)
|
||||
out += chunk
|
||||
return bytes(out)
|
||||
|
||||
|
||||
__all__ = ["json", "hello", "parse_hello", "frame", "read_frame", "read_hello", "MAGIC"]
|
||||
+369
-5
@@ -8,31 +8,395 @@ synchronously, and a slow write blocks only that client.
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import errno
|
||||
import logging
|
||||
import os
|
||||
import selectors
|
||||
import signal
|
||||
import socket
|
||||
import stat
|
||||
import sys
|
||||
import threading
|
||||
import time
|
||||
from typing import Iterable
|
||||
|
||||
from . import protocol
|
||||
from .capture import CaptureBackend, CommandCapture
|
||||
|
||||
DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock"
|
||||
#: Contract: the published socket is mode 0660 (ownership is the unit's job).
|
||||
SOCKET_MODE = 0o660
|
||||
#: Contract default for `services.hyprland-headless-stream.captureCommand`.
|
||||
DEFAULT_CAPTURE_COMMAND = ["grim", "-t", "png", "-"]
|
||||
|
||||
_BACKLOG = 64
|
||||
_WAIT_TICK = 0.2 # how often a blocked client thread re-checks for shutdown
|
||||
|
||||
log = logging.getLogger("hhstream.server")
|
||||
|
||||
|
||||
class FrameServer:
|
||||
"""Publishes one capture stream to any number of clients.
|
||||
|
||||
A single capture thread holds exactly one frame -- the most recent one --
|
||||
and every client thread sends whatever is in that slot when it is ready for
|
||||
another frame. That is how frames get dropped for a slow client instead of
|
||||
queued: there is no queue, and memory does not grow with the number of
|
||||
stalled clients.
|
||||
"""
|
||||
|
||||
def __init__(self, socket_path: str, capture: CaptureBackend, fps: int,
|
||||
fmt: str = "image/png") -> None:
|
||||
raise NotImplementedError
|
||||
if isinstance(fps, bool) or not isinstance(fps, int) or fps <= 0:
|
||||
raise ValueError(f"fps must be a positive int, got {fps!r}")
|
||||
self.socket_path = socket_path
|
||||
self.capture = capture
|
||||
self.fps = fps
|
||||
self.fmt = fmt
|
||||
|
||||
#: set once the socket is bound and listening (tests wait on it)
|
||||
self.ready = threading.Event()
|
||||
self.frames_captured = 0
|
||||
self.capture_failures = 0
|
||||
|
||||
self._cond = threading.Condition()
|
||||
self._frame: bytes | None = None
|
||||
self._seq = 0
|
||||
self._hello: bytes | None = None
|
||||
self._stop = threading.Event()
|
||||
self._listener: socket.socket | None = None
|
||||
self._bound_inode: tuple[int, int] | None = None
|
||||
self._clients: list[threading.Thread] = []
|
||||
# Closing a listening socket does not reliably interrupt a blocked
|
||||
# accept(), so the accept loop selects on this pair as well and stop()
|
||||
# pokes it.
|
||||
self._wake_r, self._wake_w = socket.socketpair()
|
||||
|
||||
# -- serving ---------------------------------------------------------
|
||||
|
||||
def serve_forever(self) -> None:
|
||||
"""Bind, then serve until stopped. A stale socket file is replaced."""
|
||||
raise NotImplementedError
|
||||
try:
|
||||
self._bind()
|
||||
listener = self._listener
|
||||
assert listener is not None
|
||||
threading.Thread(target=self._capture_loop, name="hhstream-capture",
|
||||
daemon=True).start()
|
||||
log.info("serving %s at %d fps (%s)",
|
||||
self.socket_path, self.fps, self.fmt)
|
||||
self._accept_loop(listener)
|
||||
finally:
|
||||
self.stop()
|
||||
self._wake_r.close()
|
||||
self._wake_w.close()
|
||||
|
||||
def _accept_loop(self, listener: socket.socket) -> None:
|
||||
with selectors.DefaultSelector() as selector:
|
||||
try:
|
||||
selector.register(listener, selectors.EVENT_READ)
|
||||
selector.register(self._wake_r, selectors.EVENT_READ)
|
||||
except (OSError, ValueError):
|
||||
if self._stop.is_set():
|
||||
return # stopped between binding and the accept loop
|
||||
raise
|
||||
while not self._stop.is_set():
|
||||
try:
|
||||
events = selector.select()
|
||||
except OSError as exc:
|
||||
if self._stop.is_set():
|
||||
return
|
||||
log.warning("select failed: %s", exc)
|
||||
self._stop.wait(0.05) # never spin on a repeating error
|
||||
continue
|
||||
if any(key.fileobj is self._wake_r for key, _ in events):
|
||||
return
|
||||
try:
|
||||
conn, _ = listener.accept()
|
||||
except OSError as exc:
|
||||
if self._stop.is_set():
|
||||
return
|
||||
log.warning("accept failed: %s", exc)
|
||||
self._stop.wait(0.05)
|
||||
continue
|
||||
self._clients = [t for t in self._clients if t.is_alive()]
|
||||
thread = threading.Thread(
|
||||
target=self._serve_client, args=(conn,),
|
||||
name="hhstream-client", daemon=True,
|
||||
)
|
||||
self._clients.append(thread)
|
||||
thread.start()
|
||||
|
||||
def stop(self) -> None:
|
||||
"""Ask the accept loop, the capture thread and every client to finish."""
|
||||
self._stop.set()
|
||||
with self._cond:
|
||||
self._cond.notify_all()
|
||||
try:
|
||||
self._wake_w.send(b"\x00") # unblock the accept loop
|
||||
except OSError:
|
||||
pass
|
||||
listener, self._listener = self._listener, None
|
||||
if listener is not None:
|
||||
try:
|
||||
listener.close()
|
||||
except OSError:
|
||||
pass
|
||||
self._unlink_own_socket()
|
||||
|
||||
# -- capture ---------------------------------------------------------
|
||||
|
||||
def _capture_loop(self) -> None:
|
||||
interval = 1.0 / self.fps
|
||||
while not self._stop.is_set():
|
||||
started = time.monotonic()
|
||||
try:
|
||||
payload = self.capture.grab()
|
||||
width, height = self.capture.size()
|
||||
except Exception as exc: # a backend may raise anything
|
||||
self.capture_failures += 1
|
||||
# Contract: capture erroring keeps the socket up and retries; it
|
||||
# never exits and never publishes a partial frame.
|
||||
log.warning("capture failed (%d so far): %s",
|
||||
self.capture_failures, exc)
|
||||
else:
|
||||
self._publish(payload, width, height)
|
||||
remaining = interval - (time.monotonic() - started)
|
||||
if remaining > 0:
|
||||
self._stop.wait(remaining)
|
||||
|
||||
def _publish(self, payload: bytes, width: int, height: int) -> None:
|
||||
with self._cond:
|
||||
if self._hello is None:
|
||||
if width > 0 and height > 0:
|
||||
# Contract: never a Hello with zero size.
|
||||
self._hello = protocol.hello(width, height, self.fmt, self.fps)
|
||||
else:
|
||||
log.warning("ignoring frame with zero size %dx%d", width, height)
|
||||
return
|
||||
self._frame = payload
|
||||
self._seq += 1
|
||||
self.frames_captured += 1
|
||||
self._cond.notify_all()
|
||||
|
||||
# -- one client ------------------------------------------------------
|
||||
|
||||
def _serve_client(self, conn: socket.socket) -> None:
|
||||
peer = conn.fileno()
|
||||
drain = threading.Thread(
|
||||
target=self._drain, args=(conn,), name="hhstream-drain", daemon=True
|
||||
)
|
||||
drain.start()
|
||||
try:
|
||||
hello = self._wait_for_hello()
|
||||
if hello is None:
|
||||
return
|
||||
conn.sendall(hello)
|
||||
last_seq = 0
|
||||
while not self._stop.is_set():
|
||||
payload, last_seq = self._wait_for_frame(last_seq)
|
||||
if payload is None:
|
||||
return
|
||||
conn.sendall(protocol.frame(payload))
|
||||
except OSError as exc:
|
||||
# The whole point: one client dying mid-frame is this thread's
|
||||
# problem and nobody else's.
|
||||
log.info("client %s went away: %s", peer, exc)
|
||||
except Exception:
|
||||
log.exception("client %s failed", peer)
|
||||
finally:
|
||||
try:
|
||||
conn.shutdown(socket.SHUT_RDWR)
|
||||
except OSError:
|
||||
pass
|
||||
try:
|
||||
conn.close()
|
||||
except OSError:
|
||||
pass
|
||||
|
||||
def _drain(self, conn: socket.socket) -> None:
|
||||
"""Read and discard anything a client sends (contract: v1 reserved)."""
|
||||
try:
|
||||
while not self._stop.is_set():
|
||||
if not conn.recv(4096):
|
||||
return
|
||||
except OSError:
|
||||
return
|
||||
|
||||
def _wait_for_hello(self) -> bytes | None:
|
||||
"""Block until the Hello is known (a frame has been captured)."""
|
||||
with self._cond:
|
||||
while self._hello is None and not self._stop.is_set():
|
||||
self._cond.wait(_WAIT_TICK)
|
||||
return self._hello
|
||||
|
||||
def _wait_for_frame(self, last_seq: int) -> tuple[bytes | None, int]:
|
||||
"""Block until a frame newer than `last_seq` exists, then take the latest.
|
||||
|
||||
Everything captured while this client was busy is simply skipped.
|
||||
"""
|
||||
with self._cond:
|
||||
while self._seq == last_seq and not self._stop.is_set():
|
||||
self._cond.wait(_WAIT_TICK)
|
||||
if self._seq == last_seq:
|
||||
return None, last_seq
|
||||
return self._frame, self._seq
|
||||
|
||||
# -- socket ----------------------------------------------------------
|
||||
|
||||
def _bind(self) -> None:
|
||||
path = self.socket_path
|
||||
parent = os.path.dirname(os.path.abspath(path))
|
||||
if parent:
|
||||
os.makedirs(parent, exist_ok=True)
|
||||
self._replace_stale(path)
|
||||
listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
||||
try:
|
||||
listener.bind(path)
|
||||
os.chmod(path, SOCKET_MODE)
|
||||
listener.listen(_BACKLOG)
|
||||
except OSError:
|
||||
listener.close()
|
||||
raise
|
||||
self._listener = listener
|
||||
info = os.lstat(path)
|
||||
self._bound_inode = (info.st_dev, info.st_ino)
|
||||
self.ready.set()
|
||||
|
||||
@staticmethod
|
||||
def _replace_stale(path: str) -> None:
|
||||
"""Remove a leftover socket file so a stale one cannot block startup."""
|
||||
try:
|
||||
info = os.lstat(path)
|
||||
except FileNotFoundError:
|
||||
return
|
||||
if not stat.S_ISSOCK(info.st_mode):
|
||||
raise OSError(
|
||||
errno.EEXIST,
|
||||
f"{path} exists and is not a socket; refusing to remove it",
|
||||
)
|
||||
os.unlink(path)
|
||||
|
||||
def _unlink_own_socket(self) -> None:
|
||||
"""Tidy the socket file away, but only if it is still the one we bound.
|
||||
|
||||
A restart that has already put its own socket there must keep it.
|
||||
"""
|
||||
if self._bound_inode is None:
|
||||
return
|
||||
try:
|
||||
info = os.lstat(self.socket_path)
|
||||
if (info.st_dev, info.st_ino) == self._bound_inode:
|
||||
os.unlink(self.socket_path)
|
||||
except OSError:
|
||||
pass
|
||||
self._bound_inode = None
|
||||
|
||||
|
||||
# -- CLI -----------------------------------------------------------------
|
||||
|
||||
#: `--format png` is the module's spelling; the Hello carries the MIME type.
|
||||
_MIME = {"png": "image/png", "jpeg": "image/jpeg"}
|
||||
_CAPTURE_FLAG = "--capture-command"
|
||||
|
||||
|
||||
def build_parser() -> argparse.ArgumentParser:
|
||||
raise NotImplementedError
|
||||
parser = argparse.ArgumentParser(
|
||||
prog="hhstream-server",
|
||||
description="Publish a headless Hyprland session's frames on a Unix socket.",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--socket", default=DEFAULT_SOCKET, metavar="PATH",
|
||||
help="socket to publish frames on (default: %(default)s)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--fps", type=_positive_int, default=30, metavar="N",
|
||||
help="target capture rate, advertised in the Hello (default: %(default)s)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--format", choices=sorted(_MIME), default="png",
|
||||
help="frame encoding (default: %(default)s)",
|
||||
)
|
||||
parser.add_argument(
|
||||
_CAPTURE_FLAG, action="append", dest="capture_command", metavar="TOKEN",
|
||||
help="one argv token of the capture command; repeat once per token "
|
||||
"(default: %s). Use --capture-command=-t for tokens starting "
|
||||
"with a dash." % " ".join(DEFAULT_CAPTURE_COMMAND),
|
||||
)
|
||||
return parser
|
||||
|
||||
|
||||
def main(argv: Iterable[str] | None = None) -> int:
|
||||
raise NotImplementedError
|
||||
args = build_parser().parse_args(_join_capture_tokens(argv))
|
||||
logging.basicConfig(
|
||||
level=logging.INFO, stream=sys.stderr,
|
||||
format="%(asctime)s %(levelname)s %(message)s",
|
||||
)
|
||||
capture_command = args.capture_command or _default_capture_command(args.format)
|
||||
server = FrameServer(
|
||||
args.socket,
|
||||
CommandCapture(capture_command),
|
||||
args.fps,
|
||||
fmt=_MIME[args.format],
|
||||
)
|
||||
_install_signal_handlers(server)
|
||||
try:
|
||||
server.serve_forever()
|
||||
except KeyboardInterrupt:
|
||||
server.stop()
|
||||
except OSError as exc:
|
||||
log.error("cannot serve on %s: %s", args.socket, exc)
|
||||
return 1
|
||||
return 0
|
||||
|
||||
|
||||
def _default_capture_command(fmt: str) -> list[str]:
|
||||
return ["grim", "-t", fmt, "-"]
|
||||
|
||||
|
||||
def _positive_int(text: str) -> int:
|
||||
value = int(text)
|
||||
if value <= 0:
|
||||
raise argparse.ArgumentTypeError(f"must be positive, got {text!r}")
|
||||
return value
|
||||
|
||||
|
||||
def _join_capture_tokens(argv: Iterable[str] | None) -> list[str] | None:
|
||||
"""Rewrite `--capture-command X` as `--capture-command=X`.
|
||||
|
||||
Capture tokens are argv tokens, and real ones start with a dash (`-t`, `-`
|
||||
in the default `grim -t png -`). argparse would read those as options, so
|
||||
the separated form is folded into the `=` form before it sees them.
|
||||
"""
|
||||
if argv is None:
|
||||
argv = sys.argv[1:]
|
||||
tokens = list(argv)
|
||||
out: list[str] = []
|
||||
i = 0
|
||||
while i < len(tokens):
|
||||
token = tokens[i]
|
||||
if token == "--": # everything after this is positional; leave it alone
|
||||
out.extend(tokens[i:])
|
||||
break
|
||||
if token == _CAPTURE_FLAG and i + 1 < len(tokens):
|
||||
out.append(f"{_CAPTURE_FLAG}={tokens[i + 1]}")
|
||||
i += 2
|
||||
continue
|
||||
out.append(token)
|
||||
i += 1
|
||||
return out
|
||||
|
||||
|
||||
def _install_signal_handlers(server: FrameServer) -> None:
|
||||
def handler(signum, _frame): # pragma: no cover - needs a real signal
|
||||
log.info("signal %d, shutting down", signum)
|
||||
server.stop()
|
||||
|
||||
for signum in (signal.SIGINT, signal.SIGTERM):
|
||||
try:
|
||||
signal.signal(signum, handler)
|
||||
except ValueError:
|
||||
pass # not the main thread (embedded in a test); nothing to do
|
||||
|
||||
|
||||
__all__ = ["FrameServer", "DEFAULT_SOCKET", "CaptureBackend", "CommandCapture",
|
||||
"socket", "build_parser", "main"]
|
||||
"socket", "build_parser", "main"]
|
||||
@@ -0,0 +1,307 @@
|
||||
#!/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())
|
||||
@@ -0,0 +1,89 @@
|
||||
#!/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())
|
||||
Executable
+109
@@ -0,0 +1,109 @@
|
||||
#!/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 "graphics devices"
|
||||
# The one piece of hardware a headless Hyprland still needs. A NixOS test
|
||||
# machine gets QEMU's default bochs-drm adapter, which gives a card0 and *no*
|
||||
# renderD*; aquamarine's headless backend wants a render node and aborts with
|
||||
# "CBackend::create() failed!" without one. So "card0 but no renderD128" here
|
||||
# is the signature of a machine that needs a virtio GPU in qemu.options.
|
||||
ls -l /dev/dri 2>&1 || echo "[no /dev/dri: this machine has no DRM device at all]"
|
||||
run cat /proc/fb
|
||||
|
||||
say "socket and runtime directories"
|
||||
ls -la /run/hyprland-headless-stream 2>&1 || echo "[no /run/hyprland-headless-stream]"
|
||||
ls -la /run/user 2>&1 || echo "[no /run/user]"
|
||||
for d in /run/user/*; do
|
||||
[ -d "$d" ] && ls -la "$d" 2>&1
|
||||
done
|
||||
|
||||
say "wayland socket vs WAYLAND_DISPLAY"
|
||||
# The other silent killer: the frame server waits for
|
||||
# $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY, so if the compositor bound a different
|
||||
# socket name the unit just sits in ExecStartPre until the test times out, with
|
||||
# a healthy compositor next to it. Print both names side by side.
|
||||
systemctl show -p Environment --value "$SERVICE_UNIT" 2>&1 \
|
||||
| tr ' ' '\n' | grep -E '^(WAYLAND_DISPLAY|XDG_RUNTIME_DIR)=' \
|
||||
|| echo "[no WAYLAND_DISPLAY/XDG_RUNTIME_DIR in the unit environment]"
|
||||
for d in /run/hyprland-headless-stream /run/user/*; do
|
||||
[ -d "$d" ] || continue
|
||||
found_sock=$(find "$d" -xdev -maxdepth 1 -name 'wayland-*' ! -name '*.lock' 2>/dev/null)
|
||||
if [ -n "$found_sock" ]; then
|
||||
echo "bound sockets in $d: $found_sock"
|
||||
else
|
||||
echo "bound sockets in $d: [none]"
|
||||
fi
|
||||
done
|
||||
|
||||
say "hyprland logs"
|
||||
# hyprland.log lives beside the compositor's IPC sockets; -xdev keeps this out
|
||||
# of /nix/store and /proc.
|
||||
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
|
||||
@@ -0,0 +1,262 @@
|
||||
"""Shared fixtures for the unit suite.
|
||||
|
||||
Two workstreams wrote fixtures for this directory (the server's own, and the
|
||||
test harness's); this file is the merge of both. Everything here is standard
|
||||
library. The tests never touch a socket outside their own ``tmp_path``, never
|
||||
spawn a compositor, and never read the host's configuration: the capture
|
||||
backend is an inline ``python3 -c`` program and the server is driven in-process.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import contextlib
|
||||
import os
|
||||
import pathlib
|
||||
import shutil
|
||||
import socket
|
||||
import struct
|
||||
import sys
|
||||
import tempfile
|
||||
import threading
|
||||
import zlib
|
||||
|
||||
import pytest
|
||||
|
||||
_HERE = pathlib.Path(__file__).resolve().parent
|
||||
_SRC = _HERE.parents[1] / "src"
|
||||
for _path in (str(_HERE), str(_SRC)):
|
||||
if _path not in sys.path:
|
||||
sys.path.insert(0, _path)
|
||||
|
||||
from hhstream.server import FrameServer # noqa: E402 (needs sys.path above)
|
||||
|
||||
#: The path named in docs/CONTRACT.md and in the module's option default.
|
||||
CONTRACT_SOCKET = "/run/hyprland-headless-stream/stream.sock"
|
||||
|
||||
# AF_UNIX addresses are capped near 108 bytes; a long tmp_path would fail with a
|
||||
# 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
|
||||
def tiny_png() -> bytes:
|
||||
return make_png()
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def workdir():
|
||||
"""A short-lived directory with a short path (AF_UNIX paths are ~108 bytes)."""
|
||||
path = tempfile.mkdtemp(prefix="hhs")
|
||||
try:
|
||||
yield pathlib.Path(path)
|
||||
finally:
|
||||
shutil.rmtree(path, ignore_errors=True)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def sock_path(workdir):
|
||||
path = str(workdir / "s.sock")
|
||||
if len(path) > SUN_PATH_MAX:
|
||||
pytest.skip(f"workdir too long for an AF_UNIX socket: {len(path)} bytes")
|
||||
return path
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def serve():
|
||||
"""`with serve(path, capture, fps=...) as server:` -- bound and listening."""
|
||||
started: list[tuple[FrameServer, threading.Thread]] = []
|
||||
|
||||
@contextlib.contextmanager
|
||||
def _serve(path, capture, fps=20, fmt="image/png"):
|
||||
server = FrameServer(path, capture, fps, fmt=fmt)
|
||||
thread = threading.Thread(target=server.serve_forever, daemon=True)
|
||||
started.append((server, thread))
|
||||
thread.start()
|
||||
assert server.ready.wait(5), "server never bound its socket"
|
||||
try:
|
||||
yield server
|
||||
finally:
|
||||
server.stop()
|
||||
thread.join(5)
|
||||
|
||||
yield _serve
|
||||
for server, thread in started:
|
||||
server.stop()
|
||||
thread.join(5)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def emit_bytes():
|
||||
"""Build an argv that writes exactly `data` to stdout and exits 0."""
|
||||
|
||||
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:
|
||||
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
||||
s.settimeout(timeout)
|
||||
s.connect(path)
|
||||
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
|
||||
def run_bg():
|
||||
"""Run a callable on a daemon thread and surface the exception it raised."""
|
||||
|
||||
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
|
||||
def socket_mode():
|
||||
def _mode(path: str) -> int:
|
||||
return os.stat(path).st_mode & 0o7777
|
||||
|
||||
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.
|
||||
"""
|
||||
|
||||
@contextlib.contextmanager
|
||||
def _rejects(*allowed: type[BaseException]):
|
||||
expected = allowed or (Exception,)
|
||||
try:
|
||||
yield
|
||||
except NotImplementedError as exc:
|
||||
raise AssertionError(
|
||||
"the code under test raised NotImplementedError, so it did not "
|
||||
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
|
||||
@@ -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())
|
||||
@@ -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()
|
||||
@@ -0,0 +1,116 @@
|
||||
"""The capture backend, driven by the fake capture command (no compositor)."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import sys
|
||||
|
||||
import pytest
|
||||
from helpers import FAKE_CAPTURE, png_bytes
|
||||
|
||||
from hhstream.capture import CaptureError, CommandCapture, image_size
|
||||
|
||||
|
||||
def fake(*flags: str) -> list[str]:
|
||||
return [*FAKE_CAPTURE, *flags]
|
||||
|
||||
|
||||
def test_grab_returns_the_frame_and_size_comes_from_its_header():
|
||||
capture = CommandCapture(fake("--width", "1280", "--height", "720"))
|
||||
frame = capture.grab()
|
||||
assert frame.startswith(b"\x89PNG\r\n\x1a\n")
|
||||
assert capture.size() == (1280, 720)
|
||||
|
||||
|
||||
def test_size_grabs_once_when_nothing_has_been_captured_yet():
|
||||
capture = CommandCapture(fake("--width", "64", "--height", "32"))
|
||||
assert capture.size() == (64, 32)
|
||||
|
||||
|
||||
def test_a_failing_command_raises_and_reports_its_stderr(capfd):
|
||||
capture = CommandCapture(fake("--fail", "--message", "grim: no outputs"))
|
||||
with pytest.raises(CaptureError) as excinfo:
|
||||
capture.grab()
|
||||
assert "exited 3" in str(excinfo.value)
|
||||
assert "grim: no outputs" in str(excinfo.value)
|
||||
out, err = capfd.readouterr()
|
||||
assert (out, err) == ("", ""), "the helper must not write to our stdio"
|
||||
|
||||
|
||||
def test_empty_output_is_a_failure_not_an_empty_frame(capfd):
|
||||
with pytest.raises(CaptureError) as excinfo:
|
||||
CommandCapture(fake("--empty")).grab()
|
||||
assert "no output" in str(excinfo.value)
|
||||
assert capfd.readouterr() == ("", "")
|
||||
|
||||
|
||||
def test_a_hanging_command_times_out():
|
||||
capture = CommandCapture(fake("--delay", "10"), timeout=0.5)
|
||||
with pytest.raises(CaptureError) as excinfo:
|
||||
capture.grab()
|
||||
assert "timed out" in str(excinfo.value)
|
||||
|
||||
|
||||
def test_a_missing_command_is_a_capture_error():
|
||||
with pytest.raises(CaptureError) as excinfo:
|
||||
CommandCapture(["hhstream-no-such-program"]).grab()
|
||||
assert "could not be run" in str(excinfo.value)
|
||||
|
||||
|
||||
def test_unmeasurable_output_cannot_produce_a_hello():
|
||||
capture = CommandCapture(fake("--garbage"))
|
||||
assert capture.grab() == b"fake_capture: not an image, sorry\n"
|
||||
with pytest.raises(CaptureError) as excinfo:
|
||||
capture.size()
|
||||
assert "pixel size" in str(excinfo.value)
|
||||
|
||||
|
||||
def test_a_failure_after_a_good_frame_keeps_the_known_size():
|
||||
good = CommandCapture(fake("--width", "100", "--height", "50"))
|
||||
assert good.size() == (100, 50)
|
||||
good.argv = fake("--fail")
|
||||
with pytest.raises(CaptureError):
|
||||
good.grab()
|
||||
assert good.size() == (100, 50)
|
||||
|
||||
|
||||
def test_env_is_overlaid_on_our_own_environment():
|
||||
argv = [sys.executable, "-c",
|
||||
"import os,sys;sys.stdout.write(os.environ['WAYLAND_DISPLAY']+':'+"
|
||||
"('PATH' in os.environ and 'haspath' or 'nopath'))"]
|
||||
capture = CommandCapture(argv, env={"WAYLAND_DISPLAY": "wayland-9"})
|
||||
assert capture.grab() == b"wayland-9:haspath"
|
||||
assert "WAYLAND_DISPLAY" not in os.environ, "our own environment was mutated"
|
||||
|
||||
|
||||
def test_empty_argv_and_bad_timeout_are_rejected_up_front():
|
||||
with pytest.raises(ValueError):
|
||||
CommandCapture([])
|
||||
with pytest.raises(ValueError):
|
||||
CommandCapture(["true"], timeout=0)
|
||||
|
||||
|
||||
def test_the_helpers_stdin_is_closed_so_it_cannot_steal_ours():
|
||||
code = ("import sys;"
|
||||
"sys.stdout.buffer.write(b'EMPTY' if not sys.stdin.read() else b'DATA')")
|
||||
assert CommandCapture([sys.executable, "-c", code]).grab() == b"EMPTY"
|
||||
|
||||
|
||||
@pytest.mark.parametrize("width,height", [(1, 1), (16, 9), (3840, 2160)])
|
||||
def test_image_size_reads_png_headers(width, height):
|
||||
assert image_size(png_bytes(width, height)) == (width, height)
|
||||
|
||||
|
||||
def test_image_size_reads_a_jpeg_sof_header():
|
||||
jpeg = (b"\xff\xd8"
|
||||
+ b"\xff\xe0" + (16).to_bytes(2, "big") + b"JFIF\x00" + b"\x00" * 9
|
||||
+ b"\xff\xc0" + (17).to_bytes(2, "big") + b"\x08"
|
||||
+ (720).to_bytes(2, "big") + (1280).to_bytes(2, "big")
|
||||
+ b"\x03" + b"\x00" * 9)
|
||||
assert image_size(jpeg) == (1280, 720)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("data", [b"", b"not an image", b"\x89PNG\r\n\x1a\n",
|
||||
b"\xff\xd8", b"\xff\xd8\xff\xc0\x00\x11"])
|
||||
def test_image_size_returns_none_when_it_cannot_tell(data):
|
||||
assert image_size(data) is None
|
||||
@@ -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"
|
||||
@@ -0,0 +1,147 @@
|
||||
"""The client, against the real server and against a hand-written stub server."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import contextlib
|
||||
import json
|
||||
import socket
|
||||
import threading
|
||||
|
||||
import pytest
|
||||
from helpers import FakeCapture, connect, distinct_frames
|
||||
|
||||
from hhstream import client, protocol
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def stub_server(path: str, payload: bytes):
|
||||
"""A server that writes exactly `payload` to one client, then hangs up."""
|
||||
listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
||||
listener.bind(path)
|
||||
listener.listen(1)
|
||||
|
||||
def run():
|
||||
try:
|
||||
conn, _ = listener.accept()
|
||||
except OSError:
|
||||
return
|
||||
with conn:
|
||||
try:
|
||||
conn.sendall(payload)
|
||||
except OSError:
|
||||
pass
|
||||
|
||||
thread = threading.Thread(target=run, daemon=True)
|
||||
thread.start()
|
||||
try:
|
||||
yield
|
||||
finally:
|
||||
listener.close()
|
||||
thread.join(5)
|
||||
|
||||
|
||||
def test_fetch_returns_the_payloads(sock_path, serve):
|
||||
frames = distinct_frames(30)
|
||||
with serve(sock_path, FakeCapture(frames=frames), fps=50):
|
||||
got = client.fetch(sock_path, count=3, timeout=5)
|
||||
assert len(got) == 3
|
||||
assert all(payload in frames for payload in got)
|
||||
|
||||
|
||||
def test_read_stream_also_returns_the_hello(sock_path, serve):
|
||||
with serve(sock_path, FakeCapture(frames=distinct_frames(5)), fps=25):
|
||||
hello, frames = client.read_stream(sock_path, count=1, timeout=5)
|
||||
assert hello == {"magic": "HHS1", "width": 1280, "height": 720,
|
||||
"format": "image/png", "fps": 25}
|
||||
assert len(frames) == 1
|
||||
|
||||
|
||||
def test_fetch_returns_fewer_frames_when_the_server_hangs_up(sock_path):
|
||||
wire = protocol.hello(4, 2, "image/png", 1) + protocol.frame(b"only one")
|
||||
with stub_server(sock_path, wire):
|
||||
assert client.fetch(sock_path, count=5, timeout=5) == [b"only one"]
|
||||
|
||||
|
||||
def test_fetch_on_a_missing_socket_raises_oserror(sock_path):
|
||||
with pytest.raises(OSError):
|
||||
client.fetch(sock_path, count=1, timeout=1)
|
||||
|
||||
|
||||
def test_fetch_rejects_a_bad_hello(sock_path):
|
||||
with stub_server(sock_path, b'{"magic":"NOPE"}\n'):
|
||||
with pytest.raises(ValueError):
|
||||
client.fetch(sock_path, count=1, timeout=5)
|
||||
|
||||
|
||||
def test_fetch_rejects_a_truncated_frame(sock_path):
|
||||
wire = protocol.hello(4, 2, "image/png", 1) + b"100\nshort"
|
||||
with stub_server(sock_path, wire):
|
||||
with pytest.raises(EOFError):
|
||||
client.fetch(sock_path, count=1, timeout=5)
|
||||
|
||||
|
||||
# -- the CLI -------------------------------------------------------------
|
||||
|
||||
def test_main_prints_the_hello_and_writes_one_frame(sock_path, serve, workdir, capsys):
|
||||
frames = distinct_frames(5)
|
||||
with serve(sock_path, FakeCapture(frames=frames), fps=25):
|
||||
out = workdir / "frame.png"
|
||||
assert client.main(["--socket", sock_path, "--count", "1",
|
||||
"--out", str(out), "--timeout", "5"]) == 0
|
||||
printed = capsys.readouterr().out.splitlines()
|
||||
assert json.loads(printed[0])["magic"] == "HHS1"
|
||||
assert f"-> {out}" in printed[1]
|
||||
assert out.read_bytes() in frames
|
||||
|
||||
|
||||
def test_main_suffixes_the_output_when_count_is_more_than_one(sock_path, serve,
|
||||
workdir, capsys):
|
||||
with serve(sock_path, FakeCapture(frames=distinct_frames(20)), fps=50):
|
||||
assert client.main(["--socket", sock_path, "--count", "2",
|
||||
"--out", str(workdir / "shot.png"), "--timeout", "5"]) == 0
|
||||
assert (workdir / "shot-1.png").exists()
|
||||
assert (workdir / "shot-2.png").exists()
|
||||
assert not (workdir / "shot.png").exists()
|
||||
assert len(capsys.readouterr().out.splitlines()) == 3 # hello + two frames
|
||||
|
||||
|
||||
def test_main_writes_payloads_to_stdout_with_out_dash(sock_path, serve, capsysbinary):
|
||||
frame = distinct_frames(1)[0]
|
||||
with serve(sock_path, FakeCapture(frames=[frame]), fps=25):
|
||||
assert client.main(["--socket", sock_path, "--count", "2", "--out", "-",
|
||||
"--timeout", "5"]) == 0
|
||||
captured = capsysbinary.readouterr()
|
||||
assert captured.out == frame * 2, "payloads must be the only thing on stdout"
|
||||
assert b'"magic":"HHS1"' in captured.err
|
||||
|
||||
|
||||
def test_main_reports_a_missing_socket_without_a_traceback(sock_path, capsys):
|
||||
assert client.main(["--socket", sock_path, "--timeout", "1"]) == 1
|
||||
assert "hhstream-client:" in capsys.readouterr().err
|
||||
|
||||
|
||||
def test_main_reports_a_short_stream(sock_path, capsys):
|
||||
wire = protocol.hello(4, 2, "image/png", 1) + protocol.frame(b"one")
|
||||
with stub_server(sock_path, wire):
|
||||
assert client.main(["--socket", sock_path, "--count", "3",
|
||||
"--timeout", "5"]) == 1
|
||||
assert "wanted 3 frames, got 1" in capsys.readouterr().err
|
||||
|
||||
|
||||
def test_main_rejects_a_negative_count(sock_path, capsys):
|
||||
assert client.main(["--socket", sock_path, "--count", "-1"]) == 2
|
||||
assert "--count" in capsys.readouterr().err
|
||||
|
||||
|
||||
def test_default_socket_matches_the_contract():
|
||||
assert client.DEFAULT_SOCKET == "/run/hyprland-headless-stream/stream.sock"
|
||||
assert client.build_parser().parse_args([]).socket == client.DEFAULT_SOCKET
|
||||
|
||||
|
||||
def test_a_client_can_be_interrupted_without_disturbing_the_server(sock_path, serve):
|
||||
"""Two sequential fetches: the first client's exit leaves the socket usable."""
|
||||
with serve(sock_path, FakeCapture(frames=distinct_frames(40)), fps=50):
|
||||
assert len(client.fetch(sock_path, count=2, timeout=5)) == 2
|
||||
conn = connect(sock_path)
|
||||
conn.close() # leave mid-stream
|
||||
assert len(client.fetch(sock_path, count=2, timeout=5)) == 2
|
||||
@@ -0,0 +1,38 @@
|
||||
"""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"
|
||||
@@ -0,0 +1,186 @@
|
||||
"""The framing. Other people's clients depend on these bytes being exact."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import io
|
||||
import json
|
||||
|
||||
import pytest
|
||||
|
||||
from hhstream import MAGIC, protocol
|
||||
|
||||
|
||||
# -- 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_round_trip():
|
||||
line = protocol.hello(640, 480, "image/jpeg", 15)
|
||||
assert line.endswith(b"\n") and line.count(b"\n") == 1
|
||||
assert protocol.parse_hello(line) == {
|
||||
"magic": MAGIC, "width": 640, "height": 480,
|
||||
"format": "image/jpeg", "fps": 15,
|
||||
}
|
||||
|
||||
|
||||
def test_parse_hello_tolerates_a_missing_trailing_newline():
|
||||
line = protocol.hello(8, 8, "image/png", 1)
|
||||
assert protocol.parse_hello(line.rstrip(b"\n")) == protocol.parse_hello(line)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("width,height,fps", [(0, 720, 30), (1280, 0, 30),
|
||||
(1280, 720, 0), (-1, 720, 30)])
|
||||
def test_hello_refuses_a_zero_or_negative_size(width, height, fps):
|
||||
with pytest.raises(ValueError):
|
||||
protocol.hello(width, height, "image/png", fps)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("payload", [
|
||||
b"",
|
||||
b"not json at all",
|
||||
b"[1,2,3]",
|
||||
b'"a string"',
|
||||
b'{"magic":"HHS0","width":1,"height":1,"format":"image/png","fps":1}',
|
||||
b'{"width":1,"height":1,"format":"image/png","fps":1}',
|
||||
b'{"magic":"HHS1","height":1,"format":"image/png","fps":1}',
|
||||
b'{"magic":"HHS1","width":1,"height":1,"fps":1}',
|
||||
b'{"magic":"HHS1","width":1,"height":1,"format":"image/png"}',
|
||||
b'{"magic":"HHS1","width":0,"height":1,"format":"image/png","fps":1}',
|
||||
b'{"magic":"HHS1","width":"1","height":1,"format":"image/png","fps":1}',
|
||||
b'{"magic":"HHS1","width":true,"height":1,"format":"image/png","fps":1}',
|
||||
b'{"magic":"HHS1","width":1,"height":1,"format":"","fps":1}',
|
||||
b'{"magic":"HHS1","width":1,"height":1,"format":"image/png","fps":1}\xff',
|
||||
])
|
||||
def test_parse_hello_rejects_bad_input(payload):
|
||||
with pytest.raises(ValueError):
|
||||
protocol.parse_hello(payload)
|
||||
|
||||
|
||||
def test_read_hello_then_frames_from_one_stream():
|
||||
stream = io.BytesIO(
|
||||
protocol.hello(2, 2, "image/png", 5) + protocol.frame(b"one") + protocol.frame(b"two")
|
||||
)
|
||||
assert protocol.read_hello(stream)["width"] == 2
|
||||
assert protocol.read_frame(stream) == b"one"
|
||||
assert protocol.read_frame(stream) == b"two"
|
||||
assert protocol.read_frame(stream) is None
|
||||
|
||||
|
||||
def test_read_hello_on_a_truncated_line():
|
||||
with pytest.raises(EOFError):
|
||||
protocol.read_hello(io.BytesIO(b'{"magic":"HHS1"'))
|
||||
|
||||
|
||||
def test_read_hello_gives_up_on_an_endless_line():
|
||||
with pytest.raises(ValueError):
|
||||
protocol.read_hello(_Endless(b"x"))
|
||||
|
||||
|
||||
# -- frames --------------------------------------------------------------
|
||||
|
||||
@pytest.mark.parametrize("payload", [
|
||||
b"",
|
||||
b"\n",
|
||||
b"a\nb",
|
||||
b"\n\n\n",
|
||||
b"12\n34", # payload that looks like a frame itself
|
||||
b"\x89PNG\r\n\x1a\n",
|
||||
bytes(range(256)),
|
||||
b"x" * (1 << 20),
|
||||
])
|
||||
def test_frame_round_trip(payload):
|
||||
wire = protocol.frame(payload)
|
||||
assert wire.startswith(str(len(payload)).encode("ascii") + b"\n")
|
||||
assert len(wire) == len(payload) + len(str(len(payload))) + 1
|
||||
assert protocol.read_frame(io.BytesIO(wire)) == payload
|
||||
|
||||
|
||||
def test_zero_length_frame_is_a_frame_not_an_eof():
|
||||
stream = io.BytesIO(protocol.frame(b"") + protocol.frame(b"after"))
|
||||
assert protocol.frame(b"") == b"0\n"
|
||||
assert protocol.read_frame(stream) == b""
|
||||
assert protocol.read_frame(stream) == b"after"
|
||||
|
||||
|
||||
def test_payload_containing_newlines_is_not_resplit():
|
||||
payload = b"row1\nrow2\n" * 500
|
||||
stream = io.BytesIO(protocol.frame(payload) + protocol.frame(b"next"))
|
||||
assert protocol.read_frame(stream) == payload
|
||||
assert protocol.read_frame(stream) == b"next"
|
||||
|
||||
|
||||
def test_length_prefix_has_no_leading_zeros_and_no_sign():
|
||||
assert protocol.frame(b"abc") == b"3\nabc"
|
||||
assert not protocol.frame(b"x" * 10).startswith(b"+")
|
||||
|
||||
|
||||
def test_read_frame_stops_exactly_at_the_end_of_the_payload():
|
||||
stream = io.BytesIO(protocol.frame(b"abc") + b"LEFTOVER")
|
||||
assert protocol.read_frame(stream) == b"abc"
|
||||
assert stream.read() == b"LEFTOVER"
|
||||
|
||||
|
||||
def test_clean_eof_between_frames_is_none():
|
||||
assert protocol.read_frame(io.BytesIO(b"")) is None
|
||||
|
||||
|
||||
@pytest.mark.parametrize("wire", [
|
||||
b"\nabc", # empty length prefix
|
||||
b"007\nabcdefg", # leading zero
|
||||
b"0012\n", # leading zeros
|
||||
b"12x\nabc", # not a digit
|
||||
b" 3\nabc", # leading space
|
||||
b"+3\nabc", # sign
|
||||
b"-3\nabc", # negative
|
||||
b"3.0\nabc", # not an integer
|
||||
b"1" * 21 + b"\n", # absurdly long prefix
|
||||
])
|
||||
def test_garbage_length_prefix_raises_value_error(wire):
|
||||
with pytest.raises(ValueError):
|
||||
protocol.read_frame(io.BytesIO(wire))
|
||||
|
||||
|
||||
@pytest.mark.parametrize("wire", [
|
||||
b"5\nabc", # payload short
|
||||
b"5\n", # payload absent
|
||||
b"1048576\n" + b"x" * 1000,
|
||||
b"12", # EOF inside the length prefix
|
||||
])
|
||||
def test_truncated_payload_raises_eof_error(wire):
|
||||
with pytest.raises(EOFError):
|
||||
protocol.read_frame(io.BytesIO(wire))
|
||||
|
||||
|
||||
def test_read_frame_gives_up_on_endless_digits_instead_of_hanging():
|
||||
with pytest.raises(ValueError):
|
||||
protocol.read_frame(_Endless(b"1"))
|
||||
|
||||
|
||||
def test_a_huge_length_prefix_does_not_preallocate():
|
||||
# 10**19 bytes is not going to arrive; we must notice the EOF, not the RAM.
|
||||
with pytest.raises(EOFError):
|
||||
protocol.read_frame(io.BytesIO(b"9999999999999999999\nshort"))
|
||||
|
||||
|
||||
def test_frame_rejects_non_bytes():
|
||||
with pytest.raises(ValueError):
|
||||
protocol.frame("a str is not bytes") # type: ignore[arg-type]
|
||||
|
||||
|
||||
def test_hello_is_valid_json_with_the_documented_field_order():
|
||||
line = protocol.hello(1280, 720, "image/png", 30).decode("utf-8")
|
||||
assert list(json.loads(line)) == ["magic", "width", "height", "format", "fps"]
|
||||
|
||||
|
||||
class _Endless:
|
||||
"""A stream that never ends and never blocks -- proves we bail out."""
|
||||
|
||||
def __init__(self, byte: bytes):
|
||||
self.byte = byte
|
||||
|
||||
def read(self, size: int = -1) -> bytes:
|
||||
return self.byte * (1 if size in (-1, None) else size)
|
||||
@@ -0,0 +1,253 @@
|
||||
"""The server's obligations from docs/CONTRACT.md, none of which need a GPU."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import socket
|
||||
import stat
|
||||
import threading
|
||||
import time
|
||||
|
||||
import pytest
|
||||
from helpers import (FAKE_CAPTURE, FakeCapture, abort, connect, distinct_frames,
|
||||
png_bytes)
|
||||
|
||||
from hhstream import protocol
|
||||
from hhstream.capture import CommandCapture
|
||||
from hhstream.server import FrameServer
|
||||
|
||||
HELLO_WAIT = 5.0
|
||||
|
||||
|
||||
def read_hello(conn, timeout=HELLO_WAIT):
|
||||
conn.settimeout(timeout)
|
||||
return protocol.read_hello(conn.makefile("rb"))
|
||||
|
||||
|
||||
def test_fps_must_be_positive(sock_path):
|
||||
for bad in (0, -1, True, 1.5):
|
||||
with pytest.raises(ValueError):
|
||||
FrameServer(sock_path, FakeCapture(), bad)
|
||||
|
||||
|
||||
def test_two_clients_each_get_their_own_hello_and_frames(sock_path, serve):
|
||||
capture = FakeCapture(frames=distinct_frames(20), size=(1280, 720))
|
||||
with serve(sock_path, capture, fps=30):
|
||||
first, second = connect(sock_path), connect(sock_path)
|
||||
streams = [first.makefile("rb"), second.makefile("rb")]
|
||||
hellos = [protocol.read_hello(s) for s in streams]
|
||||
assert hellos[0] == hellos[1] == {
|
||||
"magic": "HHS1", "width": 1280, "height": 720,
|
||||
"format": "image/png", "fps": 30,
|
||||
}
|
||||
for stream in streams:
|
||||
for _ in range(3):
|
||||
payload = protocol.read_frame(stream)
|
||||
assert payload and payload.startswith(b"\x89PNG\r\n\x1a\n")
|
||||
first.close()
|
||||
second.close()
|
||||
|
||||
|
||||
def test_a_client_arriving_later_is_served_too(sock_path, serve):
|
||||
with serve(sock_path, FakeCapture(frames=distinct_frames(50)), fps=50):
|
||||
early = connect(sock_path)
|
||||
early_stream = early.makefile("rb")
|
||||
protocol.read_hello(early_stream)
|
||||
assert protocol.read_frame(early_stream)
|
||||
time.sleep(0.3) # let a pile of frames go by
|
||||
late = connect(sock_path)
|
||||
late_stream = late.makefile("rb")
|
||||
assert protocol.read_hello(late_stream)["width"] == 1280
|
||||
assert protocol.read_frame(late_stream) # not made to wait for a backlog
|
||||
early.close()
|
||||
late.close()
|
||||
|
||||
|
||||
def test_a_stalled_client_does_not_block_another(sock_path, serve):
|
||||
"""Contract: a stalled client is slowed, not queued -- and it is alone."""
|
||||
big = png_bytes(1024, 1024, (1, 2, 3), level=0) # ~3 MiB, fills any buffer
|
||||
assert len(big) > 2 << 20
|
||||
with serve(sock_path, FakeCapture(frames=[big]), fps=20):
|
||||
stalled = connect(sock_path, rcvbuf=2048)
|
||||
assert read_hello(stalled)["width"] == 1280
|
||||
# ...and now `stalled` reads nothing at all, so the server's write to it
|
||||
# blocks part-way through a frame.
|
||||
time.sleep(0.5)
|
||||
|
||||
started = time.monotonic()
|
||||
healthy = connect(sock_path)
|
||||
stream = healthy.makefile("rb")
|
||||
assert protocol.read_hello(stream)["width"] == 1280
|
||||
assert len(protocol.read_frame(stream)) == len(big)
|
||||
assert len(protocol.read_frame(stream)) == len(big)
|
||||
assert time.monotonic() - started < HELLO_WAIT, "the stall spread"
|
||||
healthy.close()
|
||||
stalled.close()
|
||||
|
||||
|
||||
def test_frames_are_dropped_for_a_slow_client_not_queued(sock_path, serve):
|
||||
frames = distinct_frames(400)
|
||||
index_of = {payload: i for i, payload in enumerate(frames, start=1)}
|
||||
capture = FakeCapture(frames=frames)
|
||||
with serve(sock_path, capture, fps=100) as server:
|
||||
conn = connect(sock_path)
|
||||
stream = conn.makefile("rb")
|
||||
protocol.read_hello(stream)
|
||||
seen = []
|
||||
for _ in range(3):
|
||||
time.sleep(0.2) # far slower than 100 fps
|
||||
seen.append(index_of[protocol.read_frame(stream)])
|
||||
conn.close()
|
||||
assert server.frames_captured > len(seen) + 2, "capture did not outrun the client"
|
||||
assert seen == sorted(seen)
|
||||
assert seen[-1] > len(seen), f"frames were queued, not dropped: {seen}"
|
||||
|
||||
|
||||
def test_server_survives_a_client_dying_mid_frame(sock_path, serve):
|
||||
big = png_bytes(1024, 1024, (9, 9, 9), level=0)
|
||||
with serve(sock_path, FakeCapture(frames=[big]), fps=20) as server:
|
||||
doomed = connect(sock_path, rcvbuf=2048)
|
||||
stream = doomed.makefile("rb")
|
||||
assert protocol.read_hello(stream)["width"] == 1280
|
||||
assert len(stream.read(4096)) == 4096 # a fragment of the first frame
|
||||
abort(doomed) # torn down mid-frame, with an RST
|
||||
|
||||
survivor = connect(sock_path)
|
||||
survivor_stream = survivor.makefile("rb")
|
||||
assert protocol.read_hello(survivor_stream)["width"] == 1280
|
||||
assert len(protocol.read_frame(survivor_stream)) == len(big)
|
||||
survivor.close()
|
||||
assert server.ready.is_set()
|
||||
|
||||
|
||||
def test_server_survives_many_clients_connecting_and_vanishing(sock_path, serve):
|
||||
with serve(sock_path, FakeCapture(frames=distinct_frames(10)), fps=50):
|
||||
for _ in range(25):
|
||||
conn = connect(sock_path)
|
||||
protocol.read_hello(conn.makefile("rb"))
|
||||
abort(conn)
|
||||
survivor = connect(sock_path)
|
||||
stream = survivor.makefile("rb")
|
||||
assert protocol.read_hello(stream)["width"] == 1280
|
||||
assert protocol.read_frame(stream)
|
||||
survivor.close()
|
||||
|
||||
|
||||
def test_bytes_sent_by_a_client_are_read_and_ignored(sock_path, serve):
|
||||
with serve(sock_path, FakeCapture(frames=distinct_frames(10)), fps=30):
|
||||
conn = connect(sock_path)
|
||||
conn.sendall(b"v2 control channel?\n" * 500)
|
||||
stream = conn.makefile("rb")
|
||||
assert protocol.read_hello(stream)["magic"] == "HHS1"
|
||||
assert protocol.read_frame(stream)
|
||||
conn.sendall(b"more chatter")
|
||||
assert protocol.read_frame(stream)
|
||||
conn.close()
|
||||
|
||||
|
||||
def test_capture_failure_keeps_the_server_up_and_holds_the_hello(sock_path, serve,
|
||||
workdir):
|
||||
"""Contract: no compositor -> keep the socket up, retry, send no Hello yet."""
|
||||
gate = workdir / "gate"
|
||||
capture = CommandCapture(
|
||||
[*FAKE_CAPTURE, "--gate", str(gate), "--width", "800", "--height", "600"],
|
||||
timeout=10,
|
||||
)
|
||||
with serve(sock_path, capture, fps=20) as server:
|
||||
waiting = connect(sock_path, timeout=1.0)
|
||||
with pytest.raises(TimeoutError):
|
||||
protocol.read_hello(waiting.makefile("rb"))
|
||||
assert server.capture_failures > 0
|
||||
assert server.frames_captured == 0
|
||||
waiting.close()
|
||||
|
||||
gate.write_text("the compositor is up now\n")
|
||||
recovered = connect(sock_path)
|
||||
stream = recovered.makefile("rb")
|
||||
hello = protocol.read_hello(stream)
|
||||
assert (hello["width"], hello["height"]) == (800, 600)
|
||||
assert protocol.read_frame(stream).startswith(b"\x89PNG\r\n\x1a\n")
|
||||
recovered.close()
|
||||
assert server.frames_captured > 0
|
||||
|
||||
|
||||
def test_capture_failing_in_the_middle_does_not_break_the_stream(sock_path, serve):
|
||||
capture = FakeCapture(frames=distinct_frames(10))
|
||||
with serve(sock_path, capture, fps=50) as server:
|
||||
conn = connect(sock_path)
|
||||
stream = conn.makefile("rb")
|
||||
protocol.read_hello(stream)
|
||||
assert protocol.read_frame(stream)
|
||||
capture.fail_until = capture.calls + 20 # a burst of failures
|
||||
time.sleep(0.3)
|
||||
assert server.capture_failures >= 1
|
||||
assert protocol.read_frame(stream) # recovers without a reconnect
|
||||
conn.close()
|
||||
|
||||
|
||||
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()
|
||||
Reference in new issue
Block a user