Files
HermenixandClaude Opus 5 de408e4b7f the surface: CLI verbs, the module's options, and three checks the compositor votes in
Everything below the CLI was merged and green against fakes; none of it was
reachable and none of it had ever met a compositor. This wires it up and then
puts the compositor in a position to disagree.

CLI (src/hhstream/cli.py, src/hhstream_session/**)

  session container [ID], session reconcile [ID], and the seven pointer verbs
  from PLAN §9. `start` still prints the bare session id and nothing else.
  `list` gains WS / OUTPUT / POINTER, with the gap marker where a value is
  genuinely unknown rather than a blank that reads as zero -- the POINTER
  column needs a second, read-only `pointer.state` call because the `list`
  reply carries no lease state.

  The lease id is cached in `hhstream_session.lease` (under
  $XDG_RUNTIME_DIR), because PLAN §9's gesture verbs take no --lease and the
  wire requires a lease_id on every one of them; --lease and $HHSTREAM_LEASE
  override it, and a `no_lease` refusal drops the stale entry.

  Exit codes are the contract's: a gesture with no lease is 9 and never
  reaches the broker, and a compositor failure is 10 with a message that says
  the session is still running. `kill` now warns about
  `session.container_survivors` -- windows the compositor still shows -- and
  distinguishes `null` ("could not ask") from `[]`.

  `shot`/`record --output NAME` capture one container through `grim -o`; the
  frame socket publishes the main output only, so it cannot do it.

Module (nix/module.nix)

  sessions.containers.{enable,max,mode,workspaceBase},
  sessions.pointer.{enable,leaseTtl,leaseMax}, rendered into the generated
  TOML with §10's key names. hhstream-pointer.service: the operator's account,
  supplementary group hhstream, After=/BindsTo= the compositor,
  Restart=on-failure, KillMode=process, and the command line §3.4 freezes.
  tmpfiles for /run/hhstream plus RuntimeDirectoryPreserve on the broker,
  without which restarting the broker deletes the driver's socket out from
  under it. The runtime-directory length assertion is untouched.

  And ExecStartPost on the compositor, opening its IPC directory to its own
  group: Hyprland creates <runtime>/hypr with S_IRWXU, so the broker -- a
  different account by design -- could not reach the request or event socket
  at all, and degraded silently exactly as it is built to.

Checks (checks/**)

  vm-ipc: both sockets at their frozen names, measured against sun_path's 108
  bytes, and a socket2 subscriber that receives an openwindow for a window the
  test creates. The subscriber is the shipped HyprlandIPC, not a second
  implementation: this check exists to prove that this client hears this
  compositor.

  vm-containers: one hh-* output per session at the container mode, the window
  on it, a second window of the same application beside it, an unmatched
  window quarantined, grim -o isolating one container, teardown removing the
  output and freeing the slot. PLAN experiment 3 is answered: `hyprctl output
  create headless` works.

  vm-pointer: a version-2 virtual pointer, a warp and a click whose
  coordinates the *application* reports, BUSY naming the holder, 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.

  checks/lib gains the guest the three share, their test-script helpers (no
  assertions live there), an event-socket subscriber and a Wayland client that
  says where it was clicked -- nothing in nixpkgs both honours
  $HHSTREAM_APP_ID and reports pointer events.

Reported, not worked around: the broker reads none of the container or
pointer config (policy.py takes [defaults] and [apps] only), `start` has no
no_container field so --no-container is refused rather than silently ignored,
and nix/hyprland-conf.nix sets input:follow_mouse = 0, which sends pointer
events to the focused window only -- measured, with the cursor at the aimed
pixel and no client told. README.dev.md has the evidence for each.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WQy29x9AfHWyzNd1f7XPGK
2026-10-03 06:58:44 +00:00

242 lines
10 KiB
Nix

# checks.<system>.vm-ipc -- the compositor's own IPC, against the real thing.
#
# This is the check that would have caught the `sun_path` defect, and that is
# its reason for existing. Hyprland's event socket lives at
#
# <runtime dir>/hypr/<HYPRLAND_INSTANCE_SIGNATURE>/.socket2.sock
#
# and at the old 29-character runtime directory that path did not fit in the
# 108 bytes a Unix socket address has:
#
# ERR ]: Socket2 path is too long. (2) IPC will not work.
#
# The *request* socket is shorter by one character and kept working, so
# `hyprctl` answered, every reconciliation that only ever asked `clients -j`
# looked healthy, and the event stream was simply dead. Nothing short of a
# subscriber that waits for a named event can tell those two apart -- so that
# is what the last subtest is, and the subscriber is the shipped
# `hhstreamd.ipc.HyprlandIPC`, not a reimplementation of it.
#
# Both socket paths are asserted by name and measured against the 108-byte
# limit with the numbers printed, because "it fits today" is a fact about this
# instance signature and the next compositor may choose a longer one.
#
# Habits copied from vm-hyprland and vm-sessions: every wait is bounded, each
# assertion is made once, and a failure dumps the compositor's diagnostics and
# the broker's journal before it propagates.
{
testers,
hhstream,
hhsModule,
testTools,
hyprland,
foot,
jq,
grim,
procps,
coreutils,
dejavu_fonts,
width ? 1280,
height ? 720,
sessionUser ? "hermes",
}:
testers.runNixOSTest (
{ pkgs, ... }:
let
tools = pkgs.callPackage ./lib/session-tools.nix { inherit hhstream; };
guest = import ./lib/session-machine.nix {
inherit
hhsModule
hhstream
hyprland
testTools
foot
jq
procps
grim
coreutils
dejavu_fonts
;
sessionTools = tools;
};
prelude = import ./lib/session-prelude.nix {
inherit hhstream coreutils sessionUser;
};
in
{
name = "hhstream-vm-ipc";
globalTimeout = 1800;
nodes.machine = guest {
inherit width height sessionUser;
apps.foot = {
exec = "${foot}/bin/foot";
# The daemon refuses unlisted arguments and this check passes none:
# `foot` with no argv opens a window, which is all the witness needs.
argsAllow = [ ];
};
};
testScript =
prelude
+ ''
import re
EVENTS = "/tmp/hypr-events.log"
#: linux/un.h: sun_path is 108 bytes including the terminating NUL.
SUN_PATH_MAX = 107
start_all()
bring_up("the compositor and broker")
with subtest("the as-user wrapper propagates exit status"):
# Every assertion below reads machine.succeed/fail through it, so a
# wrapper that swallowed the status would make them all vacuous.
machine.succeed(as_user(TRUE), timeout=120)
machine.fail(as_user(FALSE), timeout=120)
with subtest("both IPC sockets exist, at the names the contract freezes"):
# By name, not by glob. CONTRACT-sessions.md §5 fixes
# <runtime dir>/hypr/<signature>/.socket{,2}.sock, and the defect
# this check exists for was precisely the second of those two being
# absent while the first was there.
try:
signature = machine.succeed(
f"ls -1 {COMPOSITOR_RUNTIME}/hypr | head -n1"
).strip()
assert signature, "no instance directory under the runtime dir"
print(f"instance signature: {signature!r} ({len(signature)} chars)")
base = f"{COMPOSITOR_RUNTIME}/hypr/{signature}"
for name in (".socket.sock", ".socket2.sock"):
path = f"{base}/{name}"
kind = machine.succeed(f"stat -c %F {path}").strip()
assert kind == "socket", f"{path} is a {kind}, not a socket"
print(f"{path} ({len(path)} bytes of {SUN_PATH_MAX})")
assert len(path) <= SUN_PATH_MAX, (
f"{path} is {len(path)} bytes; sun_path holds "
f"{SUN_PATH_MAX}. The compositor cannot have bound this."
)
except Exception:
dump("an IPC socket is missing or does not fit in sun_path")
raise
with subtest("hyprctl answers over the request socket"):
try:
version = machine.succeed(f"{HYPRCTL} version", timeout=120)
print(version)
assert json.loads(version).get("tag"), "version carries no tag"
monitors = compositor("monitors")
assert monitors, "hyprctl reported no monitors at all"
print(
"monitors: "
+ ", ".join(f"{m['name']} {m['width']}x{m['height']}" for m in monitors)
)
except Exception:
dump("the request socket did not answer")
raise
with subtest("the broker's own IPC client reads the same facts"):
# The client under test, not hyprctl: `container` goes through
# ContainerHost -> HyprlandIPC -> the request socket, so a reply
# here is this repository's parser against this compositor.
try:
reply = cli_json("container --json")
print(json.dumps(reply, indent=2, sort_keys=True))
assert reply["compositor"] == "ok", (
f"the broker cannot reach the compositor: {reply.get('error')!r}"
)
assert reply["orphans"] == [], (
f"a fresh machine already has orphan outputs: {reply['orphans']}"
)
except Exception:
dump("the broker's IPC client could not reach the compositor")
raise
with subtest("a socket2 subscriber receives openwindow for a window we create"):
# THE assertion. The subscriber is started first and left blocking
# on the event socket; the window is created after it is listening,
# so an `openwindow` in its log can only have come down the stream.
#
# If the event socket were the truncated one, everything above this
# point would still pass and this would time out -- which is the
# whole shape of the defect.
try:
machine.succeed(f"rm -f {EVENTS}")
machine.succeed(
background(
"ipc-watch",
"/run/current-system/sw/bin/hhs-ipc-watch"
f" --runtime-dir {COMPOSITOR_RUNTIME} --out {EVENTS}"
" --await-event openwindow --timeout 180",
),
timeout=120,
)
# Wait for the subscriber to be connected, not merely spawned:
# it writes its first line after `discover()` has returned and
# before it blocks, so the file appearing is the handshake.
machine.wait_for_file(EVENTS, timeout=60)
print(machine.succeed(f"cat {EVENTS}"))
session_id = machine.succeed(cli("start foot"), timeout=180).strip()
print(f"session: {session_id}")
# One bounded wait, for the unit to exit 0 -- which it does only
# when it has seen the event it was told to await.
machine.wait_until_fails(
"systemctl is-active ipc-watch.service", timeout=120
)
received = machine.succeed(f"cat {EVENTS}")
print(received)
result = machine.succeed(
"systemctl show -p Result --value ipc-watch.service"
).strip()
assert result == "success", (
f"the subscriber exited {result!r}: it never saw an openwindow "
"event. The request socket answers (above) and the event "
"socket does not -- which is exactly the sun_path defect."
)
assert "openwindow" in received, received
except Exception:
dump("no openwindow reached the event subscriber", locals().get("session_id"))
raise
with subtest("the event named the window the compositor also reports"):
# The event is not taken on trust: `openwindow>>address,workspace,
# class,title` carries an address, and the compositor's own client
# list has to agree that such a window exists.
try:
line = [
row
for row in machine.succeed(f"cat {EVENTS}").splitlines()
if row.startswith("openwindow\t")
][0]
payload = line.split("\t", 1)[1]
address = payload.split(",")[0]
print(f"openwindow payload: {payload!r} -> address {address!r}")
assert re.fullmatch(r"[0-9a-f]+", address), (
f"openwindow's first field is not an address: {address!r}"
)
addresses = [c["address"] for c in compositor("clients")]
print(f"compositor clients: {addresses}")
assert any(a.endswith(address) for a in addresses), (
f"the event announced {address} and `clients -j` has {addresses}"
)
except Exception:
dump("the openwindow event and the client list disagree")
raise
with subtest("teardown leaves the compositor with no client of ours"):
try:
reply = cli_json(f"kill --json {session_id}", timeout=180)
assert reply["ok"] is True, reply
machine.wait_until_succeeds(
f"{HYPRCTL} clients | jq -e 'length == 0' >/dev/null", timeout=60
)
except Exception:
dump("a client outlived its session", session_id)
raise
'';
}
)