Compare commits

..
Author SHA1 Message Date
HermenixandClaude Opus 5 443efd8da8 docs(dev): register vm-keyboard and vm-keyboard-de where a reader looks
The keyboard checks were in `README.dev.md`'s `checks/` layout listing and
nowhere else: not in the table of what each check proves, and not in the
one-at-a-time `nix build -L` list that the same section tells you to use
instead of `nix flake check`. So the two checks this branch adds were
invisible exactly where someone goes to find out what is gated and how to
run it, while `vm-stream-firewall` (from main) was in all three places.

Four lines, no behaviour. The table rows state what each run actually
asserts, taken from `checks/vm-keyboard.nix`'s header and its
`expectations` attrset rather than paraphrased:

  * `vm-keyboard` -- the uploaded keymap reaching a real compositor,
    `pointer acquire` leaving the aimed window holding the keyboard and
    not merely the cursor, and `hhs-keyboard-target` decoding `hello`
    from the keymap it was forwarded. The mutation is named, because it
    is the point of the victim decoding rather than counting keycodes: a
    driver that stopped uploading a keymap leaves every key arriving as
    `sym=?`.

  * `vm-keyboard-de` -- why one file is exposed twice, which is that
    `sessions.keyboard.layout` reaches the keymap only through
    `--xkb-layout` on the driver unit and a single-layout run cannot
    tell that path from a hardcoded `us`. The three differences it
    pins: keysym `y`'s evdev code (21 against 44), the forwarded
    `symbols=` name, and `ü` going from exit 2 to `udiaeresis`.

Both rows say `yes` under "Needs a VM", and the build lines sit between
`vm-pointer` and `vm-stream-firewall` so the list keeps the order the
layout listing and `checks/default.nix` already use.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PjpHyir6hxyjdw2o1RwQmn
2026-10-11 03:06:08 +00:00
HermenixandClaude Opus 5 5f94833a76 Merge origin/main into feat/keyboard-input: keep both the stream and the
keyboard sides

origin/main brought the session live-stream feature (stage 1): the
`hhstream_live` router, its phrase generator and wordlist, the
`sessions.stream.*` module options with their loopback-vs-openFirewall
assertion and the one firewall port, the `vm-stream-firewall` check, and
`tests/live/`. This branch adds keyboard input: the `key`/`type` ops, the
uploaded XKB keymap, `sessions.keyboard.{layout,model,variant,options}`
and the four `--xkb-*` flags on the driver unit, `vm-keyboard` and
`vm-keyboard-de`, and their docs.

The two features are independent, so every conflict wanted both sides.
Four files, resolved as follows.

