# 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 ''; } )