Files
hyprland-headless-stream-pl…/checks/lib/ipc_watch.py
T
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

113 lines
4.0 KiB
Python

#!/usr/bin/env python3
"""Subscribe to the compositor's event socket and write what arrives.
This is ``vm-ipc``'s witness, and it runs the **shipped** client
(:class:`hhstreamd.ipc.HyprlandIPC`) rather than a second implementation of
the same parsing. That is the opposite choice from ``tests/assert_stream.py``,
which is deliberately independent of ``hhstream.client`` so a shared framing
bug still fails -- and the reason for the difference is what each check is
for. ``vm-basic`` asserts a wire format two programs must agree on; this one
asserts that *this* client, against *this* compositor, receives events at all.
That is the defect it is pointed at. The compositor's event socket is
``<runtime dir>/hypr/<signature>/.socket2.sock``, and at the old 29-character
runtime directory the path did not fit in ``sun_path``:
ERR ]: Socket2 path is too long. (2) IPC will not work.
The *request* socket kept answering ``hyprctl`` -- both ends agreed on the
same truncated path -- so everything looked healthy while no event ever
arrived. Only a subscriber that waits for a named event can tell the
difference, which is why this program exists and why it reports what it saw
rather than just its exit status.
Every line it writes is flushed, so a caller can tail the file while the
compositor is still running.
"""
from __future__ import annotations
import argparse
import sys
import threading
import time
from pathlib import Path
from hhstreamd.ipc import CompositorUnavailable, HyprlandIPC
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(
prog="hhs-ipc-watch",
description="Record Hyprland events from the real event socket.",
)
parser.add_argument(
"--runtime-dir",
type=Path,
default=Path("/run/hypr-stream"),
help="the compositor's runtime directory (default: %(default)s)",
)
parser.add_argument(
"--out", type=Path, required=True, help="append every event here, one per line"
)
parser.add_argument(
"--await-event",
action="append",
default=[],
metavar="NAME",
help="exit 0 once this event has been seen; repeatable, all must arrive",
)
parser.add_argument(
"--timeout",
type=float,
default=120.0,
help="give up after this long and exit 1 (default: %(default)ss)",
)
args = parser.parse_args(argv)
try:
ipc = HyprlandIPC.discover(args.runtime_dir)
except CompositorUnavailable as exc:
print(f"hhs-ipc-watch: {exc}", file=sys.stderr)
return 1
out = args.out.open("a", encoding="utf-8", buffering=1)
print(f"watching {args.runtime_dir} for {args.await_event or 'everything'}", file=out)
wanted = set(args.await_event)
seen: set[str] = set()
deadline = time.monotonic() + args.timeout
# `events()` blocks in `recv`, so the deadline cannot be enforced from the
# same thread. Closing the socket from a timer is what unblocks it, and it
# is also what a real caller would have to do -- the contract's `events()`
# is explicitly a blocking iterator.
timer = threading.Timer(args.timeout, ipc.close)
timer.daemon = True
timer.start()
try:
for event in ipc.events():
print(f"{event.name}\t{event.data.get('raw', '')}", file=out)
if event.name in wanted:
seen.add(event.name)
if seen >= wanted:
print(f"saw {sorted(seen)}", file=out)
return 0
if time.monotonic() > deadline:
break
except CompositorUnavailable as exc:
print(f"event stream ended: {exc}", file=out)
finally:
timer.cancel()
ipc.close()
out.flush()
missing = sorted(wanted - seen)
print(f"TIMED OUT after {args.timeout}s; never saw {missing}", file=out)
print(f"hhs-ipc-watch: never saw {missing}", file=sys.stderr)
out.close()
return 1
if __name__ == "__main__":
sys.exit(main())