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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-11 22:47:43 +00:00
1 parent 8c99518a62
commit 7d8ca6191b
4 files changed
+579 -10

No files matched your search

+468 -4
View File
@@ -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:
# `<runtime dir>/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.
+21
View File
@@ -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",
}
)
+57 -6
View File
@@ -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)
+33
View File
@@ -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]: