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
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-11 02:57:55 +00:00
commit 5f94833a76
26 files changed
+10544 -13

No files matched your search

+7
View File
@@ -9,6 +9,7 @@
# 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"
# 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
@@ -66,4 +67,10 @@ in
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;
};
}
+243
View File
@@ -0,0 +1,243 @@
# checks.<system>.vm-stream-firewall -- the stream's port, and only that port.
#
# `sessions.stream.openFirewall` is the one part of the session-stream web app
# that a machine declares before the app has a unit (it is the piece of
# docs/plans/2026-10-04-session-stream-webapp.md §3 that does not need the
# broker), so it is the one part worth gating on its own.
#
# The option's effect is a firewall rule, and a rule is only a rule once the
# firewall has loaded it -- so this boots the module rather than evaluating it
# and reading `config.networking.firewall.allowedTCPPorts` back. A test that
# reads the option out of the evaluation proves the option is plumbed; this one
# asks the running firewall, and then asks it from *outside* the guest, which
# is the only place a firewall exists for.
#
# Four things about the shape are deliberate:
#
# * **A second machine is the peer.** Nothing outside a guest can reach it
# except another guest: the test driver runs on the host and is not on the
# test VLAN, so a probe from the driver fails whether the port is open or
# not. The peer is a bare machine on the same VLAN with no module on it --
# a peer running the module would be testing the machine against itself.
# * The configured port is **not** the module's default (9123, with 9988 as
# the default it must ignore). The interesting failure is an option that
# opens its own default whatever it is set to, and a check that configures
# 9988 cannot see it.
# * A listener is put on the unopened neighbour too, so "refused" means the
# firewall refused rather than nothing being there to connect to. Both
# listeners answer on loopback inside the guest first.
# * The address the peer probes is read out of the guest instead of assumed,
# because a check that guesses an interface name is testing the guess -- and
# the guest carries two addresses (the qemu NAT one and the test VLAN's),
# only one of which the peer can reach.
{
testers,
hhstream,
testTools,
hhsModule,
python3,
curl,
# The port the module is told to open; one beside it that it is not; and the
# module's own default, which must not appear at all.
configuredPort ? 9123,
unopenedPort ? 9124,
defaultPort ? 9988,
}:
testers.runNixOSTest {
name = "hhstream-vm-stream-firewall";
# Two guests on a two-core machine is slower than one; cap it so a hang is a
# failure rather than a wedged builder.
globalTimeout = 1800;
nodes.machine = {
# gpu-session.nix is what makes the compositor able to start at all; this
# check is not about the compositor, but `sessions.stream` lives under a
# module that boots one, and a machine kept from starting its own units is
# not the machine anyone runs.
imports = [ hhsModule ./lib/gpu-session.nix ];
services.hyprland-headless-stream = {
enable = true;
# The module declares `package` with no default (see README.dev.md), so
# the test has to supply the flake's build.
package = hhstream;
frameRate = 30;
outputs = [
{
width = 1280;
height = 720;
refresh = 30;
}
];
# The fake capture, as in vm-basic: the compositor's own frames are not
# this check's subject, and a real `grim` here would only add minutes of
# software rendering to it.
captureCommand = [
"${testTools}/bin/hhs-fake-capture"
"--width"
"1280"
"--height"
"720"
];
sessions.stream = {
port = configuredPort;
# Not a loopback address, because the module refuses that pairing with
# `openFirewall` on: opening a port nothing can reach is a hole with no
# service behind it (see the assertion in nix/module.nix).
bind = "0.0.0.0";
openFirewall = true;
};
};
# Two listeners, each bound on every interface: the configured port and a
# neighbour the module was never told about. They exist so that a refusal
# out here is the firewall's doing rather than an empty port.
systemd.services.probe-configured = {
wantedBy = [ "multi-user.target" ];
serviceConfig.ExecStart = "${python3}/bin/python3 -m http.server ${toString configuredPort}";
};
systemd.services.probe-unopened = {
wantedBy = [ "multi-user.target" ];
serviceConfig.ExecStart = "${python3}/bin/python3 -m http.server ${toString unopenedPort}";
};
environment.systemPackages = [
# `curl` is the loopback probe; python3 is the listeners themselves.
python3
curl
];
virtualisation = {
memorySize = 2048;
cores = 2;
diskSize = 4096;
graphics = false;
# The VLAN the peer is on. Without it the two machines share nothing but
# the driver's console, and "outside" stops existing.
vlans = [ 1 ];
};
};
# The peer: a bare machine on the same VLAN, no module, no compositor. Its
# whole job is to fail to reach one port and succeed on another.
nodes.peer = {
environment.systemPackages = [ curl ];
virtualisation = {
memorySize = 1024;
cores = 1;
vlans = [ 1 ];
};
};
testScript = ''
CONFIGURED = ${toString configuredPort}
UNOPENED = ${toString unopenedPort}
DEFAULT = ${toString defaultPort}
def dump(label):
print(f"########## diagnostics: {label} ##########")
for cmd in (
"systemctl --no-pager -l status firewall.service",
"systemctl --no-pager -l status probe-configured.service probe-unopened.service",
"nixos-firewall-tool show",
"ip -4 -o addr show",
):
status, out = machine.execute(cmd, timeout=60)
print(out)
print("########## end diagnostics ##########")
def peer_reaches(address, port, timeout=8):
"""Ask the peer to open the port: out there, a firewall is a firewall."""
status, out = peer.execute(
f"curl -sS -f -o /dev/null --max-time {timeout} http://{address}:{port}/",
timeout=timeout + 10,
)
return status == 0
start_all()
# Every global address the machine has, waited for and then read off the
# machine rather than assumed: a bare test machine carries two (the qemu NAT
# one and the test VLAN's), and only one of them is a path the peer can
# take.
#
# The wait is not decoration. Addresses appear a moment after `start_all()`
# returns, and reading too early yields an empty list -- which reads as "the
# peer can reach nothing" rather than as "asked a second too soon".
machine.wait_until_succeeds(
"ip -4 -o addr show scope global | grep -q ' inet '", timeout=90
)
addresses = []
for line in machine.succeed("ip -4 -o addr show scope global").splitlines():
# "2: eth0 inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic ..."
fields = line.split()
if len(fields) >= 4 and fields[2] == "inet":
addresses.append(fields[3].split("/")[0])
print(f"the machine's addresses: {addresses}")
assert addresses, "the machine reported no global address to probe"
with subtest("a machine with a stream declared is still a machine that boots"):
try:
machine.wait_for_unit("hyprland-headless.service", timeout=120)
machine.wait_for_unit("hyprland-headless-stream.service", timeout=120)
except Exception:
dump("the module's own units did not come up")
raise
with subtest("the running firewall accepts the configured port, and not the default"):
try:
machine.wait_for_unit("firewall.service")
rules = machine.succeed("nixos-firewall-tool show")
print(rules)
except Exception:
dump("the firewall did not come up")
raise
assert f"dpt:{CONFIGURED}" in rules, (
f"the firewall does not accept {CONFIGURED}: the option did not reach "
f"the rule set"
)
assert f"dpt:{DEFAULT}" not in rules, (
f"the firewall accepts {DEFAULT}: the module opened its own default "
f"port instead of the configured one"
)
with subtest("both probe listeners are up and answer inside the guest"):
try:
machine.wait_for_unit("probe-configured.service", timeout=60)
machine.wait_for_unit("probe-unopened.service", timeout=60)
for port in (CONFIGURED, UNOPENED):
machine.succeed(f"curl -sS -f -o /dev/null http://127.0.0.1:{port}/")
except Exception:
dump("a probe listener did not come up")
raise
with subtest("the peer reaches the configured port"):
reached = [a for a in addresses if peer_reaches(a, CONFIGURED)]
print(f"the peer reached {CONFIGURED} on: {reached}")
if not reached:
dump(f"the peer could not reach {CONFIGURED} on any of {addresses}")
raise AssertionError(
f"{CONFIGURED} is accepted in the rule set but the peer cannot reach "
f"it on any address the machine has ({addresses})"
)
with subtest("and is refused on the port the module never opened"):
# On the same addresses that just answered for the configured port, so
# the refusal is the firewall's doing and not a missing route.
for address in reached:
if peer_reaches(address, UNOPENED):
dump(f"the peer reached {UNOPENED} on {address}")
raise AssertionError(
f"the peer reached {UNOPENED} on {address}, a port the module was "
f"never told to open: the firewall is letting through more than "
f"the option names"
)
'';
}