Compare commits

..
Author SHA1 Message Date
Hermenix edcfd8f853 Merge branch 'feat/session-live-stream-webapp' into integration/keyboard-and-stream 2026-10-11 02:31:52 +00:00
Hermenix 994fdb1cfb Merge keyboard input (feat/keyboard-input @561e0c2) for a live trial on this machine
The same shape as the merge that branch got on 2026-10-05 (edbf15f on
feat/session-live-stream): this machine's own config sets
`sessions.keyboard.layout`, so a ref without the keyboard work does not
evaluate -- and the point of this branch is to be consumed here.

The stream branch's own commit is the first parent, so PR #2 stays based on
main and carries none of this merge. Conflicts were additive on both sides
(new option blocks, new checks, new README rows) and are resolved by keeping
both.
2026-10-11 02:23:11 +00:00
12 changed files with 78 additions and 2491 deletions

No files matched your search

-1
View File
@@ -1 +0,0 @@
use flake
+1 -5
View File
@@ -48,8 +48,6 @@ 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:
@@ -72,8 +70,6 @@ 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
```
@@ -225,11 +221,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
+6 -7
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,15 +62,14 @@ in
vm-pointer = pkgs.callPackage ./vm-pointer.nix sessionArgs;
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;
};
vm-keyboard = pkgs.callPackage ./vm-keyboard.nix sessionArgs;
vm-keyboard-de = pkgs.callPackage ./vm-keyboard.nix (
sessionArgs // { keyboardLayout = "de"; }
);
}
+57 -57
View File
@@ -625,6 +625,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.
'';
};
};
# 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
@@ -699,63 +756,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.
'';
};
};
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
@@ -1 +0,0 @@
/target
File diff suppressed because it is too large. Load diff
@@ -1,16 +0,0 @@
[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"] }
@@ -1,53 +0,0 @@
#!/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"
@@ -1,13 +0,0 @@
# 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
];
}
@@ -1,641 +0,0 @@
//! 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);
}
}
+13 -38
View File
@@ -75,18 +75,12 @@ 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'))",
]
before = os.environ.get("WAYLAND_DISPLAY")
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 os.environ.get("WAYLAND_DISPLAY") == before, (
"our own environment was mutated"
)
assert "WAYLAND_DISPLAY" not in os.environ, "our own environment was mutated"
def test_empty_argv_and_bad_timeout_are_rejected_up_front():
@@ -97,10 +91,8 @@ 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"
@@ -110,32 +102,15 @@ 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