Compare commits

..
Author SHA1 Message Date
Hermenix 15d96e7cda spike: grim-rs capture producer for the frozen harness
Long-lived zwlr-screencopy client (grim-rs 0.2.0, shm only) that prints
the contract JSON. Rust stays in a spike-local shell, not the repo flake.
2026-10-11 14:42:44 +00:00
ari f3ac9ada27 Merge pull request 'Keyboard input for sessions: typing on the compositor's one seat' (#1) from feat/keyboard-input into main
Reviewed-on: http://gitea.app.internal:3000/Hermenix/hyprland-headless-stream-plugin/pulls/1
2026-10-11 05:10:29 +00:00
HermenixandClaude Opus 5 443efd8da8 docs(dev): register vm-keyboard and vm-keyboard-de where a reader looks
The keyboard checks were in `README.dev.md`'s `checks/` layout listing and
nowhere else: not in the table of what each check proves, and not in the
one-at-a-time `nix build -L` list that the same section tells you to use
instead of `nix flake check`. So the two checks this branch adds were
invisible exactly where someone goes to find out what is gated and how to
run it, while `vm-stream-firewall` (from main) was in all three places.

Four lines, no behaviour. The table rows state what each run actually
asserts, taken from `checks/vm-keyboard.nix`'s header and its
`expectations` attrset rather than paraphrased:

  * `vm-keyboard` -- the uploaded keymap reaching a real compositor,
    `pointer acquire` leaving the aimed window holding the keyboard and
    not merely the cursor, and `hhs-keyboard-target` decoding `hello`
    from the keymap it was forwarded. The mutation is named, because it
    is the point of the victim decoding rather than counting keycodes: a
    driver that stopped uploading a keymap leaves every key arriving as
    `sym=?`.

  * `vm-keyboard-de` -- why one file is exposed twice, which is that
    `sessions.keyboard.layout` reaches the keymap only through
    `--xkb-layout` on the driver unit and a single-layout run cannot
    tell that path from a hardcoded `us`. The three differences it
    pins: keysym `y`'s evdev code (21 against 44), the forwarded
    `symbols=` name, and `ü` going from exit 2 to `udiaeresis`.

Both rows say `yes` under "Needs a VM", and the build lines sit between
`vm-pointer` and `vm-stream-firewall` so the list keeps the order the
layout listing and `checks/default.nix` already use.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PjpHyir6hxyjdw2o1RwQmn
2026-10-11 03:06:08 +00:00
HermenixandClaude Opus 5 5f94833a76 Merge origin/main into feat/keyboard-input: keep both the stream and the
keyboard sides

origin/main brought the session live-stream feature (stage 1): the
`hhstream_live` router, its phrase generator and wordlist, the
`sessions.stream.*` module options with their loopback-vs-openFirewall
assertion and the one firewall port, the `vm-stream-firewall` check, and
`tests/live/`. This branch adds keyboard input: the `key`/`type` ops, the
uploaded XKB keymap, `sessions.keyboard.{layout,model,variant,options}`
and the four `--xkb-*` flags on the driver unit, `vm-keyboard` and
`vm-keyboard-de`, and their docs.

The two features are independent, so every conflict wanted both sides.
Four files, resolved as follows.