checks/default.nix -- both the header list and the attribute set take all
three new checks: `vm-keyboard`, `vm-keyboard-de` (the same file with
`keyboardLayout = "de"`, because the layout reaches the keymap only
through the driver unit's argv) and `vm-stream-firewall`, which stays a
non-`sessionArgs` consumer with main's comment saying why. Neither side's
check list is reduced; the flake now exposes ten.

nix/package.nix -- one `pythonImportsCheck` list with both sides' entries:
`hhstream_pointer.keymap` and the vendored
`virtual_keyboard_unstable_v1` from here, `hhstream_live.server` from
main. The surrounding hunks were not in conflict, so the branch's
xkbcommon dependency and main's wordlist `postFixup` both survive, and
both ran in this merge's `checks.unit` build (`wordlist ok: 7772 words`).

nix/module.nix -- the sole conflict was textual: both sides open a new
sub-option block immediately after `sessions.pointer`. Both blocks are
kept, `keyboard` then `stream`, each with its own closing. Everything
else in the file merged cleanly, so `loopbackBinds`, the
openFirewall-on-loopback assertion and
`networking.firewall.allowedTCPPorts` are present alongside the driver
unit's `--xkb-layout`/`--xkb-model`/`--xkb-variant`/`--xkb-options`.

README.dev.md -- the `checks/` layout listing keeps both entries in the
file's existing order, `vm-keyboard.nix` then `vm-stream-firewall.nix`.

Verified: `nix flake check --no-build` evaluates every output green, and
`nix build .#checks.x86_64-linux.unit` passes -- 977 passed, 2 skipped,
0 failed, over both sides' suites. The VM checks were not run (they boot
a software-rendered compositor and must run one at a time).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PjpHyir6hxyjdw2o1RwQmn
2026-10-11 02:57:55 +00:00
ari c6cfd02bf3 Merge pull request 'Session live stream: one port, a router, and a phrase per session (stage 1)' (#2) from feat/session-live-stream-webapp into main
Reviewed-on: http://gitea.app.internal:3000/Hermenix/hyprland-headless-stream-plugin/pulls/2
2026-10-11 02:42:39 +00:00
ari 4461660c6d Merge branch 'main' into feat/session-live-stream-webapp 2026-10-11 02:42:25 +00:00
ari 934774f15e fixing a test 2026-10-09 11:32:42 -04:00
6 changed files with 109 additions and 78 deletions

No files matched your search

+1
View File
@@ -0,0 +1 @@
use flake
+5 -1
View File
@@ -48,6 +48,8 @@ and the pointer driver.
| `vm-ipc` | the **compositor's IPC**: both sockets exist at the names `docs/CONTRACT-sessions.md` §5 freezes and fit inside `sun_path`, `hyprctl` answers, the broker's own `HyprlandIPC` reaches it, and a subscriber on the **event** socket receives an `openwindow` for a window the test creates | yes |
| `vm-containers` | one `hh-*` output per session at the container mode, the application's window on it, a second window of the same application beside it, an unmatched window **quarantined**, `grim -o` capturing that container alone, and teardown removing the output and freeing its workspace slot | yes |
| `vm-pointer` | the **lease and the driver**: a version-2 virtual pointer, a warp that lands where it was aimed *as the application reports it*, a click delivered as one press and one release, a contended acquire refused with BUSY, an expired lease swept with its held button lifted, and a broker restart that leaves the lock free, the bookmark intact and the driver reachable | yes |
| `vm-keyboard` | the **keymap, the focus and a decoded symbol**: the keymap the driver uploads reaching a real compositor, `pointer acquire` leaving the aimed window holding the *keyboard* and not merely the cursor, and `hhs-keyboard-target` decoding `hello` from the keymap it was **forwarded** — so a driver that stopped uploading one arrives as `sym=?` and goes red | yes |
| `vm-keyboard-de` | the same file with `sessions.keyboard.layout = "de"`, because that option reaches the uploaded keymap through exactly one path — `--xkb-layout` on the driver unit — and a single-layout check cannot tell that path from a hardcoded `us`: keysym `y`'s evdev code swaps (21 against 44), the forwarded `symbols=` name with it, and `ü` goes from exit 2 to `udiaeresis` | yes |
| `vm-stream-firewall` | the stream's **port**: the guest's own running firewall accepts the configured port and not the module's default, a peer outside the guest reaches it, and is refused on a port beside it that was never opened | yes |
All of them at once:
@@ -70,6 +72,8 @@ nix build -L .#checks.x86_64-linux.vm-sessions
nix build -L .#checks.x86_64-linux.vm-ipc
nix build -L .#checks.x86_64-linux.vm-containers
nix build -L .#checks.x86_64-linux.vm-pointer
nix build -L .#checks.x86_64-linux.vm-keyboard
nix build -L .#checks.x86_64-linux.vm-keyboard-de
nix build -L .#checks.x86_64-linux.vm-stream-firewall
```
@@ -221,11 +225,11 @@ 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-stream-firewall.nix nixosTest, the stream's port in the guest's firewall
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
vm-stream-firewall.nix nixosTest, the stream's port in the guest's firewall
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
+7 -6
View File
@@ -7,9 +7,9 @@
# 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-stream-firewall -- the stream's port in the guest's own running firewall
# vm-keyboard -- the uploaded keymap, keyboard focus, and a decoded symbol
# vm-keyboard-de -- the same check with sessions.keyboard.layout = "de"
# vm-stream-firewall -- the stream's port in the guest's own running firewall
#
# 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
@@ -62,14 +62,15 @@ in
vm-pointer = pkgs.callPackage ./vm-pointer.nix sessionArgs;
# Not a `sessionArgs` consumer: this one is about the module's own options,
# not about the broker or the compositor (see the file's header).
vm-stream-firewall = pkgs.callPackage ./vm-stream-firewall.nix {
inherit hhstream hhsModule testTools;
};
vm-keyboard = pkgs.callPackage ./vm-keyboard.nix sessionArgs;
vm-keyboard-de = pkgs.callPackage ./vm-keyboard.nix (
sessionArgs // { keyboardLayout = "de"; }
);
# Not a `sessionArgs` consumer: this one is about the module's own options,
# not about the broker or the compositor (see the file's header).
vm-stream-firewall = pkgs.callPackage ./vm-stream-firewall.nix {
inherit hhstream hhsModule testTools;
};
}
+57 -57
View File
@@ -625,63 +625,6 @@ in {
};
};
# The session-stream web app — `hhstream-live`, the router that serves a
# live view of one session per phrase, over one port
# (`docs/plans/2026-10-04-session-stream-webapp.md`).
#
# Only the *reach* of it is declared here so far: the port every stream
# shares, the address it will bind, and whether that port is opened in
# the firewall. The unit that runs the app, the phrases the broker keeps
# in its records and the `session stream enable` verbs are later stages
# of that plan — and deliberately so: a stream is switched on per
# session, never for all of them, so nothing here turns one on.
stream = {
port = lib.mkOption {
type = lib.types.port;
default = 9988;
description = ''
The single TCP port every stream shares.
One listener rather than one per session is what makes the phrase
speakable: there is one address to give a person, one thing to
firewall and one thing to stop. It is also why this is a fixed
number with no range to fall back on — a stream at a port nobody
was told about is worse than a stream that is down, so a taken port
fails loudly instead of moving.
'';
};
bind = lib.mkOption {
type = lib.types.str;
default = "127.0.0.1";
description = ''
The address the web app will bind.
Loopback by default, where the reachable path is an ssh tunnel
(`ssh -L 9988:127.0.0.1:9988`) and nothing else. Set it to an
address a peer can reach (`"0.0.0.0"`) when
{option}`sessions.stream.openFirewall` is set: opening the port for
a listener that is not on it is a hole with no service behind it,
which is why that pairing is refused rather than allowed.
'';
};
openFirewall = lib.mkOption {
type = lib.types.bool;
default = false;
description = ''
Open {option}`sessions.stream.port` in the firewall.
Off by default, and deliberately not implied by
{option}`sessions.enable`: a live view of this desktop is readable
by anyone who can reach the port, and the phrase in the URL is its
only credential — no TLS, no second factor
(`docs/plans/2026-10-04-…` §4). Opening it is an explicit act, and
it opens exactly one port.
'';
};
};
# 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
@@ -756,6 +699,63 @@ in {
};
};
# The session-stream web app — `hhstream-live`, the router that serves a
# live view of one session per phrase, over one port
# (`docs/plans/2026-10-04-session-stream-webapp.md`).
#
# Only the *reach* of it is declared here so far: the port every stream
# shares, the address it will bind, and whether that port is opened in
# the firewall. The unit that runs the app, the phrases the broker keeps
# in its records and the `session stream enable` verbs are later stages
# of that plan — and deliberately so: a stream is switched on per
# session, never for all of them, so nothing here turns one on.
stream = {
port = lib.mkOption {
type = lib.types.port;
default = 9988;
description = ''
The single TCP port every stream shares.
One listener rather than one per session is what makes the phrase
speakable: there is one address to give a person, one thing to
firewall and one thing to stop. It is also why this is a fixed
number with no range to fall back on — a stream at a port nobody
was told about is worse than a stream that is down, so a taken port
fails loudly instead of moving.
'';
};
bind = lib.mkOption {
type = lib.types.str;
default = "127.0.0.1";
description = ''
The address the web app will bind.
Loopback by default, where the reachable path is an ssh tunnel
(`ssh -L 9988:127.0.0.1:9988`) and nothing else. Set it to an
address a peer can reach (`"0.0.0.0"`) when
{option}`sessions.stream.openFirewall` is set: opening the port for
a listener that is not on it is a hole with no service behind it,
which is why that pairing is refused rather than allowed.
'';
};
openFirewall = lib.mkOption {
type = lib.types.bool;
default = false;
description = ''
Open {option}`sessions.stream.port` in the firewall.
Off by default, and deliberately not implied by
{option}`sessions.enable`: a live view of this desktop is readable
by anyone who can reach the port, and the phrase in the URL is its
only credential — no TLS, no second factor
(`docs/plans/2026-10-04-…` §4). Opening it is an explicit act, and
it opens exactly one port.
'';
};
};
stateDir = lib.mkOption {
type = lib.types.str;
default = "/var/lib/hhstream";
+1 -1
View File
@@ -34,10 +34,10 @@ python3.pkgs.buildPythonApplication {
"hhstream_pointer.ops"
"hhstream_pointer.keymap"
"hhstream_pointer._protocol.wlr_virtual_pointer_unstable_v1"
"hhstream_pointer._protocol.virtual_keyboard_unstable_v1"
# The web app: importing the server pulls in the router, the publisher and
# the pages.
"hhstream_live.server"
"hhstream_pointer._protocol.virtual_keyboard_unstable_v1"
];
# `pythonImportsCheck` only *imports*, and `hhstream_live.phrase` reads its
+38 -13
View File
@@ -75,12 +75,18 @@ def test_a_failure_after_a_good_frame_keeps_the_known_size():
def test_env_is_overlaid_on_our_own_environment():
argv = [sys.executable, "-c",
"import os,sys;sys.stdout.write(os.environ['WAYLAND_DISPLAY']+':'+"
"('PATH' in os.environ and 'haspath' or 'nopath'))"]
argv = [
sys.executable,
"-c",
"import os,sys;sys.stdout.write(os.environ['WAYLAND_DISPLAY']+':'+"
+ "('PATH' in os.environ and 'haspath' or 'nopath'))",
]
before = os.environ.get("WAYLAND_DISPLAY")
capture = CommandCapture(argv, env={"WAYLAND_DISPLAY": "wayland-9"})
assert capture.grab() == b"wayland-9:haspath"
assert "WAYLAND_DISPLAY" not in os.environ, "our own environment was mutated"
assert os.environ.get("WAYLAND_DISPLAY") == before, (
"our own environment was mutated"
)
def test_empty_argv_and_bad_timeout_are_rejected_up_front():
@@ -91,8 +97,10 @@ def test_empty_argv_and_bad_timeout_are_rejected_up_front():
def test_the_helpers_stdin_is_closed_so_it_cannot_steal_ours():
code = ("import sys;"
"sys.stdout.buffer.write(b'EMPTY' if not sys.stdin.read() else b'DATA')")
code = (
"import sys;"
"sys.stdout.buffer.write(b'EMPTY' if not sys.stdin.read() else b'DATA')"
)
assert CommandCapture([sys.executable, "-c", code]).grab() == b"EMPTY"
@@ -102,15 +110,32 @@ def test_image_size_reads_png_headers(width, height):
def test_image_size_reads_a_jpeg_sof_header():
jpeg = (b"\xff\xd8"
+ b"\xff\xe0" + (16).to_bytes(2, "big") + b"JFIF\x00" + b"\x00" * 9
+ b"\xff\xc0" + (17).to_bytes(2, "big") + b"\x08"
+ (720).to_bytes(2, "big") + (1280).to_bytes(2, "big")
+ b"\x03" + b"\x00" * 9)
jpeg = (
b"\xff\xd8"
+ b"\xff\xe0"
+ (16).to_bytes(2, "big")
+ b"JFIF\x00"
+ b"\x00" * 9
+ b"\xff\xc0"
+ (17).to_bytes(2, "big")
+ b"\x08"
+ (720).to_bytes(2, "big")
+ (1280).to_bytes(2, "big")
+ b"\x03"
+ b"\x00" * 9
)
assert image_size(jpeg) == (1280, 720)
@pytest.mark.parametrize("data", [b"", b"not an image", b"\x89PNG\r\n\x1a\n",
b"\xff\xd8", b"\xff\xd8\xff\xc0\x00\x11"])
@pytest.mark.parametrize(
"data",
[
b"",
b"not an image",
b"\x89PNG\r\n\x1a\n",
b"\xff\xd8",
b"\xff\xd8\xff\xc0\x00\x11",
],
)
def test_image_size_returns_none_when_it_cannot_tell(data):
assert image_size(data) is None