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:
1 parent
8c99518a62
commit
7d8ca6191b
4 files changed
+579
-10
No files matched your search
+468
-4
@@ -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.
|
||||
|
||||
|
||||
@@ -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",
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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]:
|
||||
|
||||
Reference in new issue
Block a user