From 7d8ca6191bb908ed2bdfb73357b739bda6792766 Mon Sep 17 00:00:00 2001 From: Hermenix Date: Sun, 11 Oct 2026 22:47:43 +0000 Subject: [PATCH] feat(sessions)!: the four stream verbs, schema 4, and the viewer sweep The broker half of sessions-v4: `stream.enable`, `stream.disable`, `stream.list`, `stream.status`, `start`'s three new arguments, and the one rule that is genuinely new rather than additive -- a connected viewer is activity. The decisions worth reading the diff for: **A stream never falls back to the main output.** `_stream_output` refuses when a session has no container, and the refusal is stronger than the pointer's for a reason the hint states: the main output carries *every other session*, so a fallback would put somebody else's desktop on a phone behind a phrase that was issued for this one. **The phrase lives in the record, so re-enabling returns the same URL.** A different `--phrase` on an already-enabled session is `stream_busy` (exit 8), not a silent rotation: rotating under a caller who is holding the old URL is the one outcome neither answer can be mistaken for. `disable` then `enable` is how it rotates, which is explicit. **`_checked_phrase` raises the shape and never the value**, with `from None`, for `control._phrase_of`'s reason: `phrase.validate` names what it rejected, and this value is a password on its way into an error reply and a log. **`fps` is only sent when a caller named one** (`_checked_fps` returns `None` otherwise), which is what makes the daemon's own default authoritative instead of decorative. The broker holds the daemon to the frozen cap before sending, so a nonsense rate is exit 2 from the verb rather than a surprise from the socket. **`attached` is its own field and is not folded into `enabled`.** A record can say the operator asked for a stream while the daemon is down, and those are two different facts; `url` and `viewers` are *absent* rather than stale when it is false, because a URL that no longer serves anything is worse than no URL. `stream.list` also reports `available`, so "no streams" is distinguishable from "no daemon" without parsing an error. **The viewer sweep** (`_sweep_streams`, every `STREAM_SWEEP_S = 60`s) asks the daemon for viewer counts and stamps `touch` on every session somebody is watching. It is the only thing in this daemon that treats an observation as an intention, and it exists for one failure: an operator watching a long job on his phone and losing the session at three hours *because* watching was all he was doing. It cannot hold a session open by itself -- an enabled stream with no viewer runs no `grim` and stamps nothing -- which is why it is safe to run unconditionally. **Teardown detaches before it destroys the container.** The other order makes every capture fail against a removed output, which is a stream that gives up ten frames later and a log that blames `grim`. `start` takes `stream`, `stream_phrase` and `stream_fps` and reports a stream it could not open in `stream_error` beside a session that *did* start, because the exit code is 0 and a caller who asked for a stream must not read that as one. Registry schema 3 -> 4: the record gains `stream`, older records migrate to `null` rather than being refused, and the viewer count is deliberately not stored -- a viewer count on disk is a number that is wrong the moment it is written. No new exit numbers: `stream_busy` -> 8, `stream_budget` -> 6, `stream_unavailable` -> 10. The last one is 10 for `driver_refused`'s reason -- the session keeps running, and a caller that read an unreachable stream as a dead session would kill an application over a web page. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE --- src/hhstreamd/manager.py | 472 +++++++++++++++++++++++++++++++++++++- src/hhstreamd/protocol.py | 21 ++ src/hhstreamd/registry.py | 63 ++++- src/hhstreamd/server.py | 33 +++ 4 files changed, 579 insertions(+), 10 deletions(-) diff --git a/src/hhstreamd/manager.py b/src/hhstreamd/manager.py index 1cf3def..d37a6f8 100644 --- a/src/hhstreamd/manager.py +++ b/src/hhstreamd/manager.py @@ -57,6 +57,7 @@ from .container_host import ( ContainerHost, ) from .driver import DriverRejected, DriverUnavailable, PointerDriver +from .live import Attachment, LiveRejected, LiveStreams, LiveUnavailable from .ipc import CompositorUnavailable from .launcher import Launcher from .pointer import Bookmark, LeaseBusy, LeaseInvalid, PointerLease @@ -70,6 +71,7 @@ from .registry import ( State, container_record, pointer_record, + stream_record, ) from .textio import tail_lines @@ -110,6 +112,16 @@ READBACK_INTERVAL_S = 0.05 #: as long as nobody asks. POINTER_SWEEP_S = 1.0 +#: How often the broker asks the stream daemon for viewer counts, and stamps +#: `touch` on every session that has one (CONTRACT-sessions.md §4). +#: +#: A minute, not a second: this is the one exception to "`touch` is the only +#: mark of activity", and the thing it exists to prevent is a three-hour idle +#: timeout firing under somebody's eyes. Against three hours a minute of +#: granularity is free, and a tighter sweep would be one `grim`-adjacent round +#: trip per second for a fact that changes when a browser tab opens. +STREAM_SWEEP_S = 60.0 + #: The workspace band (CONTRACT-sessions.md §5) and how many slots of it this #: broker will hand out. The real ceiling is a CPU question the plan defers to #: a measurement (PLAN §5.5); the band is the part that can be enforced here, @@ -199,8 +211,17 @@ class ManagerConfig: pointer_ttl_s: float = 30.0 pointer_max_s: float = 300.0 pointer_sweep_s: float = POINTER_SWEEP_S + #: The broker↔stream socket (CONTRACT-sessions.md §3.5). Derived from the + #: runtime dir for the reason `pointer_socket` is: the path is frozen, so a + #: flag for it would be a flag for a value that may not vary. + live_socket: Path | None = None + #: How often the viewer sweep runs. The one thing that moves an idle clock + #: without a caller asking (CONTRACT-sessions.md §4). + stream_sweep_s: float = STREAM_SWEEP_S def __post_init__(self) -> None: + if self.live_socket is None: + self.live_socket = Path(self.runtime_dir) / "live.sock" if self.pointer_socket is None: # `/pointer.sock` is the frozen path # (CONTRACT-sessions.md §5: /run/hhstream/pointer.sock), and @@ -221,6 +242,7 @@ class SessionManager: audit: AuditLog | None = None, host: ContainerHost | None = None, driver: PointerDriver | None = None, + live: LiveStreams | None = None, ) -> None: self.config = config self.clock = clock or Clock() @@ -251,6 +273,10 @@ class SessionManager: ttl_s=config.pointer_ttl_s, max_s=config.pointer_max_s, clock=self.clock.boottime ) self.driver = driver + #: The stream daemon's client, or ``None`` with no socket configured -- + #: in which case every `stream.*` verb answers `stream_unavailable` + #: (exit 10) rather than pretending there is a stream. + self.live = live # Per-session asyncio plumbing, never persisted. self._exited: dict[str, asyncio.Event] = {} self._watchers: dict[str, asyncio.Task] = {} @@ -259,6 +285,7 @@ class SessionManager: #: Held so the loop does not collect a task mid-flight. self._background: set[asyncio.Task] = set() self._pointer_sweeper: asyncio.Task | None = None + self._stream_sweeper: asyncio.Task | None = None #: Set while a lease is held with a caller-supplied TTL, so the default #: comes back when the lease ends (the frozen ``acquire`` takes no TTL). self._pointer_ttl_override = False @@ -339,6 +366,13 @@ class SessionManager: self._pointer_sweeper = asyncio.create_task( self._sweep_pointer(), name="hhstreamd.pointer-sweep" ) + # Unconditional, even with no stream enabled anywhere: the sweep's own + # first act is to ask the daemon, and a broker that only started it on + # the first `enable` would be a broker whose adopted records were not + # being watched after a restart. + self._stream_sweeper = asyncio.create_task( + self._sweep_streams(), name="hhstreamd.stream-sweep" + ) return summary # ------------------------------------------------------------------ @@ -632,11 +666,14 @@ class SessionManager: """ await self.reaper.stop() - if self._pointer_sweeper is not None: - self._pointer_sweeper.cancel() + for name in ("_pointer_sweeper", "_stream_sweeper"): + sweeper = getattr(self, name) + if sweeper is None: + continue + sweeper.cancel() with contextlib.suppress(asyncio.CancelledError, Exception): - await self._pointer_sweeper - self._pointer_sweeper = None + await sweeper + setattr(self, name, None) for task in list(self._background): task.cancel() for task in list(self._background): @@ -650,6 +687,12 @@ class SessionManager: with contextlib.suppress(Exception): await self._release_all_buttons() self.driver.close() + if self.live is not None: + # Nothing to lift on this one: a stream left attached across a + # broker restart is re-attached by `enable`, and the daemon keeps + # publishing meanwhile -- which is the behaviour an operator + # watching a long job wants. + self.live.close() for task in list(self._watchers.values()): task.cancel() for task in list(self._watchers.values()): @@ -878,6 +921,9 @@ class SessionManager: wait_ready_s: float | None = None, home: str | None = None, ephemeral_home: bool = False, + stream: bool = False, + stream_phrase: str | None = None, + stream_fps: int | None = None, ) -> dict[str, Any]: policy = self.config.policy policy.check_capacity(len(self.registry.live())) @@ -971,8 +1017,38 @@ class SessionManager: ready = await self._settle(session, wait_ready) if session.live: await self._read_back(session, app_id) + stream_error: str | None = None + if stream and session.live: + # After the read-back, because that is what settles the container's + # output, and a stream has to have one to publish + # (`_stream_output`). Before the record below, so the phrase comes + # back with the session the caller asked for -- which is the whole + # reason `start` takes these arguments instead of making every + # caller sequence "start, then enable" and handle the half-done + # case in between. + # + # A stream that cannot be opened does NOT fail the start. The + # application is on the screen and killing it over a web page would + # be the wrong trade; the refusal is reported on the session's + # `stream_error` and the caller can retry `stream.enable`. + try: + await self.stream_enable( + session.id, phrase=stream_phrase, fps=stream_fps + ) + except ManagerError as exc: + log.warning("could not enable %s's stream: %s", session.id, exc.reason) + session.last_error = session.last_error or exc.reason + # A local, not an attribute: two starts can be in flight at + # once and an attribute would hand one of them the other's + # failure. + stream_error = exc.reason self.reaper.wake() record = session.public(self.now()) + if stream: + # Present whenever a stream was asked for, `None` when it worked: + # a key that appears only on failure is a key every caller has to + # remember to look for. + record["stream_error"] = stream_error if session.state == State.EXITED: # The app exited during the settle: surface it rather than handing # back a healthy-looking id (DESIGN.md §7 #3). @@ -1235,7 +1311,17 @@ class SessionManager: # has four values (lease|timeout|crash|kill), and a reap is the # broker killing the session. await self._drop_lease_for(session, reason="kill") + # The stream goes BEFORE the output does, and the order is + # load-bearing (CONTRACT-sessions.md §4): a capture aimed at a + # removed output fails every time, so the daemon's own failure + # budget would close the viewers with "unknown output" instead of + # the session simply ending. Never raises -- a daemon that cannot + # be reached must not stop a session being killed. + stream_detached = await self._detach_stream(session) + if (session.stream or {}).get("phrase"): + session.stream = None container_result = self._destroy_container(session) + container_result["stream_detached"] = stream_detached if refused is None: state_now = state @@ -1929,6 +2015,368 @@ class SessionManager: # -- lease internals -------------------------------------------------- + # ------------------------------------------------------------------ + # the live stream (CONTRACT-sessions.md §4, v4) + # ------------------------------------------------------------------ + + async def stream_enable( + self, session_id: str, *, phrase: str | None = None, fps: int | None = None + ) -> dict[str, Any]: + """Publish this session's container output under a spoken phrase. + + **Does not** count as activity, like every `pointer.*` verb: switching + a stream on is not saying the session is wanted. What *is* activity is + somebody watching it, and that is :meth:`_sweep_streams`. + + The phrase is minted here and stored in the record, so it survives a + broker restart and a re-enable: an operator who read four words out to + somebody must not have them change because the daemon bounced. A + caller's own `phrase` is held to the generated shape -- it is this + stream's only credential, so anything a caller may set is a password, + and a looser check would accept `a-b-c`. + + Re-enabling an enabled session returns the same phrase. A different + `phrase` is `stream_busy` (exit 8) rather than a silent rotation, + because rotating under a caller who is holding the old URL is the one + outcome neither answer can be mistaken for. + """ + + session = self._require_live(session_id) + output = self._stream_output(session) + rate = self._checked_fps(fps) + stored = session.stream or {} + wanted = self._checked_phrase(phrase) + + if stored.get("phrase") and wanted and wanted != stored["phrase"]: + raise ManagerError( + "stream_busy", + f"session {session.id} already has a stream under a different phrase", + hint="`stream disable` then `stream enable` rotates it; a stream " + "cannot have two phrases, because the old one is a URL somebody " + "may be holding", + id=session.id, + ) + settled = stored.get("phrase") or wanted or self._mint_phrase() + # The stored rate wins on a re-enable with no `fps`: a re-attach after a + # restart must not quietly re-rate a stream somebody is watching. With + # neither, the rate is left UNSET and the daemon applies its own + # configured default -- the broker does not have one, on purpose. + rate = rate or stored.get("fps") + + attachment = await self._attach_stream( + session, phrase=settled, output=output, fps=None if rate is None else int(rate) + ) + record = stream_record( + phrase=settled, + output=output, + fps=attachment.fps, + enabled_at=stored.get("enabled_at") or iso(self.clock.wall()), + ) + session.stream = record + # `force=True`: the phrase is the one field here that cannot be + # re-derived, so it is on disk before the caller is told what it is. + self.registry.persist(session, force=True) + # The phrase is NOT in the audit entry (CONTRACT-sessions.md §3.5): the + # log is read by whoever can read logs, and this one is a password. + self.audit.emit( + "stream_enable", id=session.id, output=output, fps=attachment.fps + ) + return {"id": session.id, "stream": self._stream_public(record, attachment)} + + async def stream_disable(self, session_id: str) -> dict[str, Any]: + """Stop publishing, and clear the record. + + Detaching a stream the daemon has already forgotten is **not** an + error: `disable` after a daemon restart is the ordinary case, and the + record has to be cleared either way. `detached` says which happened. + """ + + session = self._require_live(session_id) + stored = session.stream or {} + if not stored.get("phrase"): + raise ManagerError( + "stream_unavailable", + f"session {session.id} has no stream to disable", + hint="`stream enable` first", + id=session.id, + ) + detached = await self._detach_stream(session) + session.stream = None + self.registry.persist(session, force=True) + self.audit.emit( + "stream_disable", id=session.id, output=stored.get("output"), detached=detached + ) + return {"id": session.id, "stream": None, "detached": detached} + + def stream_list(self) -> dict[str, Any]: + """Every session with a stream, with the daemon's view merged in. + + Does not count as activity. ``available`` is whether the daemon could + be asked at all, so a caller can tell "no streams" from "no daemon" + without parsing an error. + """ + + attachments, available = self._attachments() + streams = [] + for session in self.registry.live(): + stored = session.stream or {} + if not stored.get("phrase"): + continue + streams.append( + { + "id": session.id, + "app": session.app, + **self._stream_public(stored, attachments.get(stored["phrase"])), + } + ) + return {"streams": streams, "available": available} + + def stream_status(self, session_id: str | None = None) -> dict[str, Any]: + """One session's stream, or every one of them. Not activity.""" + + if session_id is None: + return self.stream_list() + session = self._require(session_id) + stored = session.stream or {} + if not stored.get("phrase"): + return {"id": session.id, "stream": None} + attachments, _ = self._attachments() + return { + "id": session.id, + "stream": self._stream_public(stored, attachments.get(stored["phrase"])), + } + + # -- the pieces the four verbs share --------------------------------- + + def _stream_output(self, session: Session) -> str: + """The output a stream publishes: the session's own container. + + Refused rather than defaulted, and the reason is stronger than the + pointer's: the main output carries *every other session*, so falling + back to it would put somebody else's desktop on a phone behind a phrase + that was issued for this one. + """ + + output = (session.container or {}).get("output") + if output: + return str(output) + raise ManagerError( + "stream_unavailable", + f"session {session.id} has no container output to publish", + hint="a stream never falls back to the main output -- that one " + "carries every other session. `container.reconcile` once the " + "compositor is reachable, or start the session with containers on", + id=session.id, + container=session.container, + ) + + def _mint_phrase(self) -> str: + """A fresh phrase. + + From `hhstream_live.phrase`, which owns the wordlist, the shape and the + validator -- one definition, so a phrase the broker mints is one the + daemon will accept and a `--phrase` an operator types is held to the + same bar. Imported here rather than at module scope because this is the + only path that needs it and `hhstreamd` must stay importable without + the web app's wordlist being readable. + """ + + from hhstream_live import phrase as phrase_mod + + return phrase_mod.generate() + + def _checked_phrase(self, phrase: Any) -> str | None: + if phrase is None: + return None + from hhstream_live import phrase as phrase_mod + + if not isinstance(phrase, str): + raise ManagerError( + "invalid_argument", "phrase must be a string", id=None + ) + try: + return phrase_mod.validate(phrase) + except ValueError: + # The validator's own message names the value it refused, which is + # right for an operator reading their own terminal and wrong here: + # this reason reaches the broker's log and the audit trail, and the + # value is a credential (CONTRACT-sessions.md §3.5). So the shape + # is described and the phrase is NOT interpolated -- deliberately, + # and `from None` so the chained message cannot carry it either. + raise ManagerError( + "invalid_argument", + "the phrase given is not of the expected shape", + hint="four words of at least three letters and a five-character " + "tail, e.g. amber-otter-lantern-harbor-7k2qp; omit it to have " + "one minted", + ) from None + + def _checked_fps(self, fps: Any) -> int | None: + if fps is None: + return None + if isinstance(fps, bool) or not isinstance(fps, int): + raise ManagerError( + "invalid_argument", f"fps must be an int, got {type(fps).__name__}" + ) + if fps <= 0: + raise ManagerError("invalid_argument", f"fps must be positive, got {fps}") + # The ceiling is deliberately NOT checked here. It belongs to the + # daemon (`hhstream_live.publisher.FPS_CAP`), which is the process that + # has to keep up with it, and a second copy of the number here would be + # a second thing to raise when the box gets faster. + return fps + + async def _attach_stream( + self, session: Session, *, phrase: str, output: str, fps: int | None + ) -> Attachment: + live = self._live_streams() + if live is None: + raise ManagerError( + "stream_unavailable", + "no stream daemon is configured for this broker", + hint="the `hhstream-live` unit is what captures a stream; " + "`sessions.stream` in the module turns it on", + id=session.id, + ) + try: + return await asyncio.to_thread( + live.attach, + phrase=phrase, + output=output, + fps=fps, + session=session.id, + label=session.app, + ) + except LiveRejected as exc: + # The daemon's own vocabulary, mapped once: its `invalid_argument` + # is the caller's mistake (exit 2) and anything else is a stream + # that could not be opened (exit 10). The same split the driver's + # `kind` already gets. + error = "invalid_argument" if exc.kind == "invalid_argument" else "stream_unavailable" + raise ManagerError(error, str(exc), id=session.id) from exc + except LiveUnavailable as exc: + raise ManagerError( + "stream_unavailable", + f"the stream daemon could not be reached: {exc}", + hint="is hhstream-live running? the session itself is unaffected", + id=session.id, + ) from exc + + async def _detach_stream(self, session: Session) -> bool: + """Stop the capture for this session, if there is one. + + Never raises. Called from `disable`, which has a record to clear + regardless, and from teardown, where a daemon that cannot be reached + must not stop a session from being killed. + """ + + phrase = (session.stream or {}).get("phrase") + live = self._live_streams() + if not phrase or live is None: + return False + try: + return await asyncio.to_thread(live.detach, str(phrase)) + except (LiveRejected, LiveUnavailable) as exc: + log.warning( + "could not detach %s's stream on output %s: %s", + session.id, + (session.stream or {}).get("output"), + exc, + ) + return False + + def _attachments(self) -> tuple[dict[str, Attachment], bool]: + """The daemon's streams by phrase, and whether it answered. + + Synchronous and tolerant: the read verbs report what they can, and a + down daemon turns `attached` false rather than failing a `list` that + has records to show. + """ + + live = self._live_streams() + if live is None: + return {}, False + try: + return {a.phrase: a for a in live.list()}, True + except (LiveRejected, LiveUnavailable) as exc: + log.debug("the stream daemon did not answer `list`: %s", exc) + return {}, False + + @staticmethod + def _stream_public( + stored: dict[str, Any], attachment: Attachment | None + ) -> dict[str, Any]: + """The record, with the daemon's live view merged in. + + ``attached`` is its own field and is **not** folded into ``enabled``: a + record may say a session is enabled while the daemon is down, and "the + operator asked for this" and "a capture is running right now" are two + different facts. ``url`` and ``viewers`` are *absent* when it is false, + rather than stale -- a URL that no longer serves anything is worse than + no URL. + """ + + public = dict(stored) + public["attached"] = attachment is not None + if attachment is not None: + public["url"] = attachment.url + public["viewers"] = attachment.viewers + public["fps"] = attachment.fps + return public + + async def _sweep_streams(self) -> None: + """Stamp `touch` on every session somebody is watching. + + The one exception to "`touch` is the only mark of activity" + (CONTRACT-sessions.md §4), and the only thing in this daemon that + treats an observation as an intention. It exists for one failure: an + operator watching a long job on his phone, saying nothing to the + broker, and losing the session at three hours *because* watching was + all he was doing. + + It cannot hold a session open by itself. An enabled stream with no + viewer runs no `grim` and stamps nothing, so a forgotten `enable` is + not a leak -- which is why this is safe to run unconditionally. + """ + + while True: + await asyncio.sleep(self.config.stream_sweep_s) + try: + await self._touch_watched() + except asyncio.CancelledError: + raise + except Exception: # noqa: BLE001 -- a sweep must outlive one failure + log.exception("the stream viewer sweep failed; continuing") + + async def _touch_watched(self) -> list[str]: + """One pass of the sweep. Returns the ids it touched.""" + + live = self._live_streams() + if live is None: + return [] + try: + counts = await asyncio.to_thread(live.viewers) + except (LiveRejected, LiveUnavailable) as exc: + log.debug("the stream daemon did not answer `viewers`: %s", exc) + return [] + touched: list[str] = [] + for session in self.registry.live(): + phrase = (session.stream or {}).get("phrase") + if not phrase: + continue + viewers = counts.get(str(phrase), 0) + if viewers <= 0: + continue + self.registry.touch(session, force_flush=True) + touched.append(session.id) + self.audit.emit( + "stream_viewer_activity", + id=session.id, + output=(session.stream or {}).get("output"), + viewers=viewers, + ) + return touched + async def _sweep_pointer(self) -> None: """Expire a stale lease even when nobody asks. @@ -2152,6 +2600,22 @@ class SessionManager: self.driver = PointerDriver(self.config.pointer_socket) return self.driver + # -- the stream daemon ------------------------------------------------ + + def _live_streams(self) -> LiveStreams | None: + """The stream daemon's client, built on first use. + + ``None`` rather than raising, unlike :meth:`_pointer_driver`, and the + asymmetry is the point: a pointer verb with no driver is a verb that + cannot do its job, while a *read* of stream state with no daemon has a + true answer -- the records, with ``attached: false``. The write paths + (`_attach_stream`) raise `stream_unavailable` for themselves. + """ + + if self.live is None and self.config.live_socket is not None: + self.live = LiveStreams(self.config.live_socket) + return self.live + async def _drive(self, verb: str, *args: Any) -> Any: """One driver call, off the event loop. diff --git a/src/hhstreamd/protocol.py b/src/hhstreamd/protocol.py index 73d5579..cca2c2f 100644 --- a/src/hhstreamd/protocol.py +++ b/src/hhstreamd/protocol.py @@ -102,8 +102,17 @@ EXIT_CODE_FOR_ERROR: dict[str, ExitCode] = { "pointer_busy": ExitCode.BUSY, # 9 — the lease is required and not held "no_lease": ExitCode.NO_LEASE, + # 8 — a phrase that is not this session's (v4) + "stream_busy": ExitCode.BUSY, + # 6 — the stream daemon's own cap (v4) + "stream_budget": ExitCode.POLICY, # 10 — the compositor side failed; the session itself is fine "compositor": ExitCode.COMPOSITOR, + # The stream could not be reached or has no output to aim at (v4). Exit 10 + # for the reason `driver_refused` is: the *session* keeps running, and a + # caller that treated an unreachable stream as a dead session would kill an + # application over a web page. + "stream_unavailable": ExitCode.COMPOSITOR, "compositor_unavailable": ExitCode.COMPOSITOR, "no_container": ExitCode.COMPOSITOR, "driver_unavailable": ExitCode.COMPOSITOR, @@ -156,6 +165,12 @@ VERBS = ( # warp retargets the keys. So there is no `keyboard.acquire`. "keyboard.key", "keyboard.type", + # v4: the per-session live stream. `list` and `status` read; `enable` and + # `disable` are in the mutation set below. + "stream.enable", + "stream.disable", + "stream.list", + "stream.status", ) #: Verbs whose reply is remembered by ``request_id``, so a caller that died @@ -185,6 +200,12 @@ MUTATING_VERBS = frozenset( # nothing, and a cached one would be a stale one. "keyboard.key", "keyboard.type", + # v4. `enable` mints or rotates a phrase: a retry that minted a second + # one would invalidate the URL somebody is already holding, and + # `disable` is here for symmetry -- a retried disable after a daemon + # restart must report what the first one did. + "stream.enable", + "stream.disable", } ) diff --git a/src/hhstreamd/registry.py b/src/hhstreamd/registry.py index 41770b4..633b75e 100644 --- a/src/hhstreamd/registry.py +++ b/src/hhstreamd/registry.py @@ -23,11 +23,12 @@ from .clock import Clock, iso log = logging.getLogger("hhstreamd.registry") #: 3 adds the container, the pointer bookmark and the compositor signature -#: (PLAN §7). The number is read, never written by anyone but this module: a -#: record carrying an older one is **migrated on load** (:func:`migrate`), not -#: refused, because the processes it describes are still running and refusing -#: the record would strand them. -SCHEMA = 3 +#: (PLAN §7); 4 adds the live stream (CONTRACT-sessions.md §6, v4). The number +#: is read, never written by anyone but this module: a record carrying an older +#: one is **migrated on load** (:func:`migrate`), not refused, because the +#: processes it describes are still running and refusing the record would +#: strand them. +SCHEMA = 4 #: Tombstones survive this long so a ``status`` after an unexplained failure #: still answers the question. ``gc`` prunes them. @@ -138,6 +139,17 @@ class Session: #: ``{bookmark, last_released_at, released_by}``. Absent (``None``) means #: the pointer was never aimed here — not that its position is unknown. pointer: dict[str, Any] | None = None + #: The live stream, or ``None`` for a session nobody switched one on for + #: (CONTRACT-sessions.md §4). ``{enabled, phrase, output, fps, port, + #: enabled_at}``; the daemon's ``url`` and ``viewers`` are merged in by the + #: manager when it could be asked, and are deliberately not stored -- a + #: viewer count on disk is a number that is wrong the moment it is written. + #: + #: The phrase lives here because it has to survive a broker restart and a + #: re-enable: it is the stream's only credential, and an operator who read + #: four words out to somebody must not have them change underneath him + #: because the daemon bounced. + stream: dict[str, Any] | None = None #: ``HYPRLAND_INSTANCE_SIGNATURE`` of the compositor this session's #: container lives in, so a restarted broker re-attaches to the same #: instance instead of picking whichever one is there now. @@ -234,6 +246,38 @@ def container_record( } +def stream_record( + *, + phrase: str, + output: str, + fps: int, + enabled_at: str, +) -> dict[str, Any]: + """One ``stream`` sub-record (CONTRACT-sessions.md §4). + + Only what survives a restart. The daemon's ``url`` and ``viewers`` are + merged in by the manager when it could be asked and are deliberately absent + here: a viewer count on disk is wrong the moment it is written, and a URL + assembled from a remembered port is a URL that lies the first time the + listener moves. + + ``enabled`` is always ``True`` in a stored record. A session that was + never enabled has ``stream: None``, and `disable` clears the field rather + than setting ``enabled: False`` -- "nobody asked for a stream here" and + "somebody asked and then stopped" are the same state as far as anything + downstream is concerned, and two spellings for one state is how a + `if stream:` check starts being wrong. + """ + + return { + "enabled": True, + "phrase": phrase, + "output": output, + "fps": fps, + "enabled_at": enabled_at, + } + + def pointer_record( *, bookmark: dict[str, Any] | None, @@ -284,7 +328,14 @@ def migrate(data: dict[str, Any]) -> dict[str, Any]: upgraded = dict(data) # Only ever *adds* keys. A v2 record that somehow carries a container must # keep it: the field is new to the schema, not new to the session. - for key in ("container", "pointer", "signature"): + # + # `stream` (schema 4) is `None` for the same reason the others are: a + # session written by a daemon that knew nothing of streams had no stream, + # and "no stream" is a defined value rather than a guess. It must NOT be + # invented as `{"enabled": false}` either -- a record that says it was + # asked about and declined is a different claim from one that was never + # asked. + for key in ("container", "pointer", "signature", "stream"): upgraded.setdefault(key, None) upgraded["schema"] = SCHEMA log.info("migrated record %s from schema %s to %s", data.get("id"), schema, SCHEMA) diff --git a/src/hhstreamd/server.py b/src/hhstreamd/server.py index 0660994..7fa81d0 100644 --- a/src/hhstreamd/server.py +++ b/src/hhstreamd/server.py @@ -75,6 +75,10 @@ class ControlServer: "pointer.state": self._op_pointer_state, "keyboard.key": self._op_keyboard_key, "keyboard.type": self._op_keyboard_type, + "stream.enable": self._op_stream_enable, + "stream.disable": self._op_stream_disable, + "stream.list": self._op_stream_list, + "stream.status": self._op_stream_status, } # ------------------------------------------------------------------ @@ -264,6 +268,9 @@ class ControlServer: wait_ready_s=request.get("wait_ready_s"), home=request.get("home"), ephemeral_home=bool(request.get("ephemeral_home", False)), + stream=bool(request.get("stream", False)), + stream_phrase=request.get("stream_phrase"), + stream_fps=request.get("stream_fps"), ) return protocol.ok(id=record["id"], state=record["state"], session=record) @@ -297,6 +304,32 @@ class ControlServer: ) return protocol.ok(id=record["id"], state=record["state"], session=record) + async def _op_stream_enable( + self, request: dict[str, Any], caller: dict[str, Any] + ) -> dict[str, Any]: + return protocol.ok( + **await self.manager.stream_enable( + request.get("id"), + phrase=request.get("phrase"), + fps=request.get("fps"), + ) + ) + + async def _op_stream_disable( + self, request: dict[str, Any], caller: dict[str, Any] + ) -> dict[str, Any]: + return protocol.ok(**await self.manager.stream_disable(request.get("id"))) + + async def _op_stream_list( + self, request: dict[str, Any], caller: dict[str, Any] + ) -> dict[str, Any]: + return protocol.ok(**self.manager.stream_list()) + + async def _op_stream_status( + self, request: dict[str, Any], caller: dict[str, Any] + ) -> dict[str, Any]: + return protocol.ok(**self.manager.stream_status(request.get("id"))) + async def _op_container_list( self, request: dict[str, Any], caller: dict[str, Any] ) -> dict[str, Any]: