Files
hyprland-headless-stream-pl…/checks/vm-stream-firewall.nix
T
Hermenix 7141900070 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.
2026-10-11 02:22:00 +00:00

244 lines
9.7 KiB
Nix

# 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"
)
'';
}