diff --git a/README.dev.md b/README.dev.md index 23278a3..8cd27d8 100644 --- a/README.dev.md +++ b/README.dev.md @@ -219,6 +219,10 @@ 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-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 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 @@ -228,6 +232,8 @@ checks/ lib/ipc_watch.py subscribes to the event socket: hhs-ipc-watch lib/pointer_target.py a Wayland window that reports pointer events it receives: hhs-pointer-target + lib/keyboard_target.py a Wayland window that reports KEY events, decoded with + the keymap the compositor forwarded: hhs-keyboard-target tests/ fake_capture.py writes one fixed PNG to stdout: hhs-fake-capture assert_stream.py independent contract reader/asserter: hhs-assert-stream @@ -259,6 +265,14 @@ print the pointer events it receives with the coordinates it was given. `foot` and `wev` do neither and ignore the environment entirely, which makes them good *unmatched* windows and useless as matched ones. +`hhs-keyboard-target` is its sibling, and the thing that makes it a separate +program rather than a flag is **where its symbols come from**: it compiles the +keymap the compositor forwarded over `wl_keyboard.keymap` and decodes every key +through that. A client with its own keymap would decode `hello` whether or not +the driver ever uploaded one, so the check would be asserting that the check +can spell. It is also why `session-tools.nix` builds it against a python with +`xkbcommon` while the pointer target gets one with only `pywayland`. + Adding a unit test: drop a `test_*.py` under `tests/`. Nothing needs registering, but the basename must be unique across the tree. Adding a check: one file in `checks/`, one line in `checks/default.nix`. diff --git a/checks/default.nix b/checks/default.nix index 8f01f56..73f739c 100644 --- a/checks/default.nix +++ b/checks/default.nix @@ -7,13 +7,20 @@ # 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-keyboard -- the uploaded keymap, keyboard focus, and a decoded symbol +# vm-keyboard-de -- the same check with sessions.keyboard.layout = "de" # # 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 -# subscriber and the pointer target, `session-machine.nix` for the guest the -# three session checks share, and `session-prelude.nix` for their test-script +# subscriber and the two input targets, `session-machine.nix` for the guest the +# session checks share, and `session-prelude.nix` for their test-script # helpers. # +# `vm-keyboard` and `vm-keyboard-de` are one file twice over, and that is the +# point: `sessions.keyboard.layout` reaches the uploaded keymap only through +# the driver unit's argv, and a single-layout check cannot tell that path from +# a hardcoded `us`. See the header of vm-keyboard.nix. +# # Run them ONE AT A TIME. Each boots a VM with a software-rendered compositor; # two at once on a two-core machine make the timing-sensitive assertions flake, # and a flaky green is worth less than a slow one. @@ -26,9 +33,9 @@ let hhstream = self.packages.${system}.hhstream; hhsModule = self.nixosModules.default; testTools = pkgs.callPackage ./lib/test-tools.nix { }; - # The three session checks take the same five arguments; naming them once - # keeps a new check from being wired up with a different compositor or a - # different package than its neighbours. + # The session checks take the same arguments; naming them once keeps a new + # check from being wired up with a different compositor or a different + # package than its neighbours. sessionArgs = { inherit hhstream hhsModule testTools; }; @@ -53,4 +60,10 @@ in vm-containers = pkgs.callPackage ./vm-containers.nix sessionArgs; 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"; } + ); } diff --git a/checks/lib/keyboard_target.py b/checks/lib/keyboard_target.py new file mode 100644 index 0000000..732fe98 --- /dev/null +++ b/checks/lib/keyboard_target.py @@ -0,0 +1,339 @@ +#!/usr/bin/env python3 +"""A Wayland client that says which keys it was sent, in the layout's own words. + +A sibling of ``pointer_target.py`` and deliberately not an extension of it: +that client's contract is "report pointer events", this one's is "report +keyboard events, decoded with the keymap the compositor forwarded", and the +second needs a dependency (xkbcommon) and a seat capability the first does not. +Two small programs read better than one with a mode switch, and the pointer +checks should not start failing because the keyboard check needed a new +listener. + +Three things it does that matter to the assertions: + +* **It sets ``xdg_toplevel`` app id from ``$HHSTREAM_APP_ID``**, which is what + gets its window into its session's container. ``foot`` and ``wev`` ignore + the environment, keep their own class, match no per-session rule and are + swept into the quarantine workspace — so there would be nothing for the + cursor to land in. Same reason ``pointer_target.py`` exists. + +* **Every keysym it prints is decoded from the keymap the compositor sent it**, + over ``wl_keyboard.keymap``, compiled here with xkbcommon and updated with + ``xkb_state_update_mask`` on every ``modifiers`` event. Never from a table + in this file. That is the whole mutation rule for the check: keycodes that + arrive with no decodable symbol are a failure, not a pass, so a driver that + stopped uploading its keymap cannot leave the check green. If no keymap + arrived, ``sym`` is printed as ``?`` and says so. + +* **It prints the raw evdev code beside the symbol, and the modifier mask + beside both.** A toolkit that ignored ``wl_keyboard.modifiers`` and shifted + only on ``KEY_LEFTSHIFT`` would decode a capital wrongly, so the check has to + see the mask the compositor forwarded *and* the absence of a Shift keycode — + the mask is how this build makes a capital, and sending both is how a + capital gets shifted twice or not at all. + +It also binds ``wl_pointer`` and prints ``enter``/``leave`` for it. Not +decoration: a cursor that arrives in a window whose keyboard focus did not +follow is exactly the failure a one-warp ``acquire`` produces, and without the +pointer line the check could not tell that apart from a warp that never +arrived at all. + +Deliberately loud and deliberately unbuffered: the broker captures stdout into +the session log, so ``hhstream session logs`` is the read-back, and a check +that goes red says whether the window was never mapped, never focused, or +focused and sent the wrong symbol. +""" + +from __future__ import annotations + +import argparse +import mmap +import os +import signal +import struct +import sys + +from pywayland.client import Display +from pywayland.protocol.wayland import WlCompositor, WlSeat, WlShm +from pywayland.protocol.xdg_shell import XdgWmBase +from xkbcommon import xkb + +#: Opaque 32-bit colour. Something has to be in the buffer for the compositor +#: to map the surface at all, and an unmapped surface is never focused. +FILL = 0xFF2A4D6E + +#: Fallback size for a compositor that configures 0x0 ("you choose"). +DEFAULT_SIZE = (640, 360) + +#: A Wayland/evdev keycode is the XKB keycode minus 8. ``wl_keyboard.key`` +#: carries the evdev value; xkbcommon's tables are indexed by the XKB one. +EVDEV_OFFSET = 8 + +#: ``wl_keyboard.key_state``. ``2`` is ``repeated`` and only reaches a version +#: 10 client; it is named here so a count of presses cannot miss one. +STATE_NAMES = {0: "released", 1: "pressed", 2: "repeated"} + + +def say(line: str) -> None: + """One line, flushed. The reader is a log tail.""" + + print(line, flush=True) + + +class Target: + def __init__(self, app_id: str, title: str) -> None: + self.app_id = app_id + self.title = title + self.display: Display | None = None + self.compositor = None + self.shm = None + self.wm_base = None + self.seat = None + self.window: _Window | None = None + self.keyboard = None + self.pointer = None + + #: The compositor's own keymap, as forwarded, and a state machine over + #: it. Every `sym=` comes from here; see the module docstring. + self._keymap = None + self._state = None + + # -- setup --------------------------------------------------------- + + def run(self) -> int: + self.display = Display() + self.display.connect() + registry = self.display.get_registry() + registry.dispatcher["global"] = self._on_global + self.display.roundtrip() + + missing = [ + name + for name, value in ( + ("wl_compositor", self.compositor), + ("wl_shm", self.shm), + ("xdg_wm_base", self.wm_base), + ("wl_seat", self.seat), + ) + if value is None + ] + if missing: + say(f"target: FATAL missing globals: {', '.join(missing)}") + return 1 + self.wm_base.dispatcher["ping"] = lambda base, serial: base.pong(serial) + self.seat.dispatcher["capabilities"] = self._on_capabilities + + self.window = _Window(self) + self.display.roundtrip() + say(f"target: app_id={self.app_id} pid={os.getpid()}") + + while True: + # Blocking dispatch: this process exists to report events, so there + # is nothing to do between them and nothing to poll for. + if self.display.dispatch(block=True) < 0: + say("target: display disconnected") + return 1 + + def _on_global(self, registry, global_id: int, interface: str, version: int) -> None: + if interface == WlCompositor.name: + self.compositor = registry.bind(global_id, WlCompositor, min(version, 4)) + elif interface == WlShm.name: + self.shm = registry.bind(global_id, WlShm, 1) + elif interface == XdgWmBase.name: + self.wm_base = registry.bind(global_id, XdgWmBase, min(version, 2)) + elif interface == WlSeat.name and self.seat is None: + self.seat = registry.bind(global_id, WlSeat, min(version, 5)) + + def _on_capabilities(self, seat, capabilities: int) -> None: + """Bind what the seat has, and say out loud what it has not. + + A headless seat has **no keyboard capability at all** until something + creates a virtual one — there is no input device here — so + "keyboard not bound" is a statement about the driver, not about this + client, and a check that saw no key events needs to know which. + """ + + say(f"target: seat capabilities={capabilities}") + if capabilities & WlSeat.capability.keyboard.value and self.keyboard is None: + self.keyboard = seat.get_keyboard() + self.keyboard.dispatcher["keymap"] = self._on_keymap + self.keyboard.dispatcher["enter"] = self._on_enter + self.keyboard.dispatcher["leave"] = self._on_leave + self.keyboard.dispatcher["key"] = self._on_key + self.keyboard.dispatcher["modifiers"] = self._on_modifiers + self.keyboard.dispatcher["repeat_info"] = self._on_repeat_info + say("target: keyboard bound") + elif not capabilities & WlSeat.capability.keyboard.value: + say("target: seat has no keyboard capability yet") + + if capabilities & WlSeat.capability.pointer.value and self.pointer is None: + self.pointer = seat.get_pointer() + self.pointer.dispatcher["enter"] = self._on_pointer_enter + self.pointer.dispatcher["leave"] = self._on_pointer_leave + say("target: pointer bound") + + # -- keyboard ------------------------------------------------------ + + def _on_keymap(self, keyboard, format_: int, fd: int, size: int) -> None: + """Compile what the compositor forwarded, and decode with it. + + The size on the wire includes the NUL terminator, so the text is + everything up to the first one. A keymap that will not compile is + reported rather than swallowed: it is indistinguishable, from here, + from a compositor that was never given one, and the two have very + different causes. + """ + + try: + with os.fdopen(fd, "rb", closefd=True) as handle: + raw = handle.read(size) + except OSError as exc: + say(f"keyboard keymap bytes={size} UNREADABLE {exc}") + return + text = raw.split(b"\0", 1)[0].decode("utf-8", "replace") + symbols = next( + (line.strip() for line in text.splitlines() if "xkb_symbols" in line), "?" + ) + try: + self._keymap = xkb.Context().keymap_new_from_string(text) + self._state = self._keymap.state_new() + except Exception as exc: + say(f"keyboard keymap bytes={size} WILL-NOT-COMPILE {exc}") + return + # `symbols=` is the line the check greps to prove *which* layout was + # uploaded: `pc_us_inet(evdev)` against `pc_de_inet(evdev)`. + say(f"keyboard keymap format={format_} bytes={size} symbols={symbols}") + + def _sym(self, code: int) -> str: + """The keysym name for an evdev code, under the forwarded keymap.""" + + if self._state is None: + # `?` and not a guess: the check treats a key with no symbol as a + # failure, which is what makes "the keymap was uploaded" an + # assertion rather than an assumption. + return "?" + return xkb.keysym_get_name(self._state.key_get_one_sym(code + EVDEV_OFFSET)) + + def _on_enter(self, keyboard, serial, surface, keys) -> None: + held = list(keys) if keys else [] + say(f"keyboard enter serial={serial} keys={held}") + + def _on_leave(self, keyboard, serial, surface) -> None: + say(f"keyboard leave serial={serial}") + + def _on_key(self, keyboard, serial, time_, key: int, state: int) -> None: + say( + f"keyboard key code={key} state={state}" + f" ({STATE_NAMES.get(state, 'unknown')}) sym={self._sym(key)}" + ) + + def _on_modifiers(self, keyboard, serial, depressed, latched, locked, group) -> None: + if self._state is not None: + # The mask first, then the sym lookup above is the one a real + # client does: `A` is only `A` because Shift is in this mask. + self._state.update_mask(depressed, latched, locked, 0, 0, group) + say( + f"keyboard modifiers depressed={depressed} latched={latched}" + f" locked={locked} group={group}" + ) + + def _on_repeat_info(self, keyboard, rate: int, delay: int) -> None: + say(f"keyboard repeat_info rate={rate} delay={delay}") + + # -- pointer, for telling two failures apart ------------------------ + + def _on_pointer_enter(self, pointer, serial, surface, x, y) -> None: + say(f"pointer enter x={x:.2f} y={y:.2f}") + + def _on_pointer_leave(self, pointer, serial, surface) -> None: + say("pointer leave") + + +class _Window: + """One toplevel: a surface, its xdg wrapper, and an shm buffer.""" + + def __init__(self, target: Target) -> None: + self.target = target + self.size = DEFAULT_SIZE + self.buffer = None + self._pool = None + self._map: mmap.mmap | None = None + + self.surface = target.compositor.create_surface() + self.xdg_surface = target.wm_base.get_xdg_surface(self.surface) + self.xdg_surface.dispatcher["configure"] = self._on_configure + self.toplevel = self.xdg_surface.get_toplevel() + # The whole reason this program exists rather than `wev`. + self.toplevel.set_app_id(target.app_id) + self.toplevel.set_title(target.title) + self.toplevel.dispatcher["configure"] = self._on_toplevel_configure + self.toplevel.dispatcher["close"] = lambda *_: sys.exit(0) + self.surface.commit() + + def _on_toplevel_configure(self, toplevel, width, height, states) -> None: + if width and height: + self.size = (width, height) + + def _on_configure(self, xdg_surface, serial) -> None: + xdg_surface.ack_configure(serial) + self._paint() + say(f"target: window configured {self.size[0]}x{self.size[1]}") + + def _paint(self) -> None: + width, height = self.size + stride = width * 4 + size = stride * height + if self._map is None or self._map.size() < size: + self._allocate(size) + # A flat fill, written once per resize: the pixels are not the subject + # of any assertion, they only make the surface mappable. + self._map.seek(0) + self._map.write(struct.pack(" None: + fd = os.memfd_create("hhs-keyboard-target", 0) + os.ftruncate(fd, size) + self._map = mmap.mmap(fd, size) + self._pool = self.target.shm.create_pool(fd, size) + os.close(fd) + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser( + prog="hhs-keyboard-target", + description="A Wayland window that reports the key events it receives, " + "decoded with the keymap the compositor forwarded.", + ) + parser.add_argument( + "--app-id", + default=None, + help="xdg_toplevel app id; the default is $HHSTREAM_APP_ID, which is how " + "a session's window rule finds its container", + ) + parser.add_argument("--title", default="hhs-keyboard-target") + args = parser.parse_args(argv) + + app_id = args.app_id or os.environ.get("HHSTREAM_APP_ID") + if not app_id: + print( + "hhs-keyboard-target: no --app-id and no $HHSTREAM_APP_ID; refusing to " + "guess, because the app id is the whole point of this program", + file=sys.stderr, + ) + return 2 + + # The broker kills the process group; exit on the first signal rather than + # leaving the compositor to notice a dead client. + signal.signal(signal.SIGTERM, lambda *_: sys.exit(0)) + signal.signal(signal.SIGINT, lambda *_: sys.exit(0)) + return Target(app_id, args.title).run() + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/checks/lib/session-machine.nix b/checks/lib/session-machine.nix index b09fb76..fd3a6e9 100644 --- a/checks/lib/session-machine.nix +++ b/checks/lib/session-machine.nix @@ -29,6 +29,17 @@ # Only read when `pointer` is true; the module's own defaults otherwise. leaseTtl ? 30, leaseMax ? 300, + # The XKB layout the pointer unit uploads as its virtual keyboard's keymap. + # There is no `keyboard.enable`: the keyboard is the same unit, the same + # process and the same lease as the pointer, so `pointer = true` is what + # turns typing on. This is only the layout, and `vm-keyboard` is the only + # check that sets it to anything but the default -- it runs twice, once per + # layout, because the layout only reaches the keymap through this unit's + # argv and a second value is the only way to prove that. + keyboardLayout ? "us", + keyboardModel ? "pc105", + keyboardVariant ? "", + keyboardOptions ? "", width ? 1280, height ? 720, fps ? 30, @@ -73,6 +84,12 @@ enable = pointer; inherit leaseTtl leaseMax; }; + keyboard = { + layout = keyboardLayout; + model = keyboardModel; + variant = keyboardVariant; + options = keyboardOptions; + }; }; }; @@ -106,7 +123,7 @@ environment.systemPackages = [ testTools # hhs-hyprland-diagnostics - sessionTools # hhs-ipc-watch, hhs-pointer-target + sessionTools # hhs-ipc-watch, hhs-pointer-target, hhs-keyboard-target hhstream # the CLI under test hyprland # hyprctl: the compositor is the source of truth here foot diff --git a/checks/lib/session-tools.nix b/checks/lib/session-tools.nix index ea956ab..7a06632 100644 --- a/checks/lib/session-tools.nix +++ b/checks/lib/session-tools.nix @@ -1,55 +1,105 @@ # The guest programs the session checks need, packaged with the interpreters # they actually require. # -# Separate from `test-tools.nix` because these two need things that one does -# not: `hhs-ipc-watch` imports the shipped `hhstreamd.ipc` (so it needs the -# package on PYTHONPATH -- it is the client under test, not a reimplementation -# of it), and `hhs-pointer-target` is a Wayland client (so it needs pywayland). +# Separate from `test-tools.nix` because these need things that one does not: +# `hhs-ipc-watch` imports the shipped `hhstreamd.ipc` (so it needs the package +# on PYTHONPATH -- it is the client under test, not a reimplementation of it), +# and the two targets are Wayland clients (so they need pywayland, and the +# keyboard one also xkbcommon). # -# Both are self-tested at build time, for the same reason test-tools.nix does -# it: a broken helper otherwise surfaces as a baffling VM failure three layers -# away, long after the thing that would have explained it scrolled past. +# All three are self-tested at build time, for the same reason test-tools.nix +# does it: a broken helper otherwise surfaces as a baffling VM failure three +# layers away, long after the thing that would have explained it scrolled past. +# +# ─── NO HEREDOC HERE, AND THAT IS NOT A STYLE PREFERENCE ───────────────────── +# This file used to write the `hhs-ipc-watch` shim with `cat > $out/bin/... < $out/bin/hhs-ipc-watch < /dev/null $out/bin/hhs-pointer-target --help > /dev/null + $out/bin/hhs-keyboard-target --help > /dev/null ${waylandPython}/bin/python3 -c 'from pywayland.protocol.xdg_shell import XdgWmBase' - # The target refuses to guess an app id, and the checks depend on that + + # xkbcommon, and a keymap that really compiles: the keyboard target decodes + # every symbol through this, so a broken binding would show up in the guest + # as every key arriving with an undecodable symbol and no explanation. + ${keyboardPython}/bin/python3 -c 'from xkbcommon import xkb; k = xkb.Context().keymap_new_from_names(rules="evdev", model="pc105", layout="us"); assert xkb.keysym_get_name(k.state_new().key_get_one_sym(38)) == "a"' + + # Both targets refuse to guess an app id, and the checks depend on that # refusal being exit 2 rather than a window with somebody else's class. - if $out/bin/hhs-pointer-target; then - echo "hhs-pointer-target started with no app id; it must refuse" >&2 - exit 1 - fi + for target in hhs-pointer-target hhs-keyboard-target; do + if $out/bin/$target; then + echo "$target started with no app id; it must refuse" >&2 + exit 1 + fi + done '' diff --git a/checks/vm-keyboard.nix b/checks/vm-keyboard.nix new file mode 100644 index 0000000..efbc969 --- /dev/null +++ b/checks/vm-keyboard.nix @@ -0,0 +1,975 @@ +# checks..vm-keyboard -- the keymap, the focus, and a symbol a client decoded. +# +# The resolver's arithmetic is already proved by the unit suite against real +# xkbcommon, and the lease's by an injected clock. What no fake can prove is +# the half this check is for: that the keymap we upload reaches a real +# compositor, that `pointer acquire` leaves the aimed window holding the +# *keyboard* and not merely the cursor, and that an application underneath +# decodes the symbol we meant from the keymap it was forwarded. +# +# `docs/TODO/scroll-has-no-compositor-proof.md` is the precedent this exists to +# avoid: scroll shipped on the driver socket with no compositor proof. The +# keyboard's only purpose is that a client receives symbols, so a unit suite +# alone would be testing the shape of a request nobody answered. +# +# ─── WHY THE VICTIM DECODES, AND WHY THAT IS THE MUTATION RULE ─────────────── +# PLAN §14: read back the *application's* state. For the keyboard that is +# sharper than for the pointer, because there are two ways to be wrong and +# only one of them shows in the keycodes. +# +# `hhs-keyboard-target` (checks/lib/keyboard_target.py) compiles the keymap the +# compositor sent it over `wl_keyboard.keymap` and decodes every key through +# that, printing `code= state= sym=`. So: +# +# * a driver that stopped uploading a keymap leaves the client with nothing +# to decode with, every key arrives as `sym=?`, and the character +# assertions go red -- which is the mutation PLAN §14 asks for: keycodes +# without a decoded `hello` are a failure, not a pass; +# * a driver that uploaded the WRONG layout is caught by the same lines, in +# two places: the `symbols=` line names `pc_us_inet(evdev)` against +# `pc_de_inet(evdev)`, and a keysym's evdev code differs between them. +# +# A victim with its own keymap would decode `hello` from either, and the check +# would be asserting that this file can spell. +# ───────────────────────────────────────────────────────────────────────────── +# +# ─── WHY IT RUNS TWICE, ONCE PER LAYOUT ────────────────────────────────────── +# `sessions.keyboard.layout` reaches the uploaded keymap through exactly one +# path: `--xkb-layout` on `hhstream-pointer`'s ExecStart. A single-layout check +# cannot tell that path from a hardcoded `us`, and the unit test that reads the +# flag cannot tell it from a module that renders the option somewhere nothing +# reads -- which is what an earlier draft of the plan proposed (`[keyboard]` in +# the broker's TOML, read by `hhstreamd`, which is a different unit). +# +# So `default.nix` exposes `vm-keyboard` (layout `us`) and `vm-keyboard-de` +# (layout `de`), both from this file. Everything is asserted in both; the +# layout-dependent expectations come from `EXPECT` below. Hyprland's own +# `input:kb_layout` is deliberately left alone in both -- it stays `us`, so on +# the `de` run a client that ignored our keymap would decode the `us` answer +# and the check would say so. +# ───────────────────────────────────────────────────────────────────────────── +# +# ─── WHERE THIS DEVIATES FROM THE WRITTEN SPEC, AND WHY ────────────────────── +# `docs/plans/2026-10-04-keyboard-verification.md` §B3's layout subtest says +# "`keyboard type y` decodes to sym `z`". **That expectation is wrong for a +# victim that decodes from the forwarded keymap**, which the same section +# requires two paragraphs earlier. `keyboard type y` resolves keysym `y` +# against the uploaded layout and sends *that layout's* code for it; the client +# then decodes the same code with the same keymap and gets `y` back. The sym is +# `y` on both layouts, by construction, and a check asserting `z` would fail +# against a correct driver. +# +# What actually differs between the layouts, and is asserted here instead: +# +# * the EVDEV CODE keysym `y` lives on (21 on us, 44 on de -- they swap); +# * the `symbols=` name in the forwarded keymap; +# * whether `ü` is typeable at all (exit 2 on us, `udiaeresis` on de). +# +# The third is the strongest: it is a behavioural difference no amount of +# decoding confusion can fake. +# +# §B3's subtest 1 says "`pointer acquire` on A, **one warp**", and +# `docs/reviews/2026-10-04-stage0-review.md` is blunter: "Do not assert +# `wl_keyboard.enter` on `pointer acquire`. Acquire is one warp." Both were +# right when written and are now superseded by an operator decision: acquire +# grabs the keyboard as well as the cursor, so it sends **two** warps a real +# pixel apart and `nix/hyprland-conf.nix` pins the threshold the second one +# depends on. The enter assertion is therefore live rather than expected-red -- +# and the review's reason for doubting it is exactly why this check asserts the +# keyboard half separately from the pointer half, instead of trusting that a +# delivered cursor implies delivered keys. +# +# The victim's lines are the Stage 0 probe's with two deliberate differences: +# every line is prefixed `keyboard ` or `pointer `, and the key state carries +# its name. The prefix is not cosmetic -- `wl_pointer.enter` contains the +# substring `enter`, and an unanchored match of one reporting the other is a +# false pass this project has already shipped once, in the probe itself. +# ───────────────────────────────────────────────────────────────────────────── +# +# Real time, no injected clock, same as `vm-pointer`: the expiry subtest uses a +# caller-supplied `--ttl` of a few seconds and waits for it. An injected clock +# would prove the arithmetic the unit suite already proves, and not the +# sweeper, the `release_all` it calls, or the key-up the client has to be told +# about. +{ + testers, + hhstream, + hhsModule, + testTools, + hyprland, + foot, + jq, + grim, + procps, + coreutils, + dejavu_fonts, + width ? 1280, + height ? 720, + sessionUser ? "hermes", + # Deliberately much longer than `vm-pointer`'s, and the expiry subtest does + # not use them: it supplies its own `--ttl` of a few seconds, which is the + # only place a deadline is under test. + # + # These are generous because every verb below is a `systemd-run` round trip + # of several seconds and this check has three times as many of them. At + # `vm-pointer`'s 120 s hard cap, the lease taken in the acquire subtest would + # expire somewhere in the middle of the script -- and the symptom would be a + # later subtest failing with exit 9 for a reason that has nothing to do with + # what it asserts. `hold()` in the script is the other half of that guard. + leaseTtl ? 60, + leaseMax ? 600, + # `us` or `de`; see the block above for why both exist. + keyboardLayout ? "us", +}: +testers.runNixOSTest ( + { pkgs, lib, ... }: + 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; + }; + target = pkgs.writeShellScript "hhs-keyboard-target-wrapper" '' + exec ${tools}/bin/hhs-keyboard-target --app-id "$HHSTREAM_APP_ID" "$@" + ''; + + # What this layout is expected to do, as data rather than as branches in + # the script. Both runs assert every row; only the values differ. + expectations = { + us = { + symbols = "pc_us_inet(evdev)"; + yCode = 21; # KEY_Y + zCode = 44; # KEY_Z + # `ü` has no keysym on a plain `us` map, so the whole string is refused + # and nothing is typed. + diaeresisTypeable = false; + }; + de = { + symbols = "pc_de_inet(evdev)"; + # The swap: keysym `y` is on the physical Z key and vice versa. + yCode = 44; + zCode = 21; + diaeresisTypeable = true; + }; + }; + expect = + expectations.${keyboardLayout} + or (throw "vm-keyboard has no expectations for layout ${keyboardLayout}"); + in + { + name = "hhstream-vm-keyboard-${keyboardLayout}"; + + # The order of `vm-pointer`'s. This check boots a VM with a + # software-rendered compositor and waits out a real lease TTL; that is slow + # and is not a reason to fold it into a unit test. + globalTimeout = 1800; + + nodes.machine = guest { + inherit + width + height + sessionUser + leaseTtl + leaseMax + keyboardLayout + ; + pointer = true; + apps.target = { + exec = "${target}"; + argsAllow = [ ]; + }; + # NOT set: `input:kb_layout`. It stays at the compositor's own default + # (`us`) in both runs, which is what makes the `de` run meaningful -- a + # client that ignored our uploaded keymap would decode the `us` answer. + # And NOT set: `follow_mouse`, which `nix/hyprland-conf.nix` now ships as + # `1` with `follow_mouse_threshold = 0` beside it. `vm-pointer` overrides + # the first through `extraConfig`; this check deliberately does not, + # because acquire's focus guarantee depends on the shipped values and an + # override here would hide a regression in them. + extraConfig = ""; + }; + + testScript = + prelude + + '' + import re + + LAYOUT = "${keyboardLayout}" + SYMBOLS = "${expect.symbols}" + Y_CODE = ${toString expect.yCode} + Z_CODE = ${toString expect.zCode} + DIAERESIS_TYPEABLE = ${if expect.diaeresisTypeable then "True" else "False"} + POINTER_SOCKET = "/run/hhstream/pointer.sock" + + #: evdev codes from `linux/input-event-codes.h`. These are the integers + #: `wl_keyboard.key` carries; the XKB keycode is 8 higher and never + #: leaves the driver, so asserting 38 for `a` would be asserting an + #: index no client ever sees. + KEY_A = 30 + KEY_LEFTSHIFT = 42 + + #: `wl_keyboard.key_state`. + RELEASED, PRESSED = 0, 1 + + + def target_log(session_id, lines=800): + """Every line the victim has printed so far. + + The session log is the application's own captured stdout and + nothing else -- no broker commands, no echoed arguments -- which is + what makes grepping it an assertion about the client. The parsers + below anchor at the start of a line anyway. + """ + + return machine.succeed(cli(f"logs {session_id} --lines {lines}"), timeout=120) + + + def keys(session_id): + """(code, state, sym) from every `keyboard key` line, in order.""" + + found = [] + for line in target_log(session_id).splitlines(): + match = re.match( + r"keyboard key code=(\d+) state=(\d+) \(\w+\) sym=(\S+)$", line + ) + if match: + found.append( + (int(match.group(1)), int(match.group(2)), match.group(3)) + ) + return found + + + def masks(session_id): + """The `depressed` mask from every `keyboard modifiers` line.""" + + found = [] + for line in target_log(session_id).splitlines(): + match = re.match(r"keyboard modifiers depressed=(\d+) ", line) + if match: + found.append(int(match.group(1))) + return found + + + def events(session_id, prefix): + """Lines starting with `prefix`, in order. + + Anchored, because `pointer enter` and `keyboard enter` both contain + `enter` -- and an unanchored match on one of them reporting the + other is a false pass this project has already made once, in the + Stage 0 probe. + """ + + return [ + line + for line in target_log(session_id).splitlines() + if line.startswith(prefix) + ] + + + def keymap_lines(session_id): + return events(session_id, "keyboard keymap ") + + + def typed(session_id, since): + """The symbols of the key-DOWNS after index `since`. + + Downs only: a tap is a pair, and "the client was told h,e,l,l,o" + reads better as five symbols than as ten. + """ + + return [sym for code, state, sym in keys(session_id)[since:] if state == PRESSED] + + + def first_index(session_id, prefix): + """Line number of the first line starting with `prefix`, or None.""" + + for index, line in enumerate(target_log(session_id).splitlines()): + if line.startswith(prefix): + return index + return None + + + def hold(session_id): + """Make sure `session_id` holds the lease, acquiring if it does not. + + Not laziness: this check runs dozens of verbs and the hard cap is + real, so a lease taken in one subtest cannot be assumed to survive + to a later one. Without this, a cap that expired mid-script would + show up as some unrelated subtest failing with exit 9 -- which is + a true statement about the lease and a useless one about the + assertion that was being made. + + It never *releases*, so a subtest that is deliberately holding a + key keeps it. + """ + + state = cli_json("pointer state --json") + if state["holder"] == session_id: + return state["lease_id"] + if state["holder"] is not None: + machine.succeed(cli(f"pointer release {state['holder']}"), timeout=120) + return cli_json(f"pointer acquire --json {session_id}", timeout=120)["lease_id"] + + + def start_target(): + """Start a session and wait for its window to reach its container. + + It dumps its *own* session's log on failure rather than leaving + that to the caller, and that is not tidiness: the caller's + `alpha, alpha_output = start_target()` has not bound `alpha` yet + when this raises, so a `dump(..., locals().get("alpha"))` in the + subtest gets `None` and prints every diagnostic except the one + that matters -- the application's own captured output. Measured, + by a run that failed here and said nothing about why. + """ + + session_id = machine.succeed(cli("start target"), timeout=180).strip() + output = f"hh-{session_id}" + try: + machine.wait_until_succeeds( + f"{HYPRCTL} clients | jq -e --arg m {output}" + " 'any(.initialClass == $m)' >/dev/null", + timeout=120, + ) + wait_for( + lambda: "target: keyboard bound" in target_log(session_id), + timeout=120, + what=f"{session_id} to bind wl_keyboard", + ) + except Exception: + dump(f"{session_id} never mapped a window or bound a keyboard", session_id) + raise + return session_id, output + + + start_all() + bring_up("the compositor and broker") + + with subtest("the driver comes up and uploaded a keymap for this layout"): + # The unit's own journal is where a layout xkbcommon refused shows + # up, as exit 2 before any Wayland call -- which is a restart loop + # with its own words in it rather than a silent default. + try: + machine.wait_for_unit("hhstream-pointer.service", timeout=180) + machine.wait_for_file(POINTER_SOCKET, timeout=120) + restarts = machine.succeed( + "systemctl show -p NRestarts --value hhstream-pointer.service" + ).strip() + assert restarts == "0", ( + f"the driver has restarted {restarts} time(s); read its journal" + ) + journal = machine.succeed( + "journalctl --no-pager --boot --unit hhstream-pointer.service" + ) + print(journal) + assert "uploaded a" in journal and "keymap" in journal, ( + "the driver never logged a keymap upload. `key` before " + "`keymap` is the protocol error `no_keymap`, which kills " + "the connection rather than answering, so this must happen " + "before the socket listens:\n" + journal + ) + # The flag really is on the command line, with this layout. + argv = machine.succeed( + "systemctl show -p ExecStart --value hhstream-pointer.service" + ) + print(argv) + assert f"--xkb-layout {LAYOUT}" in argv, ( + f"the unit does not pass --xkb-layout {LAYOUT}: {argv}" + ) + except Exception: + dump("the driver did not come up with a keymap") + raise + + with subtest("a session's window is in its container, and binds a keyboard"): + # The seat of a headless session has no keyboard capability until + # something creates a virtual one: there is no input device here. + # So "target: keyboard bound" is itself proof that the driver's + # `zwp_virtual_keyboard_v1` reached the seat, and not merely that + # the broker believes it sent something. + try: + alpha, alpha_output = start_target() + print(f"session {alpha} -> {alpha_output}") + print(target_log(alpha)) + except Exception: + # `start_target` dumps its own session's log; this covers the + # case where `start` itself failed and there is no session id + # to dump -- a target that exited immediately, for instance, + # which is exit 4 with the reason only in the broker's log. + dump("the victim never got a window or a keyboard", locals().get("alpha")) + raise + + with subtest("the client was forwarded the keymap this layout names"): + # The direct proof that our upload arrived, and the thing that + # tells the two layouts apart independently of any keystroke. + try: + lines = wait_for( + lambda: keymap_lines(alpha), + timeout=120, + what="the compositor to forward a keymap", + ) + print("\n".join(lines)) + assert len(lines) == 1, ( + f"the client was sent {len(lines)} keymaps; the driver uploads " + f"exactly one, after connect and before listen: {lines}" + ) + assert "WILL-NOT-COMPILE" not in lines[0], lines[0] + assert "UNREADABLE" not in lines[0], lines[0] + assert "format=1" in lines[0], ( + f"the keymap arrived in a format other than xkb_v1: {lines[0]}" + ) + assert SYMBOLS in lines[0], ( + f"the forwarded keymap is not {LAYOUT}: {lines[0]}. Expected " + f"symbols={SYMBOLS}. A `de` run that says pc_us_inet means " + "--xkb-layout never reached xkb_keymap_new_from_names." + ) + # And it arrived BEFORE any key did, which is the verification + # doc's own rule: a decoded symbol is only evidence of our + # upload if the client had the keymap when the key arrived. + # Asserted on log position and not on subtest order, because + # subtest order is this file's choice and log position is the + # compositor's. + keymap_at = first_index(alpha, "keyboard keymap ") + key_at = first_index(alpha, "keyboard key ") + print(f"keymap at line {keymap_at}, first key at line {key_at}") + assert keymap_at is not None + assert key_at is None or keymap_at < key_at, ( + f"a key arrived at line {key_at} before the keymap at " + f"{keymap_at}; every symbol decoded before that is a guess" + ) + except Exception: + dump("the keymap did not reach the client", alpha) + raise + + with subtest("a second session takes focus, which is what subtest 4 needs"): + # Started here, and not in the subtest that needs it, because what + # makes it useful is that its window opened LAST: that is how it + # holds focus, and it is the situation `vm-pointer` found the hard + # way. Both sessions exist from here on. + try: + beta, beta_output = start_target() + print(f"session {beta} -> {beta_output}") + focused = [ + c.get("initialClass") + for c in compositor("clients") + if c.get("focusHistoryID") == 0 + ] + print(f"the compositor's focused window belongs to: {focused}") + assert focused and focused[0] == beta_output, ( + f"this check needs {beta} focused after it opened; {focused} is. " + "Every assertion below about acquire moving focus is " + "vacuous otherwise." + ) + # And it is the keyboard focus, not merely the stacking order: + # beta was told it has the keys. + wait_for( + lambda: events(beta, "keyboard enter"), + timeout=60, + what=f"{beta} to be told it holds keyboard focus", + ) + except Exception: + dump("the second session did not take focus", locals().get("beta")) + raise + + with subtest("acquire takes the KEYBOARD as well as the cursor"): + # The measurement this whole feature turns on, and the one a + # careless version of this check would fake. + # + # `pointer acquire` warps into alpha's container while BETA holds + # keyboard focus. A check that asserted only `pointer enter` on + # alpha would go green while alpha had the cursor, beta had the + # keys, and the first keystroke of the lease went to beta -- which + # is exactly what one warp does: Hyprland zeroes `m_mousePosDelta` + # when the previous movement was over 0.5s ago, and keyboard focus + # is that delta compared against `input:follow_mouse_threshold`. + # + # So acquire sends two motions a real pixel apart, and this subtest + # asserts BOTH halves: the cursor arrived (pointer enter on alpha) + # and the keys moved with it (keyboard enter on alpha, keyboard + # leave on beta). + try: + before_pointer = len(events(alpha, "pointer enter")) + before_enter = len(events(alpha, "keyboard enter")) + before_leave = len(events(beta, "keyboard leave")) + + reply = cli_json(f"pointer acquire --json {alpha}", timeout=120) + print(json.dumps(reply, indent=2, sort_keys=True)) + assert reply["bookmark"]["output"] == alpha_output, reply + assert reply["focus"] == "warp", ( + f"acquire reports focus={reply['focus']!r}; `warp` is the " + "path that should have run. `focuswindow` means the nudge " + "could not be sent, `none` that neither worked." + ) + + wait_for( + lambda: events(alpha, "pointer enter")[before_pointer:], + timeout=60, + what=f"{alpha} to be told the cursor arrived", + ) + entered = wait_for( + lambda: events(alpha, "keyboard enter")[before_enter:], + timeout=60, + what=( + f"{alpha} to be told it holds KEYBOARD focus after acquire. " + "The cursor arriving is not enough: see the comment above " + "this subtest" + ), + ) + left = wait_for( + lambda: events(beta, "keyboard leave")[before_leave:], + timeout=60, + what=f"{beta} to be told it lost keyboard focus", + ) + print(f"{alpha} entered: {entered}") + print(f"{beta} left: {left}") + lease = reply["lease_id"] + except Exception: + dump("acquire did not move keyboard focus to the aimed session", alpha) + raise + + with subtest("a capital is a modifier MASK and not a Shift keycode"): + # The worked example, and the one place a toolkit could be right + # for the wrong reason. Hyprland's virtual keyboard never runs + # `updateXkbStateWithKey`, so an injected KEY_LEFTSHIFT changes no + # modifier state at all -- the mask is the only thing that makes a + # capital, and sending both is how a client shifts twice or not at + # all. The client prints the mask and the sym, so both are checked. + try: + hold(alpha) + before = len(keys(alpha)) + before_masks = len(masks(alpha)) + machine.succeed(cli(f"keyboard type {alpha} A"), timeout=120) + + pair = wait_for( + lambda: ( + keys(alpha)[before:] if len(keys(alpha)) >= before + 2 else None + ), + timeout=60, + what="the client to report a press and a release of `A`", + ) + print(f"the client reports keys: {pair}") + assert [(c, s) for c, s, _ in pair] == [ + (KEY_A, PRESSED), + (KEY_A, RELEASED), + ], f"`type A` delivered {pair}; it must be one press and one release" + assert [sym for _, _, sym in pair] == ["A", "A"], ( + f"the client decoded {pair}, not `A`. A `sym=a` here means the " + "mask did not arrive before the key; a `sym=?` means no keymap " + "was ever uploaded and the character assertions are vacuous." + ) + assert not any(code == KEY_LEFTSHIFT for code, _, _ in pair), ( + f"a Shift keycode was injected for a capital: {pair}" + ) + + span = masks(alpha)[before_masks:] + print(f"the client reports masks: {span}") + # `any`, not `span[0]`, and the ordering is carried by `sym=A` + # instead. The focus change from the acquire sends its own + # `modifiers depressed=0`, which can land in this span or the + # previous one depending on when the log was polled -- so a + # positional assertion here would flake for a reason that has + # nothing to do with the capital. + # + # `sym=A` above is the stronger ordering proof anyway: the + # client decodes through its own xkb state, so it can only + # report `A` if Shift was in the mask it had been given WHEN + # the key arrived. A mask sent after the key decodes as `a`. + assert any(m != 0 for m in span), ( + f"no non-zero modifier mask arrived for `A`: {span}. Without " + "it a client that decodes from wl_keyboard.modifiers gets `a`." + ) + assert span[-1] == 0, ( + f"the mask was not cleared after the capital: {span}. A " + "virtual key-up clears no modifier state, so a mask left set " + "makes every later letter a capital." + ) + except Exception: + dump("a capital did not arrive as a capital", alpha) + raise + + with subtest("`hello` arrives on the holder and nowhere else"): + # Positive and negative in one subtest, because they need the same + # moment: a string delivered to alpha is only evidence if beta, + # which held focus until the acquire, was told nothing. + try: + hold(alpha) + before = len(keys(alpha)) + before_beta = len(keys(beta)) + machine.succeed(cli(f"keyboard type {alpha} hello"), timeout=120) + + wait_for( + lambda: len(typed(alpha, before)) >= 5 or keys(beta)[before_beta:], + timeout=60, + what=f"either {alpha} or {beta} to report the string", + ) + mine = typed(alpha, before) + theirs = keys(beta)[before_beta:] + print(f"the holder {alpha} decoded: {mine}") + print(f"the other {beta} reports: {theirs}") + assert not theirs, ( + f"the string was typed into the lease holder {alpha} and " + f"{beta} received {theirs}. One seat, one focus: this is the " + "failure the lease exists to prevent." + ) + assert mine == ["h", "e", "l", "l", "o"], ( + f"the holder decoded {mine}, not h,e,l,l,o. `?` symbols mean " + "no keymap was uploaded -- keycodes without decoded symbols " + "are a failure, not a pass (PLAN §14)." + ) + assert all(sym != "?" for _, _, sym in keys(alpha)[before:]), ( + "a key arrived with no decodable symbol" + ) + except Exception: + dump("the string did not arrive on the holder alone", alpha) + raise + + with subtest("`Return` is a key with no character, and arrives as one"): + # `keyboard key`, the verb `type` cannot express: Return, Tab, + # BackSpace and the arrows have no character to put in a string. + try: + hold(alpha) + before = len(keys(alpha)) + machine.succeed(cli(f"keyboard key {alpha} Return"), timeout=120) + pair = wait_for( + lambda: ( + keys(alpha)[before:] if len(keys(alpha)) >= before + 2 else None + ), + timeout=60, + what="the client to report Return pressed and released", + ) + print(f"the client reports: {pair}") + assert [sym for _, _, sym in pair] == ["Return", "Return"], pair + assert [s for _, s, _ in pair] == [PRESSED, RELEASED], ( + f"a tap must be exactly one press and one release: {pair}" + ) + except Exception: + dump("Return did not arrive", alpha) + raise + + with subtest("this layout's own keycodes, which is how `de` differs"): + # `type y` resolves keysym `y` against the uploaded layout and + # sends THAT layout's code for it. The client decodes the same code + # with the same keymap, so the sym is `y` on both layouts -- see + # the block at the top of this file -- and the CODE is what differs: + # 21 on us, 44 on de. They swap. + try: + hold(alpha) + for character, want_code in (("y", Y_CODE), ("z", Z_CODE)): + hold(alpha) + before = len(keys(alpha)) + machine.succeed(cli(f"keyboard type {alpha} {character}"), timeout=120) + pair = wait_for( + lambda: ( + keys(alpha)[before:] + if len(keys(alpha)) >= before + 2 + else None + ), + timeout=60, + what=f"the client to report `{character}`", + ) + print(f"`type {character}` on {LAYOUT} -> {pair}") + assert [sym for _, _, sym in pair] == [character, character], ( + f"the client decoded {pair}, not `{character}`" + ) + assert all(code == want_code for code, _, _ in pair), ( + f"`{character}` on {LAYOUT} arrived as code " + f"{pair[0][0]}, not {want_code}. us and de swap y and z, " + "so the wrong code here means the wrong layout was " + "uploaded even though the symbol decoded correctly." + ) + except Exception: + dump("this layout's keycodes are not what it should produce", alpha) + raise + + with subtest("a character this layout cannot produce is exit 2, and types nothing"): + # The behavioural difference between the two layouts that no + # decoding confusion can fake: `ü` is an ordinary key on `de` and + # has no keysym at all on a plain `us` map. + try: + hold(alpha) + before = len(keys(alpha)) + # Both branches assert on the broker's own fields rather than + # on prose, and both pin something a VM can get wrong + # independently of the layout: that the non-ASCII argument + # survived argv decoding as ONE scalar. `chars == 4` on the + # typeable path, and `scalar 3 (U+00FC)` on the other, are + # both false if it arrived as two surrogates. + if DIAERESIS_TYPEABLE: + reply = cli_json(f"keyboard type --json {alpha} 'cafü'") + print(f"`type cafü` on {LAYOUT}: {reply}") + assert reply["chars"] == 4, ( + f"the broker counted {reply['chars']} scalars in " + "`cafü`, not 4; the argument did not survive as UTF-8" + ) + symbols = wait_for( + lambda: ( + typed(alpha, before) + if len(typed(alpha, before)) >= 4 + else None + ), + timeout=60, + what="the client to report c,a,f,udiaeresis", + ) + print(f"the client decoded: {symbols}") + assert symbols == ["c", "a", "f", "udiaeresis"], symbols + else: + code, out = machine.execute( + cli(f"keyboard type --json {alpha} 'cafü'") + " 2>&1", + timeout=120, + ) + print(f"`type cafü` on {LAYOUT}: exit {code}: {out}") + assert code == 2, ( + f"an unmappable character exited {code}, not 2. Exit 10 " + "would be reporting the caller's typo as a compositor " + "failure -- see the verification doc's change 1." + ) + assert "ü" not in out, ( + f"the refusal quotes the character it refused: {out!r}. A " + "typed string is a password as often as not and this " + "reaches a log." + ) + assert "caf" not in out, ( + f"the refusal quotes the string it refused: {out!r}" + ) + # The index AND the codepoint: `scalar 3` alone would be + # printed for a mangled argument too, and `U+00FC` is what + # says the broker saw the character the operator typed. + assert "scalar 3" in out and "U+00FC" in out, ( + f"the refusal does not name scalar 3 (U+00FC): {out!r}" + ) + # And no prefix: `c`, `a` and `f` must not have been typed. + machine.sleep(3) + after = keys(alpha)[before:] + print(f"the client reports after the refusal: {after}") + assert after == [], ( + f"a refused string typed a prefix: {after}. Validation is " + "complete before the first event, so there is nothing to " + "clean up -- or there should be." + ) + except Exception: + dump("the unmappable-character path is wrong for this layout", alpha) + raise + + with subtest("a chord holds a modifier across a type and leaves it held"): + # The justified use of `down`: `Control_L` held, a character typed + # with its mask ORed in, and Control still down afterwards. The + # client sees the mask, which is the only thing a chord is. + try: + hold(alpha) + before_masks = len(masks(alpha)) + machine.succeed(cli(f"keyboard down {alpha} Control_L"), timeout=120) + held = cli_json("pointer state --json") + print(json.dumps(held, indent=2, sort_keys=True)) + assert held["keys"] == ["Control_L"], held + + control = wait_for( + lambda: [m for m in masks(alpha)[before_masks:] if m != 0], + timeout=60, + what="the client to be told Control is depressed", + ) + print(f"the client reports a depressed mask of {control}") + + before = len(keys(alpha)) + machine.succeed(cli(f"keyboard type {alpha} c"), timeout=120) + pair = wait_for( + lambda: ( + keys(alpha)[before:] if len(keys(alpha)) >= before + 2 else None + ), + timeout=60, + what="the client to report `c` under Control", + ) + print(f"Ctrl+c delivered: {pair}") + # Control is STILL held: a chord spans three CLI invocations, + # and a `type` that lifted it would make that impossible. + still = cli_json("pointer state --json") + assert still["keys"] == ["Control_L"], ( + f"`type` under a held modifier lifted it: {still}" + ) + machine.succeed(cli(f"keyboard up {alpha} Control_L"), timeout=120) + assert cli_json("pointer state --json")["keys"] == [] + except Exception: + dump("a chord did not hold across the type", alpha) + raise + + with subtest("a second acquire during a hold is refused with BUSY"): + # Held deliberately across the refusal: a contended acquire must + # not disturb a chord somebody is in the middle of. + try: + hold(alpha) + machine.succeed(cli(f"keyboard down {alpha} Shift_L"), timeout=120) + assert cli_json("pointer state --json")["keys"] == ["Shift_L"] + + code, out = machine.execute( + cli(f"pointer acquire {beta}") + " 2>&1", timeout=120 + ) + print(f"exit {code}: {out}") + assert code == 8, f"a contended acquire exited {code}, not 8 (BUSY)" + assert alpha in out, f"the refusal does not name the holder: {out!r}" + state = cli_json("pointer state --json") + assert state["holder"] == alpha, state + assert state["keys"] == ["Shift_L"], ( + f"the refused acquire disturbed the holder's chord: {state}" + ) + machine.succeed(cli(f"keyboard up {alpha} Shift_L"), timeout=120) + except Exception: + dump("a contended acquire was not refused cleanly", alpha) + raise + + with subtest("typing without the lease is exit 9, and reaches no client"): + try: + before = len(keys(alpha)) + before_beta = len(keys(beta)) + code, out = machine.execute( + cli(f"keyboard type {beta} nope") + " 2>&1", timeout=120 + ) + print(f"exit {code}: {out}") + assert code == 9, ( + f"typing with no lease exited {code}, not 9. 9 says `acquire " + "one`, 8 says `wait for someone`, and conflating them is how " + "a retry loop spins." + ) + machine.sleep(3) + assert keys(beta)[before_beta:] == [], "a refused type still typed" + assert keys(alpha)[before:] == [], "a refused type went to the holder" + except Exception: + dump("a type without a lease was not refused", beta) + raise + + with subtest("an expired lease lifts the key it left down, and clears the mask"): + # Real time, a caller-supplied TTL, nothing touching the lease. The + # sweeper is what makes the TTL a promise: without it expiry would + # only be noticed by the next verb, so an agent that held Shift and + # died would hold the keyboard -- with Shift down -- until somebody + # else happened to try. + # + # `Shift_L` on purpose, and code 42 is why: `type` must never emit + # a Shift keycode, so a `state=0` for 42 cannot be a leftover from + # any earlier subtest. A `state=0` for code 30 could be. + try: + short = 8 + state = cli_json("pointer state --json") + if state["holder"] is not None: + machine.succeed( + cli(f"pointer release {state['holder']}"), timeout=120 + ) + cli_json(f"pointer acquire --json --ttl {short}s {alpha}", timeout=120) + before = len(keys(alpha)) + before_masks = len(masks(alpha)) + machine.succeed(cli(f"keyboard down {alpha} Shift_L"), timeout=120) + + held = cli_json("pointer state --json") + print(json.dumps(held, indent=2, sort_keys=True)) + assert held["keys"] == ["Shift_L"], held + wait_for( + lambda: [ + k for k in keys(alpha)[before:] if k[0] == KEY_LEFTSHIFT + ], + timeout=60, + what="the client to be told Shift went down", + ) + + # One bounded wait for the deadline to arrive, not a retry of + # the assertion: the lease expires on its own or it does not. + machine.wait_until_succeeds( + cli("pointer state --json") + " | jq -e '.holder == null' >/dev/null", + timeout=short * 6 + 120, + ) + state = cli_json("pointer state --json") + print(json.dumps(state, indent=2, sort_keys=True)) + assert state["keys"] == [], ( + f"the lease expired with a key still down: {state}" + ) + assert state["buttons"] == [], state + + shift = wait_for( + lambda: ( + [k for k in keys(alpha)[before:] if k[0] == KEY_LEFTSHIFT] + if len( + [k for k in keys(alpha)[before:] if k[0] == KEY_LEFTSHIFT] + ) + >= 2 + else None + ), + timeout=60, + what="the client to be told Shift came back up", + ) + print(f"the client reports for code {KEY_LEFTSHIFT}: {shift}") + assert [s for _, s, _ in shift] == [PRESSED, RELEASED], ( + f"the application was told Shift went down and never that it " + f"came up: {shift}. On this compositor that is worse than a " + "stuck key: InputManager::onKeyboardKey drops the NEXT press " + "of a code it still believes is down, so the key is dead." + ) + span = masks(alpha)[before_masks:] + print(f"the client reports masks: {span}") + assert span and span[-1] == 0, ( + f"the mask was not cleared when the lease expired: {span}. " + "`release_pressed_on_close` would not have done it either -- " + "it emits key-ups and never a `modifiers` -- which is why " + "release_all sends modifiers(0, 0, 0, 0) itself." + ) + except Exception: + dump("the lease did not expire cleanly", alpha) + raise + + with subtest("release lifts a held key and says which"): + try: + hold(alpha) + machine.succeed(cli(f"keyboard down {alpha} Control_L"), timeout=120) + released = cli_json(f"pointer release --json {alpha}", timeout=120) + print(json.dumps(released, indent=2, sort_keys=True)) + assert released["keys_lifted"] == ["Control_L"], released + assert released["buttons_lifted"] == [], released + state = cli_json("pointer state --json") + assert state["holder"] is None and state["keys"] == [], state + except Exception: + dump("release did not lift the held key", alpha) + raise + + with subtest("the audit log counted the characters and kept none of them"): + # The CLI's own argv is visible to `ps` and that is out of scope; + # `events.jsonl` is what this project controls, and a typed string + # is a password as often as not. + try: + secret = "hunter2" + hold(alpha) + machine.succeed(cli(f"keyboard type {alpha} {secret}"), timeout=120) + machine.succeed(cli(f"pointer release {alpha}"), timeout=120) + + events_json = machine.succeed( + "cat /var/lib/hhstream/events.jsonl", timeout=120 + ) + typed_events = [ + json.loads(line) + for line in events_json.splitlines() + if '"keyboard_type"' in line + ] + print(json.dumps(typed_events[-3:], indent=2, sort_keys=True)) + assert typed_events, "no keyboard_type event was recorded at all" + assert any(e.get("chars") == len(secret) for e in typed_events), ( + f"no event recorded a character count of {len(secret)}: " + f"{typed_events[-3:]}" + ) + assert secret not in events_json, ( + "the audit log contains the typed string. It records a count " + "and never the text, deliberately." + ) + except Exception: + dump("the audit log is not what it should be", alpha) + raise + ''; + } +)