From a6a4094e6a9cae91ed3efc1f1f7d09467cd59254 Mon Sep 17 00:00:00 2001 From: Hermenix Date: Sun, 4 Oct 2026 20:23:14 +0000 Subject: [PATCH] Stage 3: vm-keyboard, and the helper derivation that never built MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The keyboard's only purpose is that a client receives symbols, so a unit suite alone was testing the shape of a request nobody answered -- docs/TODO/scroll-has-no-compositor-proof.md is the precedent. This is the compositor proof: two nixosTests, 16 subtests each, real time, no injected clock. nix build --no-link -L .#checks.x86_64-linux.vm-keyboard test script finished in 281.06s (16/16, exit 0) nix build --no-link -L .#checks.x86_64-linux.vm-keyboard-de test script finished in 278.15s (16/16, exit 0) The victim, checks/lib/keyboard_target.py, decodes every keysym from the keymap the COMPOSITOR forwarded rather than from a table of its own. That is the mutation rule PLAN §14 asks for: a driver that stopped uploading leaves the client with nothing to decode with, every key arrives as `sym=?`, and the character assertions go red. A victim with its own keymap would decode `hello` either way and the check would be asserting that the check can spell. What the client actually reported, which is the point of reading back the application's state rather than the broker's intention: type A [(30, 1, 'A'), (30, 0, 'A')] masks [1, 1, 0, 0] -- evdev 30 decoded as A, so the mask arrived BEFORE the key, and no code 42 anywhere key Return [(28, 1, 'Return'), (28, 0, 'Return')] TTL expiry [(42, 1, 'Shift_L'), (42, 0, 'Shift_L')] masks [1,1,0,0] -- lifted by the sweeper alone, mask cleared with it chord depressed mask [4, 4] while Control held, still held after the type returned It runs TWICE because `sessions.keyboard.layout` reaches the uploaded keymap through exactly one path -- `--xkb-layout` on the driver unit's argv -- and one layout cannot tell that path from a hardcoded `us`: us: symbols=pc_us_inet(evdev) bytes=35572 type y -> [(21, 1, 'y')] type z -> [(44, 1, 'z')] type cafü -> exit 2, "scalar 3 (U+00FC) is not typeable", and the client reported [] -- no prefix typed de: symbols=pc_de_inet(evdev) bytes=37532 type y -> [(44, 1, 'y')] type z -> [(21, 1, 'z')] (swapped) type cafü -> {'chars': 4, 'ok': True} client decoded ['c', 'a', 'f', 'udiaeresis'] Hyprland's own input:kb_layout is left at `us` in BOTH runs, so a client that ignored our keymap would decode the us answer on the de machine. The decisive subtest is "acquire takes the KEYBOARD as well as the cursor". With session B holding keyboard focus because its window mapped last, acquire on A delivered wl_pointer.enter AND wl_keyboard.enter to A and wl_keyboard.leave to B, with focus == "warp". A check that asserted only pointer delivery would have gone green while A had the cursor, B had the keys, and the first keystroke of the lease went to B -- which is exactly what one warp does. §B3's "one warp" and the Stage 0 review's "do not assert enter on acquire" are superseded by the two-warp acquire, and the header says so. One deviation from §B3, with reasons in the header: its subtest 4 says `type y` decodes to sym `z`, which is wrong for a victim that decodes from the forwarded keymap -- the same paragraph requires that. `type y` resolves keysym y against the uploaded layout and sends that layout's code; the client decodes it back to `y`. The sym is `y` on both layouts by construction. What differs is the CODE, the symbols name, and whether ü is typeable at all, and those are what this asserts. ── AND A PRE-EXISTING BUG THE FIRST RUN EXPOSED ────────────────────── checks/lib/session-tools.nix opened a heredoc with `< Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM --- README.dev.md | 14 + checks/default.nix | 23 +- checks/lib/keyboard_target.py | 339 ++++++++++++ checks/lib/session-machine.nix | 19 +- checks/lib/session-tools.nix | 106 +++- checks/vm-keyboard.nix | 975 +++++++++++++++++++++++++++++++++ 6 files changed, 1442 insertions(+), 34 deletions(-) create mode 100644 checks/lib/keyboard_target.py create mode 100644 checks/vm-keyboard.nix 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 + ''; + } +)