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;