"""The stream verbs: the phrase, the record, the teardown order and the sweep. Both ends are real. The broker end is the manager, its `LiveStreams` client and its registry; the daemon end is the shipped `Control` and `ControlServer` over a real ``AF_UNIX`` socket. Only two things are substituted: the clock, because the viewer sweep's effect on an idle deadline has to be testable without waiting a minute, and the *capture*, because this machine has no compositor — a `grim` here would fail for a reason none of these tests are about. What that leaves real is everything the feature actually turns on: that a phrase minted by the broker is one the daemon accepts, that it survives a re-enable, that a stream is detached before its output is removed, and that a connected viewer moves the idle clock when nothing else does. """ from __future__ import annotations import asyncio import contextlib import socket import threading from pathlib import Path import pytest from fakes import check_path from hhstream_live import phrase as phrase_mod from hhstream_live.control import Control, ControlServer from hhstream_live.publisher import StreamRegistry from hhstreamd.clock import ManualClock from hhstreamd.manager import ManagerConfig, ManagerError, SessionManager from hhstreamd.policy import Policy from hhstreamd.protocol import ExitCode, exit_code_for from hhstreamd.registry import ContainerState, Session, State, container_record #: A JPEG the publisher will accept without a compositor. One pixel, enough #: for `Stream` to have captured something. ONE_PIXEL_JPEG = b"\xff\xd8\xff\xd9" def make_session(session_id: str = "foot-aaaaaa", *, container: bool = True) -> Session: return Session( id=session_id, app="foot", argv=["/usr/bin/foot"], pid=4242, pgid=4242, sid=4242, pid_starttime=918342, cmdline_sha256="9f2c", home="/home/someone", runtime_dir=f"/run/hhstream/sessions/{session_id}", created_at="2026-10-01T09:14:02Z", created_boottime=1000.0, last_activity_at="2026-10-01T09:14:02Z", last_activity_boottime=1000.0, idle_timeout_s=10800.0, state=State.READY, container=( container_record( output=f"hh-{session_id}", workspace=1000, mode=(1280, 720), created_by="broker", state=ContainerState.OWNED, ) if container else None ), ) class FakeCapture: """A capture with no compositor. Counts grabs so a test can see one.""" def __init__(self) -> None: self.grabs = 0 def grab(self) -> bytes: self.grabs += 1 return ONE_PIXEL_JPEG class FakeLiveDaemon: """The shipped `Control` and protocol loop, with a poll-interval accept. The accept loop is the one thing not shipped, for `FakeDriver`'s reason: ``serve_forever`` blocks in ``accept()`` by design and closing a listening socket does not reliably wake a thread already inside it, so a fake that used it would cost every test the stop timeout. """ PORT = 9988 def __init__(self, socket_path: Path) -> None: check_path(Path(socket_path)) self.registry = StreamRegistry() self.captures: dict[str, FakeCapture] = {} self.control = Control( self.registry, capture_for=self._capture_for, url_for=lambda phrase: f"http://127.0.0.1:{self.PORT}/{phrase}/", ) self.server = ControlServer(Path(socket_path), self.control) self.server.listen() self.socket_path = Path(socket_path) self.connections: list[socket.socket] = [] self._stop = threading.Event() self._listener = self.server._sock self._listener.settimeout(0.05) self._thread = threading.Thread(target=self._serve, daemon=True) self._thread.start() def _capture_for(self, output: str) -> FakeCapture: capture = FakeCapture() self.captures[output] = capture return capture def _serve(self) -> None: while not self._stop.is_set(): try: conn, _ = self._listener.accept() except (TimeoutError, socket.timeout): continue except OSError: return self.connections.append(conn) with conn: self.server._serve_connection(conn) def watch(self, phrase: str, viewers: int = 1) -> None: """Pretend ``viewers`` browsers are connected to ``phrase``.""" stream = self.registry.get(phrase) assert stream is not None, "nothing is published under that phrase" for _ in range(viewers): stream.add_viewer() def unwatch(self, phrase: str) -> None: stream = self.registry.get(phrase) assert stream is not None while stream.viewers: stream.remove_viewer() def outputs(self) -> list[str]: return [s.spec.output for s in self.registry.all()] def stop(self) -> None: """Stop answering, for real. Shutting the *accepted* connections down matters and is easy to get wrong: the broker holds one open between ops, so a stop that only closed the listener would leave a thread still sitting in `readline` and still answering `list` -- and the "the daemon is down" tests would pass against a daemon that was up. """ self._stop.set() for conn in self.connections: with contextlib.suppress(OSError): conn.shutdown(socket.SHUT_RDWR) self._thread.join(timeout=2) self.registry.stop_all() self.server.close() class Harness: def __init__(self, manager: SessionManager, daemon: FakeLiveDaemon, clock: ManualClock): self.manager = manager self.daemon = daemon self.clock = clock def add(self, session_id: str = "foot-aaaaaa", **kwargs) -> Session: return self.manager.registry.add(make_session(session_id, **kwargs)) def run(self, coro): return asyncio.run(coro) @pytest.fixture def harness(short_tmpdir: Path): daemon = FakeLiveDaemon(short_tmpdir / "live.sock") clock = ManualClock(boottime=1000.0) manager = SessionManager( ManagerConfig( state_dir=short_tmpdir / "state", runtime_dir=short_tmpdir / "run", policy=Policy(), live_socket=daemon.socket_path, ), clock=clock, ) try: yield Harness(manager, daemon, clock) finally: if manager.live is not None: manager.live.close() daemon.stop() # ── enable ───────────────────────────────────────────────────────────────── def test_enabling_mints_a_phrase_the_daemon_accepts_and_publishes(harness): harness.add() reply = harness.run(harness.manager.stream_enable("foot-aaaaaa")) stream = reply["stream"] assert stream["enabled"] is True assert stream["attached"] is True assert stream["output"] == "hh-foot-aaaaaa" # The phrase the broker minted is one the daemon's own validator took. assert phrase_mod.validate(stream["phrase"]) == stream["phrase"] assert stream["url"].endswith(f"/{stream['phrase']}/") # ...and the daemon really is publishing that output. assert harness.daemon.outputs() == ["hh-foot-aaaaaa"] def test_the_url_is_the_daemon_s_and_is_not_in_the_record(harness): """So anything answering with the record alone must merge the reply in. REGRESSION. `start --stream` built its answer from `Session.public()`, which reports what was *stored* -- and a `url` is never stored, because naming one is the daemon's (CONTRACT-sessions.md §3.5). The result was a successful start whose stream had no URL, which the CLI could not tell from a stream that failed to open: it printed "the session is running but its stream was not enabled" over a stream the daemon had just attached. Found by checks/vm-stream.nix, which is also where the `start --stream` path is proven end to end -- there is no launcher here. """ harness.add() reply = harness.run(harness.manager.stream_enable("foot-aaaaaa")) assert reply["stream"]["url"] stored = harness.manager.registry.get("foot-aaaaaa").public(harness.clock.boottime()) assert stored["stream"]["phrase"] == reply["stream"]["phrase"] assert "url" not in stored["stream"] def test_the_phrase_is_in_the_record_so_it_survives_a_restart(harness): harness.add() first = harness.run(harness.manager.stream_enable("foot-aaaaaa"))["stream"] stored = harness.manager.registry.get("foot-aaaaaa").stream assert stored["phrase"] == first["phrase"] # And it is on disk, not just in memory: a URL somebody was read out to # must not change because the broker bounced. records, broken = harness.manager.registry.load_records() assert broken == [] on_disk = {record.id: record for record in records} assert on_disk["foot-aaaaaa"].stream["phrase"] == first["phrase"] def test_re_enabling_returns_the_same_phrase_and_starts_no_second_capture(harness): harness.add() first = harness.run(harness.manager.stream_enable("foot-aaaaaa"))["stream"] again = harness.run(harness.manager.stream_enable("foot-aaaaaa"))["stream"] assert again["phrase"] == first["phrase"] assert again["url"] == first["url"] # One stream on the daemon, not two: a re-enable after a restart must not # double the grim rate on one output. assert len(harness.daemon.registry.all()) == 1 def test_a_phrase_that_is_not_this_session_s_is_refused_not_rotated(harness): harness.add() harness.run(harness.manager.stream_enable("foot-aaaaaa")) mine = harness.manager.registry.get("foot-aaaaaa").stream["phrase"] with pytest.raises(ManagerError) as caught: harness.run( harness.manager.stream_enable("foot-aaaaaa", phrase=phrase_mod.generate()) ) assert caught.value.error == "stream_busy" assert exit_code_for(caught.value.error) == ExitCode.BUSY # The stored one is untouched: somebody may be holding its URL. assert harness.manager.registry.get("foot-aaaaaa").stream["phrase"] == mine def test_disable_then_enable_rotates_the_phrase(harness): harness.add() first = harness.run(harness.manager.stream_enable("foot-aaaaaa"))["stream"]["phrase"] harness.run(harness.manager.stream_disable("foot-aaaaaa")) second = harness.run(harness.manager.stream_enable("foot-aaaaaa"))["stream"]["phrase"] assert second != first assert harness.daemon.registry.get(first) is None def test_a_caller_s_own_phrase_is_held_to_the_generated_shape(harness): harness.add() with pytest.raises(ManagerError) as caught: harness.run(harness.manager.stream_enable("foot-aaaaaa", phrase="a-b-c")) assert caught.value.error == "invalid_argument" assert exit_code_for(caught.value.error) == ExitCode.USAGE # The refusal must not echo the phrase: this reason is logged. assert "a-b-c" not in caught.value.reason def test_a_session_with_no_container_is_refused_and_never_falls_back(harness): """The main output carries every other session. This is the one that matters.""" harness.add(container=False) with pytest.raises(ManagerError) as caught: harness.run(harness.manager.stream_enable("foot-aaaaaa")) assert caught.value.error == "stream_unavailable" assert exit_code_for(caught.value.error) == ExitCode.COMPOSITOR assert harness.daemon.outputs() == [] def test_a_bad_rate_is_a_usage_error_from_the_broker(harness): harness.add() for bad in (0, -1): with pytest.raises(ManagerError) as caught: harness.run(harness.manager.stream_enable("foot-aaaaaa", fps=bad)) assert caught.value.error == "invalid_argument" def test_a_rate_over_the_daemon_s_cap_is_refused_by_the_daemon(harness): """The cap belongs to the process that has to keep up with it.""" harness.add() with pytest.raises(ManagerError) as caught: harness.run(harness.manager.stream_enable("foot-aaaaaa", fps=1000)) # The daemon's `invalid_argument` kind, mapped to exit 2 by the broker. assert caught.value.error == "invalid_argument" assert harness.daemon.outputs() == [] def test_no_daemon_configured_is_unavailable_and_not_a_dead_session(harness, short_tmpdir): manager = SessionManager( ManagerConfig( state_dir=short_tmpdir / "s2", runtime_dir=short_tmpdir / "r2", policy=Policy(), live_socket=short_tmpdir / "nothing-here.sock", ), clock=ManualClock(boottime=1000.0), ) manager.registry.add(make_session()) with pytest.raises(ManagerError) as caught: asyncio.run(manager.stream_enable("foot-aaaaaa")) assert caught.value.error == "stream_unavailable" # Exit 10, which the table defines as "the session is NOT lost". assert exit_code_for(caught.value.error) == ExitCode.COMPOSITOR assert manager.registry.get("foot-aaaaaa").live # ── disable ──────────────────────────────────────────────────────────────── def test_disabling_stops_the_capture_and_clears_the_record(harness): harness.add() harness.run(harness.manager.stream_enable("foot-aaaaaa")) reply = harness.run(harness.manager.stream_disable("foot-aaaaaa")) assert reply["detached"] is True assert reply["stream"] is None assert harness.manager.registry.get("foot-aaaaaa").stream is None assert harness.daemon.outputs() == [] def test_disabling_a_stream_the_daemon_forgot_is_not_an_error(harness): """The ordinary case after the daemon restarts; the record still clears.""" harness.add() stream = harness.run(harness.manager.stream_enable("foot-aaaaaa"))["stream"] harness.daemon.registry.remove(stream["phrase"]) # as a restart would reply = harness.run(harness.manager.stream_disable("foot-aaaaaa")) assert reply["detached"] is False assert harness.manager.registry.get("foot-aaaaaa").stream is None def test_disabling_a_session_with_no_stream_says_so(harness): harness.add() with pytest.raises(ManagerError) as caught: harness.run(harness.manager.stream_disable("foot-aaaaaa")) assert caught.value.error == "stream_unavailable" # ── reading ──────────────────────────────────────────────────────────────── def test_the_listing_merges_the_daemon_s_view_into_the_records(harness): harness.add("foot-aaaaaa") harness.add("foot-bbbbbb") harness.run(harness.manager.stream_enable("foot-aaaaaa")) phrase = harness.manager.registry.get("foot-aaaaaa").stream["phrase"] harness.daemon.watch(phrase, viewers=3) reply = harness.manager.stream_list() assert reply["available"] is True assert [row["id"] for row in reply["streams"]] == ["foot-aaaaaa"] assert reply["streams"][0]["viewers"] == 3 assert reply["streams"][0]["attached"] is True def test_a_down_daemon_turns_attached_false_rather_than_failing_the_read(harness): harness.add() harness.run(harness.manager.stream_enable("foot-aaaaaa")) harness.daemon.stop() reply = harness.manager.stream_list() assert reply["available"] is False row = reply["streams"][0] assert row["attached"] is False # No stale URL and no stale count: absent is the honest answer. assert "url" not in row assert "viewers" not in row # The phrase is still there, which is what makes a re-enable the same URL. assert row["phrase"] def test_status_of_a_session_with_no_stream_is_a_null_not_an_error(harness): harness.add() assert harness.manager.stream_status("foot-aaaaaa")["stream"] is None def test_status_with_no_id_is_the_listing(harness): harness.add() assert "streams" in harness.manager.stream_status(None) # ── the idle clock ───────────────────────────────────────────────────────── def test_enabling_and_reading_do_not_touch_the_idle_clock(harness): session = harness.add() before = session.last_activity_boottime harness.clock.advance(300.0) harness.run(harness.manager.stream_enable("foot-aaaaaa")) harness.manager.stream_list() harness.manager.stream_status("foot-aaaaaa") assert harness.manager.registry.get("foot-aaaaaa").last_activity_boottime == before def test_a_connected_viewer_is_activity_and_moves_the_deadline(harness): """The one exception to "`touch` is the only mark of activity".""" session = harness.add() before = session.last_activity_boottime harness.run(harness.manager.stream_enable("foot-aaaaaa")) phrase = harness.manager.registry.get("foot-aaaaaa").stream["phrase"] harness.daemon.watch(phrase) harness.clock.advance(600.0) touched = harness.run(harness.manager._touch_watched()) assert touched == ["foot-aaaaaa"] after = harness.manager.registry.get("foot-aaaaaa").last_activity_boottime assert after == before + 600.0 def test_an_enabled_stream_nobody_watches_keeps_nothing_alive(harness): """Otherwise a forgotten `enable` would be an immortal session.""" session = harness.add() before = session.last_activity_boottime harness.run(harness.manager.stream_enable("foot-aaaaaa")) harness.clock.advance(600.0) assert harness.run(harness.manager._touch_watched()) == [] assert harness.manager.registry.get("foot-aaaaaa").last_activity_boottime == before def test_the_sweep_touches_only_the_sessions_being_watched(harness): harness.add("foot-aaaaaa") harness.add("foot-bbbbbb") for session_id in ("foot-aaaaaa", "foot-bbbbbb"): harness.run(harness.manager.stream_enable(session_id)) watched = harness.manager.registry.get("foot-bbbbbb").stream["phrase"] harness.daemon.watch(watched) assert harness.run(harness.manager._touch_watched()) == ["foot-bbbbbb"] def test_the_sweep_survives_a_daemon_that_is_not_there(harness): harness.add() harness.run(harness.manager.stream_enable("foot-aaaaaa")) harness.daemon.stop() assert harness.run(harness.manager._touch_watched()) == [] def test_the_viewer_audit_entry_never_carries_the_phrase(harness): """The audit log is read by whoever can read logs, and this is a password.""" harness.add() harness.run(harness.manager.stream_enable("foot-aaaaaa")) phrase = harness.manager.registry.get("foot-aaaaaa").stream["phrase"] harness.daemon.watch(phrase) harness.run(harness.manager._touch_watched()) written = (Path(harness.manager.config.state_dir) / "events.jsonl").read_text() assert "stream_viewer_activity" in written assert "stream_enable" in written assert phrase not in written # ── teardown order ───────────────────────────────────────────────────────── def test_a_kill_detaches_the_stream_before_removing_the_output(harness): """Order is load-bearing: a capture aimed at a removed output fails every time, and the daemon's failure budget would close the viewers saying "unknown output" instead of the session simply ending.""" harness.add() harness.run(harness.manager.stream_enable("foot-aaaaaa")) order: list[str] = [] real_detach = harness.manager._detach_stream real_destroy = harness.manager._destroy_container async def detach(session): order.append("detach") return await real_detach(session) def destroy(session): order.append("output remove") return real_destroy(session) harness.manager._detach_stream = detach harness.manager._destroy_container = destroy harness.run( harness.manager.teardown( harness.manager.registry.get("foot-aaaaaa"), reason="kill", grace_s=0.1 ) ) assert order == ["detach", "output remove"] assert harness.daemon.outputs() == []