checks/default.nix -- both the header list and the attribute set take all
three new checks: `vm-keyboard`, `vm-keyboard-de` (the same file with
`keyboardLayout = "de"`, because the layout reaches the keymap only
through the driver unit's argv) and `vm-stream-firewall`, which stays a
non-`sessionArgs` consumer with main's comment saying why. Neither side's
check list is reduced; the flake now exposes ten.

nix/package.nix -- one `pythonImportsCheck` list with both sides' entries:
`hhstream_pointer.keymap` and the vendored
`virtual_keyboard_unstable_v1` from here, `hhstream_live.server` from
main. The surrounding hunks were not in conflict, so the branch's
xkbcommon dependency and main's wordlist `postFixup` both survive, and
both ran in this merge's `checks.unit` build (`wordlist ok: 7772 words`).

nix/module.nix -- the sole conflict was textual: both sides open a new
sub-option block immediately after `sessions.pointer`. Both blocks are
kept, `keyboard` then `stream`, each with its own closing. Everything
else in the file merged cleanly, so `loopbackBinds`, the
openFirewall-on-loopback assertion and
`networking.firewall.allowedTCPPorts` are present alongside the driver
unit's `--xkb-layout`/`--xkb-model`/`--xkb-variant`/`--xkb-options`.

README.dev.md -- the `checks/` layout listing keeps both entries in the
file's existing order, `vm-keyboard.nix` then `vm-stream-firewall.nix`.

Verified: `nix flake check --no-build` evaluates every output green, and
`nix build .#checks.x86_64-linux.unit` passes -- 977 passed, 2 skipped,
0 failed, over both sides' suites. The VM checks were not run (they boot
a software-rendered compositor and must run one at a time).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PjpHyir6hxyjdw2o1RwQmn
2026-10-11 02:57:55 +00:00
ari c6cfd02bf3 Merge pull request 'Session live stream: one port, a router, and a phrase per session (stage 1)' (#2) from feat/session-live-stream-webapp into main
Reviewed-on: http://gitea.app.internal:3000/Hermenix/hyprland-headless-stream-plugin/pulls/2
2026-10-11 02:42:39 +00:00
ari 4461660c6d Merge branch 'main' into feat/session-live-stream-webapp 2026-10-11 02:42:25 +00:00
ari 934774f15e fixing a test 2026-10-09 11:32:42 -04:00
12 changed files with 2491 additions and 78 deletions

No files matched your search

+1
View File
@@ -0,0 +1 @@
use flake
+5 -1
View File
@@ -48,6 +48,8 @@ and the pointer driver.
| `vm-ipc` | the **compositor's IPC**: both sockets exist at the names `docs/CONTRACT-sessions.md` §5 freezes and fit inside `sun_path`, `hyprctl` answers, the broker's own `HyprlandIPC` reaches it, and a subscriber on the **event** socket receives an `openwindow` for a window the test creates | yes |
| `vm-containers` | one `hh-*` output per session at the container mode, the application's window on it, a second window of the same application beside it, an unmatched window **quarantined**, `grim -o` capturing that container alone, and teardown removing the output and freeing its workspace slot | yes |
| `vm-pointer` | the **lease and the driver**: a version-2 virtual pointer, a warp that lands where it was aimed *as the application reports it*, a click delivered as one press and one release, a contended acquire refused with BUSY, an expired lease swept with its held button lifted, and a broker restart that leaves the lock free, the bookmark intact and the driver reachable | yes |
| `vm-keyboard` | the **keymap, the focus and a decoded symbol**: the keymap the driver uploads reaching a real compositor, `pointer acquire` leaving the aimed window holding the *keyboard* and not merely the cursor, and `hhs-keyboard-target` decoding `hello` from the keymap it was **forwarded** — so a driver that stopped uploading one arrives as `sym=?` and goes red | yes |
| `vm-keyboard-de` | the same file with `sessions.keyboard.layout = "de"`, because that option reaches the uploaded keymap through exactly one path — `--xkb-layout` on the driver unit — and a single-layout check cannot tell that path from a hardcoded `us`: keysym `y`'s evdev code swaps (21 against 44), the forwarded `symbols=` name with it, and `ü` goes from exit 2 to `udiaeresis` | yes |
| `vm-stream-firewall` | the stream's **port**: the guest's own running firewall accepts the configured port and not the module's default, a peer outside the guest reaches it, and is refused on a port beside it that was never opened | yes |
All of them at once:
@@ -70,6 +72,8 @@ nix build -L .#checks.x86_64-linux.vm-sessions
nix build -L .#checks.x86_64-linux.vm-ipc
nix build -L .#checks.x86_64-linux.vm-containers
nix build -L .#checks.x86_64-linux.vm-pointer
nix build -L .#checks.x86_64-linux.vm-keyboard
nix build -L .#checks.x86_64-linux.vm-keyboard-de
nix build -L .#checks.x86_64-linux.vm-stream-firewall
```
@@ -221,11 +225,11 @@ checks/
vm-ipc.nix nixosTest, the compositor's request and event sockets
vm-containers.nix nixosTest, one output and one workspace per session
vm-pointer.nix nixosTest, the lease, the driver and a click that lands
vm-stream-firewall.nix nixosTest, the stream's port in the guest's firewall
vm-keyboard.nix nixosTest, the uploaded keymap, keyboard focus, and a
symbol a client decoded. Exposed TWICE -- `vm-keyboard`
(layout us) and `vm-keyboard-de` -- because the layout
reaches the keymap only through the driver unit's argv
vm-stream-firewall.nix nixosTest, the stream's port in the guest's firewall
lib/test-tools.nix packages the tests/ helpers for the guest
lib/session-tools.nix packages the two guest programs below
lib/session-machine.nix the guest the three session checks share
+7 -6
View File
@@ -7,9 +7,9 @@
# vm-ipc -- the compositor's IPC sockets, and an event that arrives
# vm-containers -- one output and one workspace per session
# vm-pointer -- the lease, the driver, and a click the application saw
# vm-stream-firewall -- the stream's port in the guest's own running firewall
# vm-keyboard -- the uploaded keymap, keyboard focus, and a decoded symbol
# vm-keyboard-de -- the same check with sessions.keyboard.layout = "de"
# vm-stream-firewall -- the stream's port in the guest's own running firewall
#
# What the guests need lives in checks/lib: `test-tools.nix` for the fake
# capture and the contract asserter, `session-tools.nix` for the event
@@ -62,14 +62,15 @@ in
vm-pointer = pkgs.callPackage ./vm-pointer.nix sessionArgs;
# Not a `sessionArgs` consumer: this one is about the module's own options,
# not about the broker or the compositor (see the file's header).
vm-stream-firewall = pkgs.callPackage ./vm-stream-firewall.nix {
inherit hhstream hhsModule testTools;
};
vm-keyboard = pkgs.callPackage ./vm-keyboard.nix sessionArgs;
vm-keyboard-de = pkgs.callPackage ./vm-keyboard.nix (
sessionArgs // { keyboardLayout = "de"; }
);
# Not a `sessionArgs` consumer: this one is about the module's own options,
# not about the broker or the compositor (see the file's header).
vm-stream-firewall = pkgs.callPackage ./vm-stream-firewall.nix {
inherit hhstream hhsModule testTools;
};
}
+57 -57
View File
@@ -625,63 +625,6 @@ in {
};
};
# The session-stream web app — `hhstream-live`, the router that serves a
# live view of one session per phrase, over one port
# (`docs/plans/2026-10-04-session-stream-webapp.md`).
#
# Only the *reach* of it is declared here so far: the port every stream
# shares, the address it will bind, and whether that port is opened in
# the firewall. The unit that runs the app, the phrases the broker keeps
# in its records and the `session stream enable` verbs are later stages
# of that plan — and deliberately so: a stream is switched on per
# session, never for all of them, so nothing here turns one on.
stream = {
port = lib.mkOption {
type = lib.types.port;
default = 9988;
description = ''
The single TCP port every stream shares.
One listener rather than one per session is what makes the phrase
speakable: there is one address to give a person, one thing to
firewall and one thing to stop. It is also why this is a fixed
number with no range to fall back on — a stream at a port nobody
was told about is worse than a stream that is down, so a taken port
fails loudly instead of moving.
'';
};
bind = lib.mkOption {
type = lib.types.str;
default = "127.0.0.1";
description = ''
The address the web app will bind.
Loopback by default, where the reachable path is an ssh tunnel
(`ssh -L 9988:127.0.0.1:9988`) and nothing else. Set it to an
address a peer can reach (`"0.0.0.0"`) when
{option}`sessions.stream.openFirewall` is set: opening the port for
a listener that is not on it is a hole with no service behind it,
which is why that pairing is refused rather than allowed.
'';
};
openFirewall = lib.mkOption {
type = lib.types.bool;
default = false;
description = ''
Open {option}`sessions.stream.port` in the firewall.
Off by default, and deliberately not implied by
{option}`sessions.enable`: a live view of this desktop is readable
by anyone who can reach the port, and the phrase in the URL is its
only credential — no TLS, no second factor
(`docs/plans/2026-10-04-…` §4). Opening it is an explicit act, and
it opens exactly one port.
'';
};
};
# The keyboard has no `enable` of its own: it is the same unit, the same
# process and the same lease as the pointer (`hhstream session keyboard
# …` refuses with exit 9 until `pointer acquire`). What it needs from an
@@ -756,6 +699,63 @@ in {
};
};
# The session-stream web app — `hhstream-live`, the router that serves a
# live view of one session per phrase, over one port
# (`docs/plans/2026-10-04-session-stream-webapp.md`).
#
# Only the *reach* of it is declared here so far: the port every stream
# shares, the address it will bind, and whether that port is opened in
# the firewall. The unit that runs the app, the phrases the broker keeps
# in its records and the `session stream enable` verbs are later stages
# of that plan — and deliberately so: a stream is switched on per
# session, never for all of them, so nothing here turns one on.
stream = {
port = lib.mkOption {
type = lib.types.port;
default = 9988;
description = ''
The single TCP port every stream shares.
One listener rather than one per session is what makes the phrase
speakable: there is one address to give a person, one thing to
firewall and one thing to stop. It is also why this is a fixed
number with no range to fall back on — a stream at a port nobody
was told about is worse than a stream that is down, so a taken port
fails loudly instead of moving.
'';
};
bind = lib.mkOption {
type = lib.types.str;
default = "127.0.0.1";
description = ''
The address the web app will bind.
Loopback by default, where the reachable path is an ssh tunnel
(`ssh -L 9988:127.0.0.1:9988`) and nothing else. Set it to an
address a peer can reach (`"0.0.0.0"`) when
{option}`sessions.stream.openFirewall` is set: opening the port for
a listener that is not on it is a hole with no service behind it,
which is why that pairing is refused rather than allowed.
'';
};
openFirewall = lib.mkOption {
type = lib.types.bool;
default = false;
description = ''
Open {option}`sessions.stream.port` in the firewall.
Off by default, and deliberately not implied by
{option}`sessions.enable`: a live view of this desktop is readable
by anyone who can reach the port, and the phrase in the URL is its
only credential — no TLS, no second factor
(`docs/plans/2026-10-04-…` §4). Opening it is an explicit act, and
it opens exactly one port.
'';
};
};
stateDir = lib.mkOption {
type = lib.types.str;
default = "/var/lib/hhstream";
+1 -1
View File
@@ -34,10 +34,10 @@ python3.pkgs.buildPythonApplication {
"hhstream_pointer.ops"
"hhstream_pointer.keymap"
"hhstream_pointer._protocol.wlr_virtual_pointer_unstable_v1"
"hhstream_pointer._protocol.virtual_keyboard_unstable_v1"
# The web app: importing the server pulls in the router, the publisher and
# the pages.
"hhstream_live.server"
"hhstream_pointer._protocol.virtual_keyboard_unstable_v1"
];
# `pythonImportsCheck` only *imports*, and `hhstream_live.phrase` reads its
@@ -0,0 +1 @@
/target
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,16 @@
[package]
name = "grimrs-capture"
version = "0.1.0"
edition = "2021"
publish = false
description = "Long-lived grim-rs capture producer for the frozen HARNESS.md contract"
[[bin]]
name = "grimrs-capture"
path = "src/main.rs"
[dependencies]
# Exact: the raw-mode stop point depends on what 0.2.0 does inside capture_*.
grim-rs = "=0.2.0"
libc = "0.2"
serde_json = { version = "1", features = ["preserve_order"] }
+53
View File
@@ -0,0 +1,53 @@
#!/bin/sh
# Eight measured cells, still screen, two runs each.
# Stdout of each cell is one JSON line. Progress goes to runs/progress.log.
# Does not set XDG_RUNTIME_DIR. The caller must export WAYLAND_DISPLAY to the
# absolute socket path.
set -u
cd "$(dirname "$0")"
if [ "${WAYLAND_DISPLAY:-}" != "/run/hypr-stream/wayland-1" ]; then
echo "WAYLAND_DISPLAY must be /run/hypr-stream/wayland-1" >&2
exit 2
fi
if [ "${XDG_RUNTIME_DIR:-}" = "/run/hypr-stream" ]; then
echo "refusing XDG_RUNTIME_DIR=/run/hypr-stream" >&2
exit 2
fi
OUTPUT=${1:?usage: run-cells.sh OUTPUT_NAME}
BIN=./target/release/grimrs-capture
if [ ! -x "$BIN" ]; then
echo "missing $BIN; build with nix-shell --run 'cargo build --release'" >&2
exit 2
fi
mkdir -p runs
LOG=runs/progress.log
: > "$LOG"
# The frame server is a system unit. Do not stop it. Record that it was
# capturing during the run so the numbers are not read as an idle compositor.
ps -eo pid,user,cmd > runs/ps-at-start.txt
echo "BEGIN runner $(date -Is) WAYLAND_DISPLAY=$WAYLAND_DISPLAY XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR-}" >> "$LOG"
fail=0
run() {
name=$1
shift
echo "BEGIN $name $(date -Is)" >> "$LOG"
start=$(date +%s)
"$BIN" "$@" > "runs/$name.stdout" 2> "runs/$name.stderr"
rc=$?
end=$(date +%s)
echo "END $name rc=$rc elapsed=$((end - start)) $(date -Is)" >> "$LOG"
if [ "$rc" -ne 0 ]; then
echo "CELL_FAIL $name rc=$rc" >> "$LOG"
fail=1
fi
}
run output-raw-1 --output "$OUTPUT" --frames 300 --warmup 10 --mode raw --json
run output-raw-2 --output "$OUTPUT" --frames 300 --warmup 10 --mode raw --json
run output-jpeg-1 --output "$OUTPUT" --frames 300 --warmup 10 --mode jpeg --json
run output-jpeg-2 --output "$OUTPUT" --frames 300 --warmup 10 --mode jpeg --json
run all-raw-1 --all --frames 300 --warmup 10 --mode raw --json
run all-raw-2 --all --frames 300 --warmup 10 --mode raw --json
run all-jpeg-1 --all --frames 300 --warmup 10 --mode jpeg --json
run all-jpeg-2 --all --frames 300 --warmup 10 --mode jpeg --json
echo "ALL_DONE fail=$fail $(date -Is)" >> "$LOG"
exit "$fail"
@@ -0,0 +1,13 @@
# Spike-local toolchain for route 001a. Rust stays out of the repository flake
# on purpose: this shell is the only place this spike gets rustc and cargo.
#
# Do not set WAYLAND_DISPLAY or XDG_RUNTIME_DIR here. The run commands in
# README.md set WAYLAND_DISPLAY to the absolute socket path. Pointing
# XDG_RUNTIME_DIR at /run/hypr-stream makes libwayland reject the runtime dir.
{ pkgs ? import <nixpkgs> { } }:
pkgs.mkShell {
packages = with pkgs; [
rustc # 1.98 from the machine's nixpkgs
cargo
];
}
@@ -0,0 +1,641 @@
//! Long-lived capture producer for the frozen measurement contract.
//!
//! One Wayland connection (`Grim::new_wlr`, so the crate cannot pick
//! `ext-image-copy-capture-v1`), then warmup frames, then N measured frames.
//! Stdout is exactly one JSON object, on the last line. Everything else goes
//! to stderr.
use std::env;
use std::io::{self, Write};
use std::process::ExitCode;
use std::time::Instant;
use grim_rs::Grim;
const ROUTE: &str = "grim-rs";
const JPEG_QUALITY: u8 = 80;
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum Mode {
Raw,
Jpeg,
}
impl Mode {
fn as_str(self) -> &'static str {
match self {
Mode::Raw => "raw",
Mode::Jpeg => "jpeg",
}
}
}
#[derive(Clone, Debug)]
enum Target {
Output(String),
All,
}
impl Target {
fn label(&self) -> &str {
match self {
Target::Output(name) => name,
Target::All => "all",
}
}
}
struct Args {
target: Target,
frames: u32,
warmup: u32,
mode: Mode,
}
struct Held {
width: u32,
height: u32,
/// JPEG byte length. `None` in raw mode.
jpeg_len: Option<usize>,
/// Pixel or JPEG bytes. Kept alive until the caller drops it, so the
/// frame timer can stop when the bytes are complete and not when they
/// are freed.
bytes: Vec<u8>,
}
fn main() -> ExitCode {
match run() {
Ok(()) => ExitCode::SUCCESS,
Err(err) => {
eprintln!("grimrs-capture: {err}");
ExitCode::from(1)
}
}
}
fn run() -> Result<(), String> {
let args = parse_args(env::args().skip(1))?;
// Absolute WAYLAND_DISPLAY is required. Leaving XDG_RUNTIME_DIR alone is
// also required: this process does not own /run/hypr-stream.
match env::var("WAYLAND_DISPLAY") {
Ok(value) if !value.is_empty() => {}
_ => {
return Err(
"WAYLAND_DISPLAY is empty. Set it to the absolute socket \
path /run/hypr-stream/wayland-1 and do not set \
XDG_RUNTIME_DIR=/run/hypr-stream"
.to_string(),
);
}
}
if env::var("XDG_RUNTIME_DIR").ok().as_deref() == Some("/run/hypr-stream") {
return Err(
"XDG_RUNTIME_DIR=/run/hypr-stream is set. Unset it; libwayland \
refuses a runtime dir the caller does not own"
.to_string(),
);
}
// Force zwlr-screencopy. Grim::new() prefers ext-image-copy-capture-v1,
// which is the dma-buf-capable path this machine must not take.
let mut grim = Grim::new_wlr().map_err(|err| {
format!(
"Grim::new_wlr failed ({err}). Refusing to fall back to \
ext-image-copy-capture-v1"
)
})?;
let outputs = grim.get_outputs().map_err(|err| err.to_string())?;
if outputs.is_empty() {
return Err("compositor advertised no outputs".to_string());
}
let layout = describe_outputs(&outputs);
if let Target::Output(name) = &args.target {
if !outputs.iter().any(|output| output.name() == name) {
return Err(format!(
"output {name:?} not found. Outputs: {layout}"
));
}
}
eprintln!(
"grimrs-capture: route {ROUTE} protocol zwlr-screencopy-v1 \
mode {} target {} warmup {} frames {}",
args.mode.as_str(),
args.target.label(),
args.warmup,
args.frames
);
eprintln!("grimrs-capture: outputs {layout}");
let mut last_warmup_nonzero: Option<u64> = None;
let mut last_warmup_jpeg_ok = true;
for i in 0..args.warmup {
let held = grab(&mut grim, &args.target, args.mode)?;
if args.mode == Mode::Jpeg && !held.bytes.starts_with(&[0xFF, 0xD8]) {
last_warmup_jpeg_ok = false;
}
last_warmup_nonzero = Some(count_nonzero(&held.bytes));
eprintln!(
"grimrs-capture: warmup {}/{} {}x{} bytes {} nonzero {}",
i + 1,
args.warmup,
held.width,
held.height,
held.bytes.len(),
last_warmup_nonzero.unwrap_or(0)
);
}
if args.mode == Mode::Jpeg && !last_warmup_jpeg_ok {
return Err(
"warmup JPEG did not start with FF D8; refusing to measure"
.to_string(),
);
}
let cpu_before = process_cpu_ms()?;
let wall_start = Instant::now();
let mut samples_ms: Vec<f64> = Vec::with_capacity(args.frames as usize);
let mut jpeg_sizes: Vec<u64> = Vec::new();
let mut geometry: Option<(u32, u32)> = None;
for _ in 0..args.frames {
let tick = Instant::now();
let held = grab(&mut grim, &args.target, args.mode)?;
// Touch the length so the buffer is complete before the clock stops.
// Do not read pixels: the contract puts stride and checksum outside
// the measurement.
std::hint::black_box(held.bytes.len());
let ms = tick.elapsed().as_secs_f64() * 1000.0;
match geometry {
None => geometry = Some((held.width, held.height)),
Some((w, h)) if w != held.width || h != held.height => {
return Err(format!(
"geometry changed during the run: {w}x{h} then {}x{}",
held.width, held.height
));
}
Some(_) => {}
}
if let Some(len) = held.jpeg_len {
jpeg_sizes.push(len as u64);
}
samples_ms.push(ms);
// Free between frames, outside the frame timer. wall_ms includes it.
drop(held);
}
let wall_ms = wall_start.elapsed().as_secs_f64() * 1000.0;
let cpu_after = process_cpu_ms()?;
let (width, height) = geometry.ok_or("no measured frames")?;
let cpu_ms_per_frame = match (cpu_before, cpu_after) {
(Some(before), Some(after)) if after >= before => {
Some((after - before) / f64::from(args.frames))
}
_ => None,
};
let mut notes = format!(
"grim-rs 0.2.0 via Grim::new_wlr(); copy target is a wl_shm buffer \
created inside each capture_* call, not a dma-buf the producer \
imports. Cursor not overlaid (the frozen argv has no cursor flag; \
hhstream-live's grim command passes -c). JPEG is Grim::to_jpeg, \
quality {JPEG_QUALITY}, the crate default and the live-stream \
setting. Raw timer stops when capture_* returns, which is after \
the crate copies the mapping into a Vec and swizzles XRGB/ARGB to \
RGBA (and applies any output transform or y-invert). The public \
API does not expose the mapped buffer before that, so raw includes \
work the contract says to leave outside the timer. Percentiles are \
linear interpolation on the sorted samples. cpu_ms_per_frame is \
getrusage(RUSAGE_SELF) utime+stime over the measured loop only, \
divided by frames. Frame buffers are freed between frames; that \
free is inside wall_ms and outside frame_ms. Outputs: {layout}. \
No GPU on this machine; dma-buf was not used and is not claimed. \
This process does not move the pointer and does not start or stop \
a session; the pixels are whatever the compositor is already \
showing."
);
if let Some(nonzero) = last_warmup_nonzero {
notes.push_str(&format!(
" Last warmup frame nonzero bytes: {nonzero}."
));
if nonzero == 0 {
notes.push_str(" WARNING: last warmup frame was all zeros.");
}
}
let report = Report {
route: ROUTE,
language: "rust",
protocol: "zwlr-screencopy-v1",
output: args.target.label().to_string(),
geometry: [width, height],
mode: args.mode.as_str(),
warmup: args.warmup,
frames: args.frames,
frame_ms: summarize(&samples_ms),
fps_sustained: sustained_fps(&samples_ms),
wall_ms,
cpu_ms_per_frame,
bytes_p50: if args.mode == Mode::Jpeg {
Some(percentile_u64(&jpeg_sizes, 0.50))
} else {
None
},
persistent: true,
notes,
};
let line = serde_json::to_string(&report.to_json())
.map_err(|err| err.to_string())?;
let mut stdout = io::stdout().lock();
writeln!(stdout, "{line}").map_err(|err| err.to_string())?;
stdout.flush().map_err(|err| err.to_string())?;
Ok(())
}
fn grab(grim: &mut Grim, target: &Target, mode: Mode) -> Result<Held, String> {
let captured = match target {
Target::Output(name) => grim.capture_output(name),
Target::All => grim.capture_all(),
}
.map_err(|err| err.to_string())?;
let width = captured.width();
let height = captured.height();
if width == 0 || height == 0 {
return Err(format!("capture returned {width}x{height}"));
}
match mode {
Mode::Raw => Ok(Held {
width,
height,
jpeg_len: None,
bytes: captured.into_data(),
}),
Mode::Jpeg => {
let jpeg = grim
.to_jpeg_with_quality(captured.data(), width, height, JPEG_QUALITY)
.map_err(|err| err.to_string())?;
let jpeg_len = jpeg.len();
Ok(Held {
width,
height,
jpeg_len: Some(jpeg_len),
bytes: jpeg,
})
}
}
}
fn describe_outputs(outputs: &[grim_rs::Output]) -> String {
let mut ordered: Vec<_> = outputs.iter().collect();
ordered.sort_by(|a, b| {
let ag = a.geometry();
let bg = b.geometry();
ag.x()
.cmp(&bg.x())
.then(ag.y().cmp(&bg.y()))
.then(a.name().cmp(b.name()))
});
ordered
.into_iter()
.map(|output| {
let geometry = output.geometry();
format!(
"{}@{},{} {}x{} scale {}",
output.name(),
geometry.x(),
geometry.y(),
geometry.width(),
geometry.height(),
output.scale()
)
})
.collect::<Vec<_>>()
.join("; ")
}
fn count_nonzero(bytes: &[u8]) -> u64 {
bytes.iter().filter(|byte| **byte != 0).count() as u64
}
fn process_cpu_ms() -> Result<Option<f64>, String> {
let mut usage: libc::rusage = unsafe { std::mem::zeroed() };
let rc = unsafe { libc::getrusage(libc::RUSAGE_SELF, &mut usage) };
if rc != 0 {
return Ok(None);
}
Ok(Some(timeval_ms(usage.ru_utime) + timeval_ms(usage.ru_stime)))
}
fn timeval_ms(value: libc::timeval) -> f64 {
value.tv_sec as f64 * 1000.0 + value.tv_usec as f64 / 1000.0
}
struct Summary {
min: f64,
p50: f64,
mean: f64,
p95: f64,
max: f64,
}
fn summarize(samples: &[f64]) -> Summary {
let mut sorted = samples.to_vec();
sorted.sort_by(|a, b| a.total_cmp(b));
let sum: f64 = sorted.iter().sum();
Summary {
min: sorted[0],
p50: percentile_linear(&sorted, 0.50),
mean: sum / sorted.len() as f64,
p95: percentile_linear(&sorted, 0.95),
max: *sorted.last().expect("at least one sample"),
}
}
fn sustained_fps(samples: &[f64]) -> f64 {
let sum = samples.iter().sum::<f64>();
if sum <= 0.0 {
return 0.0;
}
samples.len() as f64 / (sum / 1000.0)
}
/// Linear interpolation between closest ranks. `samples` must be sorted and
/// non-empty. This is the same definition as numpy's default percentile.
fn percentile_linear(sorted: &[f64], p: f64) -> f64 {
if sorted.len() == 1 {
return sorted[0];
}
let rank = p * (sorted.len() - 1) as f64;
let lo = rank.floor() as usize;
let hi = rank.ceil() as usize;
let frac = rank - lo as f64;
sorted[lo] * (1.0 - frac) + sorted[hi] * frac
}
fn percentile_u64(samples: &[u64], p: f64) -> f64 {
let as_f64: Vec<f64> = samples.iter().map(|value| *value as f64).collect();
let mut sorted = as_f64;
sorted.sort_by(|a, b| a.total_cmp(b));
percentile_linear(&sorted, p)
}
struct Report {
route: &'static str,
language: &'static str,
protocol: &'static str,
output: String,
geometry: [u32; 2],
mode: &'static str,
warmup: u32,
frames: u32,
frame_ms: Summary,
fps_sustained: f64,
wall_ms: f64,
cpu_ms_per_frame: Option<f64>,
bytes_p50: Option<f64>,
persistent: bool,
notes: String,
}
impl Report {
fn to_json(&self) -> serde_json::Value {
serde_json::json!({
"route": self.route,
"language": self.language,
"protocol": self.protocol,
"output": self.output,
"geometry": self.geometry,
"mode": self.mode,
"warmup": self.warmup,
"frames": self.frames,
"frame_ms": {
"min": round3(self.frame_ms.min),
"p50": round3(self.frame_ms.p50),
"mean": round3(self.frame_ms.mean),
"p95": round3(self.frame_ms.p95),
"max": round3(self.frame_ms.max),
},
"fps_sustained": round3(self.fps_sustained),
"wall_ms": round3(self.wall_ms),
"cpu_ms_per_frame": self.cpu_ms_per_frame.map(round3),
"bytes_p50": self.bytes_p50.map(round3),
"persistent": self.persistent,
"notes": self.notes,
})
}
}
fn round3(value: f64) -> f64 {
(value * 1000.0).round() / 1000.0
}
fn parse_args(args: impl IntoIterator<Item = String>) -> Result<Args, String> {
let args: Vec<String> = args.into_iter().collect();
let mut output: Option<String> = None;
let mut all = false;
let mut frames: Option<u32> = None;
let mut warmup: Option<u32> = None;
let mut mode: Option<Mode> = None;
let mut json = false;
let mut index = 0;
while index < args.len() {
let arg = &args[index];
match arg.as_str() {
"--json" => {
if json {
return Err("repeated --json".to_string());
}
json = true;
}
"--all" => {
if all {
return Err("repeated --all".to_string());
}
all = true;
}
"--output" => {
output = Some(need_value(&args, &mut index, "--output")?);
}
"--frames" => {
frames = Some(parse_u32(&need_value(&args, &mut index, "--frames")?, "--frames")?);
}
"--warmup" => {
warmup = Some(parse_u32(&need_value(&args, &mut index, "--warmup")?, "--warmup")?);
}
"--mode" => {
let value = need_value(&args, &mut index, "--mode")?;
mode = Some(match value.as_str() {
"raw" => Mode::Raw,
"jpeg" => Mode::Jpeg,
other => {
return Err(format!(
"--mode must be raw or jpeg, got {other:?}"
))
}
});
}
"--help" | "-h" => {
return Err(usage());
}
other => {
return Err(format!("unknown argument {other}. {}", usage()));
}
}
index += 1;
}
if !json {
return Err(format!("--json is required. {}", usage()));
}
if all && output.is_some() {
return Err("--all and --output are mutually exclusive".to_string());
}
let target = if all {
Target::All
} else if let Some(name) = output {
if name.is_empty() {
return Err("--output name is empty".to_string());
}
Target::Output(name)
} else {
return Err(format!("one of --output or --all is required. {}", usage()));
};
let frames = frames.ok_or_else(|| format!("--frames is required. {}", usage()))?;
if frames == 0 {
return Err("--frames must be at least 1".to_string());
}
let warmup = warmup.ok_or_else(|| format!("--warmup is required. {}", usage()))?;
let mode = mode.ok_or_else(|| format!("--mode is required. {}", usage()))?;
Ok(Args {
target,
frames,
warmup,
mode,
})
}
fn need_value(args: &[String], index: &mut usize, flag: &str) -> Result<String, String> {
let next = index.checked_add(1).and_then(|i| args.get(i));
match next {
Some(value) if !value.starts_with("--") => {
*index += 1;
Ok(value.clone())
}
_ => Err(format!("{flag} needs a value")),
}
}
fn parse_u32(value: &str, flag: &str) -> Result<u32, String> {
value
.parse::<u32>()
.map_err(|_| format!("{flag} must be a non-negative integer, got {value:?}"))
}
fn usage() -> String {
"usage: grimrs-capture (--output NAME | --all) --frames N --warmup W \
--mode raw|jpeg --json"
.to_string()
}
#[cfg(test)]
mod tests {
use super::*;
fn parse(line: &str) -> Result<Args, String> {
parse_args(line.split_whitespace().map(str::to_string))
}
#[test]
fn accepts_the_contract_forms() {
let output = parse(
"--output hh-chromium-yrfadn --frames 300 --warmup 10 --mode raw --json",
)
.unwrap();
assert!(matches!(output.target, Target::Output(name) if name == "hh-chromium-yrfadn"));
assert_eq!(output.frames, 300);
assert_eq!(output.warmup, 10);
assert_eq!(output.mode, Mode::Raw);
let all = parse("--all --frames 300 --warmup 10 --mode jpeg --json").unwrap();
assert!(matches!(all.target, Target::All));
assert_eq!(all.mode, Mode::Jpeg);
}
#[test]
fn rejects_mixed_targets_and_missing_json() {
assert!(parse("--all --output x --frames 1 --warmup 0 --mode raw --json").is_err());
assert!(parse("--output x --frames 1 --warmup 0 --mode raw").is_err());
assert!(parse("--output x --frames 0 --warmup 0 --mode raw --json").is_err());
assert!(parse("--frames 1 --warmup 0 --mode raw --json").is_err());
assert!(parse("--output x --frames 1 --warmup 0 --mode png --json").is_err());
}
#[test]
fn percentile_matches_linear_interpolation() {
let samples = [1.0, 2.0, 3.0, 4.0];
assert_eq!(percentile_linear(&samples, 0.50), 2.5);
assert_eq!(percentile_linear(&samples, 0.0), 1.0);
assert_eq!(percentile_linear(&samples, 1.0), 4.0);
// rank = 0.95 * 3 = 2.85 -> 3.0 * 0.15 + 4.0 * 0.85
let p95 = percentile_linear(&samples, 0.95);
assert!((p95 - 3.85).abs() < 1e-9);
}
#[test]
fn sustained_fps_uses_the_sum_of_frame_times() {
// Two frames of 100 ms -> 2 / 0.2 = 10 fps.
let fps = sustained_fps(&[100.0, 100.0]);
assert!((fps - 10.0).abs() < 1e-9);
}
#[test]
fn json_object_has_the_contract_keys() {
let report = Report {
route: ROUTE,
language: "rust",
protocol: "zwlr-screencopy-v1",
output: "hh-chromium-yrfadn".to_string(),
geometry: [1280, 720],
mode: "jpeg",
warmup: 10,
frames: 300,
frame_ms: Summary {
min: 1.0,
p50: 2.0,
mean: 3.0,
p95: 4.0,
max: 5.0,
},
fps_sustained: 10.0,
wall_ms: 20.0,
cpu_ms_per_frame: None,
bytes_p50: Some(100.5),
persistent: true,
notes: "n".to_string(),
};
let value = report.to_json();
for key in [
"route",
"language",
"protocol",
"output",
"geometry",
"mode",
"warmup",
"frames",
"frame_ms",
"fps_sustained",
"wall_ms",
"cpu_ms_per_frame",
"bytes_p50",
"persistent",
"notes",
] {
assert!(value.get(key).is_some(), "missing {key}");
}
assert!(value["cpu_ms_per_frame"].is_null());
assert_eq!(value["bytes_p50"], 100.5);
assert_eq!(value["persistent"], true);
assert_eq!(value["geometry"][0], 1280);
}
}
+38 -13
View File
@@ -75,12 +75,18 @@ def test_a_failure_after_a_good_frame_keeps_the_known_size():
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'))"]
argv = [
sys.executable,
"-c",
"import os,sys;sys.stdout.write(os.environ['WAYLAND_DISPLAY']+':'+"
+ "('PATH' in os.environ and 'haspath' or 'nopath'))",
]
before = os.environ.get("WAYLAND_DISPLAY")
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"
assert os.environ.get("WAYLAND_DISPLAY") == before, (
"our own environment was mutated"
)
def test_empty_argv_and_bad_timeout_are_rejected_up_front():
@@ -91,8 +97,10 @@ def test_empty_argv_and_bad_timeout_are_rejected_up_front():
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')")
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"
@@ -102,15 +110,32 @@ def test_image_size_reads_png_headers(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)
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"])
@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