Stage 1 review fixes, and Stage 2: the broker, the CLI and the module
The Stage 1 review (docs/reviews/2026-10-04-stage1-review.md, verdict
yes-with-fixes) found a real bug, and it was the kind Stage 2 would have
cemented. All five findings:
(1) HIGH, and reproduced before fixing: `key` resolved the action and
then used only its `code`. So `keyboard key A` sent a bare code 30
and the window received `a`; on `de`, `at` lost its level-three mask
and typed `q`. `type` was the only path that used the mask, which is
why every `type` test stayed green. `key` now sends
modifiers(baseline | mask) before the down and restores the baseline
on the up -- the one-character `type` sequence -- and `Shift_L`
keeps its key-then-mask order, which is the other path on purpose.
The same hole aliased two names onto one keycode: `down A` then
`down a` recorded both and pressed 30 twice, Hyprland dropped the
second, and the held set lied until the lease ended. A second name
for a code already down is now refused.
(2) HIGH: the shutdown comment claimed hyprland-conf.nix sets
input:virtualkeyboard:release_pressed_on_close. It did not. The line
is there now, with the note that it releases keys and still never
clears a mask -- which is why release_all zeroes the mask on every
path we control rather than relying on it.
(3) MEDIUM: nothing would have noticed the keymap upload stopping. A
`main` that connected and listened without uploading passed every
test in the tree. Now asserted on the real sink: uploaded once,
before `listen` (one shared ordering log across both stand-ins), the
payload NUL-terminated with `size == len(utf8) + 1` read back
through the fd, format 1, one terminator not two, and modifiers(0)
straight after.
(4) LOW: `key` up now forgets the name only after a successful send,
like `button` -- otherwise a raise between the two leaves us
believing a key is up that the compositor still has down, and
release_all will not try again.
(5) LOW: `\r` no longer aliases to Return (CRLF would have become two
newlines silently), and an empty layout is refused -- xkbcommon
compiles "" as the same keymap as `us`, so `--xkb-layout ''` looked
configured and typed `us`.
Several of the review's named false passes are closed too: Control's
mask is compared against mod_get_index("Control") rather than merely
"not Shift's"; the keymap text assertion names pc_us_inet/pc_de_inet
instead of substring-matching "us"; the capital-under-Control case
asserts the whole sequence; the exit-code mirror is compared against
hhstreamd.protocol; and the module's defaults are read out of
nix/module.nix rather than asserted against themselves.
Stage 2 proper:
* broker verbs keyboard.key / keyboard.type, both in the mutation set,
both through _refresh (so they refresh the lease and, like every
pointer verb, do NOT count as activity)
* the driver's `kind` token mapped: a bad keysym or character is
invalid_argument (exit 2), a missing keyboard global stays
driver_refused (exit 10). The 4096-scalar cap and the shape checks
are broker-side, because only a broker-side invalid_argument is 2
* keys[] on pointer.state, keys_lifted[] on pointer.release and on
pointer_lease_timeout, one release_all for both halves
* CLI `session keyboard type|key|down|up`, reusing the pointer lease
and its cache; `type` takes one raw argument and interprets nothing;
the audit records a character count and never the text
* sessions.keyboard.{layout,model,variant,options} on the unit's argv,
layout defaulting to "us" with a type that refuses a comma. NO
[keyboard] TOML table: hhstreamd reads that file and the driver is a
different unit, so it would be a setting with no effect
* CONTRACT-sessions.md bumped to v3; README.dev.md item 3 and
vm-pointer.nix's header corrected (both still said the conf ships
follow_mouse = 0 and that the keyboard work would choose)
And the operator decision that acquire grabs both devices: it now sends
two warps a real pixel apart, because one warp onto an idle cursor moves
the cursor and not keyboard focus. follow_mouse_threshold = 0 is set
explicitly in hyprland-conf.nix since the second warp depends on it,
`dispatch focuswindow` is the fallback when the nudge cannot be sent,
and the reply and audit carry which mechanism ran. The acquire test
asserts the pair and that they floor to different pixels -- a test that
only saw wl_pointer.enter would pass while the first keystroke went to
the wrong window.
nix develop -c python -m pytest tests/pointer tests/sessions/unit -q
605 passed in 27.11s
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
This commit is contained in:
1 parent
b1f2744cf0
commit
e6f4c3bb3f
24 files changed
+2474
-105
No files matched your search
@@ -90,7 +90,50 @@ in ''
|
||||
# aimed correctly and delivered nowhere. The cursor lease already
|
||||
# serialises input, so letting the pointer move keyboard focus cannot make
|
||||
# two sessions fight over the keyboard.
|
||||
#
|
||||
# It is also what moves the KEYBOARD, which matters now that the broker
|
||||
# injects keys as well: a virtual keyboard is seat-global and has no
|
||||
# output, so the warp is the only thing that decides which window the
|
||||
# letters land in, and the lease is what stops another session retargeting
|
||||
# them mid-string.
|
||||
follow_mouse = 1
|
||||
|
||||
# Set explicitly, at its default value, because `pointer acquire` now
|
||||
# depends on it rather than merely benefiting from it.
|
||||
#
|
||||
# MEASURED (tests/README-keyboard-probe.md): one warp onto an idle cursor
|
||||
# delivers `wl_pointer.enter` and NO `wl_keyboard.enter`. Hyprland's
|
||||
# `onMouseWarp` goes through `mouseMoveUnified(refocus=false)`, which
|
||||
# *sets* `m_mousePosDelta` to 0 when the previous movement was more than
|
||||
# 0.5 s ago, and keyboard focus is that delta compared against this
|
||||
# threshold. So acquire sends two motions a real pixel apart: the second
|
||||
# carries a non-zero delta, and `> 0` is true only because this is 0.
|
||||
#
|
||||
# Raise it and `hhstream session pointer acquire` stops taking keyboard
|
||||
# focus — the cursor would land in the session's window and the first
|
||||
# keystroke would go to whatever was focused before.
|
||||
follow_mouse_threshold = 0
|
||||
|
||||
# Release a virtual keyboard's held keys when its resource is destroyed.
|
||||
#
|
||||
# MEASURED, and the default is `false`: `destroy` with a key down
|
||||
# delivered no key-up at all. That is worse than a stuck key, because
|
||||
# `InputManager::onKeyboardKey` *drops* a press whose code is already in
|
||||
# the seat's `m_pressed` — so a driver killed with `-9` leaves that code
|
||||
# there and the next driver's press of it is ignored. The key is dead,
|
||||
# not merely held, and nothing in the logs says so.
|
||||
#
|
||||
# The driver's own shutdown path lifts keys first
|
||||
# (`hhstream_pointer.__main__._lift_everything`) and SIGKILL skips it;
|
||||
# this is the backstop for that case.
|
||||
#
|
||||
# It does NOT clear the modifier mask: `releasePressed` emits key-ups and
|
||||
# never a `modifiers`, and a client keeps the last mask it was sent. That
|
||||
# is why `release_all` ends with `modifiers(0, 0, 0, 0)` on every path we
|
||||
# control, and why this setting is a backstop rather than the mechanism.
|
||||
virtualkeyboard {
|
||||
release_pressed_on_close = true
|
||||
}
|
||||
}
|
||||
|
||||
# Frames cost capture bandwidth and CPU, and no one is watching the easing.
|
||||
|
||||
+94
-5
@@ -620,6 +620,80 @@ in {
|
||||
};
|
||||
};
|
||||
|
||||
# The keyboard has no `enable` of its own: it is the same unit, the same
|
||||
# process and the same lease as the pointer (`hhstream session keyboard
|
||||
# …` refuses with exit 9 until `pointer acquire`). What it needs from an
|
||||
# operator is a layout, because the keymap the driver uploads is the only
|
||||
# thing that decides which keycode a keysym is -- Hyprland's own
|
||||
# `input:kb_layout` is not read and does not affect injected keys.
|
||||
keyboard = {
|
||||
layout = lib.mkOption {
|
||||
# `strMatching` and not `str`, and the pattern is the point: it is
|
||||
# what refuses `us,ru`. A comma-separated layout compiles perfectly
|
||||
# well into a two-group keymap, and v1 sends `group = 0` in every
|
||||
# `modifiers` request -- so the second group would be unreachable and
|
||||
# an agent asking for a Cyrillic character would silently get a Latin
|
||||
# one. The driver refuses a comma too, for a binary run by hand.
|
||||
type = lib.types.strMatching "[A-Za-z0-9_-]+";
|
||||
default = "us";
|
||||
example = "de";
|
||||
description = ''
|
||||
XKB layout the `hhstream-pointer` unit compiles once at start-up and
|
||||
uploads as its virtual keyboard's keymap (rules `evdev`, model from
|
||||
{option}`sessions.keyboard.model`).
|
||||
|
||||
**This is the only thing that decides what an injected key means.**
|
||||
Every `hhstream session keyboard` verb names an XKB *keysym*
|
||||
(`a`, `A`, `Return`, `Control_L`), and the driver resolves that name
|
||||
against this keymap to get the evdev code and the modifier mask the
|
||||
compositor is sent. A character this layout cannot produce is
|
||||
refused with exit 2 and nothing is typed -- there is no partial
|
||||
type, so `é` on `us` fails the whole string rather than the letter.
|
||||
|
||||
Hyprland's `input:kb_layout` is **not** read. It describes the
|
||||
layout for physical keyboards, of which a headless session has none,
|
||||
and reading it would mean a `hyprctl` reload could silently change
|
||||
what every agent types. One group only: see the type.
|
||||
'';
|
||||
};
|
||||
|
||||
model = lib.mkOption {
|
||||
type = lib.types.strMatching "[A-Za-z0-9_-]*";
|
||||
default = "pc105";
|
||||
description = ''
|
||||
XKB model for the same keymap. `pc105` unless an operator knows
|
||||
otherwise; it decides little beyond which keys exist at all.
|
||||
'';
|
||||
};
|
||||
|
||||
variant = lib.mkOption {
|
||||
type = lib.types.str;
|
||||
default = "";
|
||||
example = "intl";
|
||||
description = ''
|
||||
XKB variant, empty by default.
|
||||
|
||||
Worth knowing before setting one: a variant whose characters are
|
||||
**dead keys** -- `us(intl)`'s accents, for instance -- cannot be
|
||||
typed by this version. A dead key is half of a compose sequence and
|
||||
v1 emits one event per character, so the driver refuses the name
|
||||
rather than arming the next keystroke in the focused application.
|
||||
'';
|
||||
};
|
||||
|
||||
options = lib.mkOption {
|
||||
type = lib.types.str;
|
||||
default = "";
|
||||
example = "ctrl:nocaps";
|
||||
description = ''
|
||||
XKB options, empty by default. Passed through to
|
||||
`xkb_keymap_new_from_names`; a value it rejects stops the driver
|
||||
with exit 2 before it connects to the compositor, so a typo here is
|
||||
a failed unit rather than a session that types the wrong thing.
|
||||
'';
|
||||
};
|
||||
};
|
||||
|
||||
stateDir = lib.mkOption {
|
||||
type = lib.types.str;
|
||||
default = "/var/lib/hhstream";
|
||||
@@ -978,17 +1052,32 @@ in {
|
||||
# plainly that stopping the driver stops the driver and nothing else.
|
||||
KillMode = "process";
|
||||
|
||||
# Frozen in docs/CONTRACT-sessions.md §3.4, word for word. The driver
|
||||
# defaults to both of these paths anyway; they are passed explicitly
|
||||
# because the contract specifies the command line, and a unit that
|
||||
# relied on the defaults would stop matching it the moment either
|
||||
# default moved.
|
||||
# The first two flags are frozen in docs/CONTRACT-sessions.md §3.4,
|
||||
# word for word. The driver defaults to both of those paths anyway;
|
||||
# they are passed explicitly because the contract specifies the command
|
||||
# line, and a unit that relied on the defaults would stop matching it
|
||||
# the moment either default moved.
|
||||
#
|
||||
# The four XKB flags are the **only** path a layout has to the uploaded
|
||||
# keymap, and that is worth being blunt about: the broker's TOML has a
|
||||
# `[pointer]` table that `hhstreamd` reads for its lease numbers, and
|
||||
# this is a different unit that never opens that file. A `[keyboard]`
|
||||
# table there would be a setting an operator could change while every
|
||||
# injected key stayed on `us`.
|
||||
ExecStart = lib.escapeShellArgs [
|
||||
(lib.getExe' cfg.package "hhstream-pointer")
|
||||
"--socket"
|
||||
pointerSocket
|
||||
"--compositor-runtime-dir"
|
||||
runtimeDir
|
||||
"--xkb-layout"
|
||||
cfg.sessions.keyboard.layout
|
||||
"--xkb-model"
|
||||
cfg.sessions.keyboard.model
|
||||
"--xkb-variant"
|
||||
cfg.sessions.keyboard.variant
|
||||
"--xkb-options"
|
||||
cfg.sessions.keyboard.options
|
||||
];
|
||||
};
|
||||
};
|
||||
|
||||
Reference in new issue
Block a user