Files
hyprland-headless-stream-pl…/nix/package.nix
T
HermenixandClaude Opus 5 ca5dbfb2ea feat(nix): the hhstream-live unit, and the two things it has to be handed
`services.hyprland-headless-stream.sessions.stream.enable` (default **false**)
runs `hhstream-live` and hands the broker `/run/hhstream/live.sock`. Running it
still turns nothing on: a stream exists only for the sessions
`hhstream session stream enable` was run on, which is the plan's rule that a
stream is never on for all sessions at all times.

A fourth unit rather than a flag on an existing one, for the pointer driver's
reason: `grim` blocks tens to hundreds of milliseconds, so the capture must not
run where `touch` and `kill` are answered, and a LAN-facing HTTP parser must not
run in the frame server whose one-socket contract cannot grow one.

Two things the unit must be handed, both of them MEASURED failures rather than
precautions:

1. **The capture command, spelled out, with grim's store path.** A unit's
   `PATH` has no `grim`
   (`docs/TODO/capture-binary-and-the-unit-path.md`), and the symptom is a
   stream that answers with an empty frame area and says why only in the
   daemon's journal. Every word is passed as `--capture-command=<word>` and not
   `--capture-command <word>`, because grim's last word is a bare `-` and
   argparse reads a lone dash as an option prefix rather than a value -- a unit
   crash-looping with "expected one argument", which is how that form was
   chosen.
2. **The compositor's session.** `XDG_RUNTIME_DIR` on the unit plus `execLive`,
   which discovers whichever `wayland-N` the compositor actually bound and
   exports it -- `execServer`'s trick, for `execServer`'s reason: the name is
   only known once the compositor is up, so it cannot be an `Environment=`
   line. Without it the unit was `active (running)`, the broker attached,
   `stream status` said `attached: true`, and every capture exited 1 with
   "XDG_RUNTIME_DIR is invalid or not set in the environment" until the
   publisher gave up after ten in a row. checks/vm-stream.nix found that on its
   first real run, which is the whole reason that check reads bytes instead of
   asserting a 200.

`SupplementaryGroups` gets the compositor's group for the pointer driver's
reason one step further -- this one has to *capture*, not merely find the
socket -- and there is deliberately no `RuntimeDirectory=`: a second one on
/run/hhstream would delete the broker's control socket when this unit stopped,
which the plan names as the Stage 3 risk.

`sessions.stream.fps` is the daemon's own default and nothing else sends one, so
the option changes what actually happens; the port and bind address are the
daemon's too, and the broker learns the URL from it.

`nix/package.nix` names `hhstream_live.control` and `hhstreamd.live` in
`pythonImportsCheck`: they are the one pair in this package that has to agree
with each other across two processes, so an import error in either is worth
finding at build time rather than the first time an operator enables a stream.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:48:22 +00:00

73 lines
2.9 KiB
Nix

{
lib,
python3,
...
}:
python3.pkgs.buildPythonApplication {
pname = "hhstream";
version = "0.1.0";
pyproject = true;
src = ../.;
build-system = [ python3.pkgs.setuptools ];
# `hhstream-pointer` is a Wayland client, so it needs libwayland's
# marshalling; and it resolves keysym names against the XKB layout it
# uploads, so it needs xkbcommon.
#
# Neither protocol XML is a build input: both generated modules are vendored
# under src/hhstream_pointer/_protocol, so a checkout builds without a code
# generator. See that package's docstring for why, and
# hhstream_pointer._protocol.regenerate for how to refresh them -- including
# the note that virtual-keyboard-unstable-v1.xml is not in wayland-protocols
# or wlr-protocols in this nixpkgs and comes from pkgs.hyprland.src.
dependencies = [ python3.pkgs.pywayland python3.pkgs.xkbcommon ];
# Unit tests are wired up in the flake's `checks` so they can run without
# installing the package; see docs/CONTRACT.md.
doCheck = false;
# Cheap proof that the vendored protocols still bind against this pywayland:
# importing each runs the scanner-generated `_gen_c()` for its interfaces.
pythonImportsCheck = [
"hhstream_pointer.ops"
"hhstream_pointer.keymap"
"hhstream_pointer._protocol.wlr_virtual_pointer_unstable_v1"
"hhstream_pointer._protocol.virtual_keyboard_unstable_v1"
# The web app: importing the server pulls in the router, the publisher and
# the pages.
"hhstream_live.server"
# The two halves of `live.sock` (CONTRACT-sessions.md §3.5). Both are
# stdlib-only, and they are named here because they are the one pair in
# this package that has to agree with each other across two processes --
# so an import error in either is worth finding at build time rather than
# the first time an operator enables a stream.
"hhstream_live.control"
"hhstreamd.live"
];
# `pythonImportsCheck` only *imports*, and `hhstream_live.phrase` reads its
# wordlist lazily -- so a wheel that dropped `wordlist.txt` would sail past it
# and fail at the first `enable` instead. Read the list for real, against the
# installed tree, and mint a phrase so the generator and its validator are
# proven on the same words. `doCheck = false` (the suite runs in the flake's
# `checks`), so this is the only place the packaged data is exercised.
postFixup = ''
echo "checking the installed wordlist..."
PYTHONPATH="$out/${python3.sitePackages}:$PYTHONPATH" ${python3.interpreter} -c '
import hhstream_live.phrase as phrase
count = len(phrase.words())
assert count > 7000, f"wordlist has only {count} words; is wordlist.txt installed?"
assert phrase.validate(phrase.generate())
print(f"wordlist ok: {count} words, ~{phrase.entropy_bits():.1f} bits a phrase")
'
'';
meta = {
description = "Publish a headless Hyprland session's frames on a Unix socket";
license = lib.licenses.mit;
mainProgram = "hhstream-server";
};
}