From 714190007036565e47b2885f4a2ce8846810b28e Mon Sep 17 00:00:00 2001 From: Hermenix Date: Sun, 11 Oct 2026 02:22:00 +0000 Subject: [PATCH] module: declare the stream's port, and the one hole it needs `sessions.stream { port, bind, openFirewall }` -- the piece of stage 3 that does not need the broker. It exists because a machine had to be able to *reach* a stream before the rest of the app is settled: the operator asked for the port to be open on the deployment machine, where the app still runs by hand, and a bare `networking.firewall.allowedTCPPorts` line in one machine's config is the wrong place for a fact about this flake. - `openFirewall` defaults false and is deliberately not implied by `sessions.enable`: a live view of the desktop is readable by anyone who can reach the port, the phrase in the URL is its only credential, and there is no TLS. It opens exactly one port -- the one the option names. - `bind` defaults to loopback and is *checked*: `openFirewall = true` beside a loopback bind is refused, because that is a hole with no service behind it. - `checks/vm-stream-firewall.nix` boots the module with a configured port that is not the module's default, puts listeners on that port and on a neighbour, and asserts from a second machine on the same VLAN that the peer reaches the configured port and is refused on the other -- while both answer on loopback inside the guest, so the refusal is the firewall's doing and not an empty socket. The peer is a second machine because a probe from the test driver proves nothing: the driver is not on the test VLAN. Nothing here turns a stream on -- no unit, no phrases, no `session stream` verbs, which stay stage 2+3 -- and docs/plans/2026-10-04-session-stream-webapp.md now records which part of its stage 3 landed and why out of order. --- README.dev.md | 3 + checks/default.nix | 7 + checks/vm-stream-firewall.nix | 243 ++++++++++++++++++ .../plans/2026-10-04-session-stream-webapp.md | 16 +- nix/module.nix | 88 +++++++ 5 files changed, 356 insertions(+), 1 deletion(-) create mode 100644 checks/vm-stream-firewall.nix diff --git a/README.dev.md b/README.dev.md index 38a4091..f345d03 100644 --- a/README.dev.md +++ b/README.dev.md @@ -48,6 +48,7 @@ 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-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: @@ -69,6 +70,7 @@ 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-stream-firewall ``` `-L` is not optional in practice: without it, Nix hides the build log, and the @@ -219,6 +221,7 @@ 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 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 diff --git a/checks/default.nix b/checks/default.nix index 8f01f56..703b5f1 100644 --- a/checks/default.nix +++ b/checks/default.nix @@ -7,6 +7,7 @@ # 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 # # 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 @@ -53,4 +54,10 @@ in vm-containers = pkgs.callPackage ./vm-containers.nix sessionArgs; 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; + }; } diff --git a/checks/vm-stream-firewall.nix b/checks/vm-stream-firewall.nix new file mode 100644 index 0000000..8acc6d2 --- /dev/null +++ b/checks/vm-stream-firewall.nix @@ -0,0 +1,243 @@ +# checks..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" + ) + ''; +} diff --git a/docs/plans/2026-10-04-session-stream-webapp.md b/docs/plans/2026-10-04-session-stream-webapp.md index 2796523..7be79cc 100644 --- a/docs/plans/2026-10-04-session-stream-webapp.md +++ b/docs/plans/2026-10-04-session-stream-webapp.md @@ -178,4 +178,18 @@ one at a time; no browser in a VM check. **Stage 1 is built** (`src/hhstream_live/`, `tests/live/`, 51 unit tests): the router, the pages, the phrase and the publisher, runnable standalone via `hhstream-live serve --stream PHRASE=OUTPUT`. The broker verbs and -`/run/hhstream/live.sock` are Stage 2. \ No newline at end of file +`/run/hhstream/live.sock` are Stage 2. + +**Stage 3 has started, out of order and on purpose** (2026-10-11). A machine +had to be able to *reach* a stream before the rest of the app is settled: the +operator asked for the port to be open on the deployment machine, where the app +runs by hand, and a hand-written firewall line in one machine's config is the +wrong place for a fact about this flake. So `sessions.stream { port, bind, +openFirewall }` and the single rule it stands for are in `nix/module.nix`, with +`checks/vm-stream-firewall.nix` asking the *running* firewall — and a peer +outside the guest — whether the configured port is the one that opened. + +What that does **not** do: no unit, no phrases, no `session stream +enable|disable|list|status`, and nothing in the module turns a stream on. The +app is still started by hand, and the option's whole job is to describe where a +stream will be reachable from. \ No newline at end of file diff --git a/nix/module.nix b/nix/module.nix index 2d7446b..80b31e9 100644 --- a/nix/module.nix +++ b/nix/module.nix @@ -47,6 +47,11 @@ let controlSocket = "${brokerRuntimeDir}/control.sock"; pointerSocket = "${brokerRuntimeDir}/pointer.sock"; + # Addresses that mean "this listener answers on loopback only". The spelling + # `localhost` is included because it is what a person writes; it is not a + # resolution the module performs. + loopbackBinds = [ "127.0.0.1" "::1" "localhost" ]; + socketDir = builtins.dirOf cfg.socketPath; # Hyprland refuses `--socket` unless it is paired with `--wayland-fd` (that @@ -620,6 +625,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"; @@ -695,6 +757,21 @@ in { so without the broker it would bind a socket nothing connects to. ''; } + { + assertion = + !cfg.sessions.stream.openFirewall + || !(lib.elem cfg.sessions.stream.bind loopbackBinds); + message = '' + services.hyprland-headless-stream.sessions.stream.openFirewall is true + while sessions.stream.bind is "${cfg.sessions.stream.bind}" — a loopback + address. The port would be open in the firewall with nothing answering on + it from anywhere but this machine, which is a hole rather than a feature. + + Set sessions.stream.bind to an address a peer can reach ("0.0.0.0"), or + leave the firewall closed and reach the stream through a tunnel + (`ssh -L 9988:127.0.0.1:9988`). + ''; + } { assertion = !cfg.sessions.enable || lib.hasAttr cfg.sessions.user config.users.users; message = '' @@ -757,6 +834,17 @@ in { }) ]; + # The stream's one port, in the firewall. + # + # `lib.optional`, not a conditional block: the option is one line and its + # effect is one port in the rule set, so there is nothing here that could + # open a second one. Everything else about the app — the phrase per + # session, the capture, the enable/disable verbs — is later stages of the + # plan; this is the only part of the stream that a machine declares before + # any of that exists. + networking.firewall.allowedTCPPorts = + lib.optional cfg.sessions.stream.openFirewall cfg.sessions.stream.port; + users.users.${cfg.user} = { isSystemUser = true; group = cfg.group;