Files
Hermenix 30f456c07e integrate the session broker: one CLI, a module unit, and a VM check
M0 of the sessions design, wired into the flake and gated by a real check.

What is here now:

- `src/hhstreamd/` — the broker: session registry, lifecycle verbs, process-group
  teardown, app allowlist, audit log, idle reaper on CLOCK_BOOTTIME.
- `src/hhstream_session/` — the CLI handlers, registered into the one front door.
- `src/hhstream/cli.py` — `hhstream status|shot|run|record|session …`, so the
  frame verbs and the session namespace are one binary.
- `nix/module.nix` — `sessions.*` options and the `hhstream-sessions.service`
  unit: the operator's own account (never a service account, because launched
  applications should see that account's home), the compositor's group as a
  supplementary group (without it a launched GUI client cannot open the Wayland
  socket), the generated app allowlist, and `--compositor-runtime-dir` so
  applications are handed the compositor's session rather than the broker's.
- `checks/vm-sessions.nix` — 18 subtests on a real compositor in a VM.

Two bugs found by driving it, both fixed:

- BUG-01: launched applications could not reach the compositor at all — the
  broker spawned them with its own inherited environment, which names the login
  session. `hhstreamd/compositor.py` discovers the socket and builds the child
  environment; a directory with no usable socket is a startup refusal, not a
  warning.
- BUG-02: `kill` refused to signal a live application and said nothing was
  wrong. The identity gate hashed `/proc/<pid>/cmdline`, which every `execve`
  replaces — and on NixOS applications are reached through wrapper scripts that
  do exactly that. The gate now rests on `starttime` (+ boot id, + session id
  where it is immutable) and records command-line drift as evidence of nothing.

KillMode=process is set on the unit on purpose: the default control-group kill
would take the applications down with the broker, which would make adoption and
a broker restart pointless.
2026-10-01 12:23:16 +00:00

105 lines
3.4 KiB
Python

"""The exit-code table of DESIGN.md §1.6.
These are frozen: agents branch on them. The test states the table in full so
a change to it is a change to this file.
"""
from __future__ import annotations
import pytest
from hhstream_session.client import ClientError, reply_exit_code
from hhstreamd.protocol import EXIT_CODE_FOR_ERROR, ExitCode, exit_code_for
def test_the_frozen_numbers():
assert ExitCode.OK == 0
assert ExitCode.USAGE == 2
assert ExitCode.NO_SUCH_SESSION == 3
assert ExitCode.BAD_STATE == 4
assert ExitCode.DAEMON_UNREACHABLE == 5
assert ExitCode.POLICY == 6
assert ExitCode.TIMEOUT == 7
assert ExitCode.BUSY == 8
# 1 is deliberately absent: it is the shell's "something went wrong", and
# reusing it would make an unhandled crash indistinguishable from a
# documented outcome.
assert 1 not in set(ExitCode)
@pytest.mark.parametrize(
"error,code",
[
# 2 — usage
("bad_request", 2),
("unknown_op", 2),
("unsupported_version", 2),
("message_too_large", 2),
("invalid_argument", 2),
# 3 — no such session
("no_such_session", 3),
("no_such_process", 3),
# 4 — not in a usable state
("session_exited", 4),
("session_killed", 4),
("session_reaped", 4),
("session_starting", 4),
("compositor_lost", 4),
("bad_state", 4),
("pid_reuse_detected", 4),
("identity_unknown", 4),
# 5 — daemon unreachable
("daemon_unreachable", 5),
# 6 — refused by policy
("not_allowlisted", 6),
("argument_refused", 6),
("session_cap_reached", 6),
("refused", 6),
# 7 — timed out
("timeout", 7),
("readiness_timeout", 7),
# 8 — busy
("busy", 8),
("already_managed", 8),
],
)
def test_every_error_name_maps_to_its_documented_code(error, code):
assert exit_code_for(error) == code
def test_the_table_has_no_entries_this_test_does_not_know_about():
"""Adding an error name must mean adding it to the test above."""
documented = {
"bad_request", "unknown_op", "unsupported_version", "message_too_large",
"invalid_argument", "no_such_session", "no_such_process", "session_exited",
"session_killed", "session_reaped", "session_starting", "compositor_lost",
"bad_state", "pid_reuse_detected", "identity_unknown",
"daemon_unreachable", "not_allowlisted",
"argument_refused", "session_cap_reached", "refused", "timeout",
"readiness_timeout", "busy", "already_managed",
}
assert set(EXIT_CODE_FOR_ERROR) == documented
def test_success_is_zero():
assert exit_code_for(None) == 0
assert exit_code_for("") == 0
def test_an_unknown_error_degrades_to_not_usable_rather_than_to_success():
"""A caller that does not recognise the failure must still not see a 0."""
assert exit_code_for("something_invented_next_year") == ExitCode.BAD_STATE
def test_reply_exit_code_reads_a_decoded_reply():
assert reply_exit_code({"ok": True, "id": "a"}) == 0
assert reply_exit_code({"ok": False, "error": "no_such_session"}) == 3
assert reply_exit_code({"ok": False}) == ExitCode.BAD_STATE
def test_client_errors_carry_their_own_code():
assert ClientError("daemon_unreachable", "no socket").exit_code == 5
assert ClientError("timeout", "no reply").exit_code == 7