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.
This commit is contained in:
Hermenix committed 2026-10-11 02:22:00 +00:00
1 parent db7aaf8276
commit 7141900070
5 files changed
+356 -1

No files matched your search

+3
View File
@@ -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
+7
View File
@@ -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;
};
}
+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"
)
'';
}
+15 -1
View File
@@ -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.
`/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.
+88
View File
@@ -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;