Files
hyprland-headless-stream-pl…/src/hhstreamd/container_host.py
T
HermenixandClaude Opus 5 129430bffd wire the broker to the compositor, containers and pointer
The four slices existed and nothing called them. Now the broker builds a
spatial container per session, reads back what the compositor actually did,
and aims the cursor into one container under a broker-wide lease.

Record schema 3 (registry.py): `container` {output, workspace, mode,
created_by, state}, `pointer` {bookmark, last_released_at, released_by} and
the compositor's `signature`. A v2 record is migrated on load, not refused —
its application is still running. Every field that could not be verified is
null; `container: null` means "no container", never "probably something".

Containers (new container_host.py, manager.py, launcher.py): `start`
allocates a slot from `WorkspaceAllocator`, runs `container_plan()`'s argv,
launches the app with the container stamp in its environment, then reads the
workspace, output and window back out of `clients -j`. Teardown removes the
output, releases the slot and reports survivors rather than claiming success
— and runs for an unprompted exit and for `gc` too, so no container is ever
left unattended. Broker start-up reconciles: adopt `hh-*` outputs a live
session claims, remove the rest, `contains_output()` being the only filter.
No IPC means `container: degraded` and lifecycle verbs unchanged.

The plans' argv are dispatched over the compositor's request socket rather
than by executing `hyprctl`, which is what hyprctl does with the same words;
the reply is checked, so a refused command is not recorded as a container.

Pointer (new driver.py, manager.py): a client for the driver's private
socket, and `pointer.acquire|move|button|click|release|state` on top of
`PointerLease`. The broker owns the lease, the driver executes. The bookmark
is marked on every move and before release and stored in the record, so it
survives a restart. On expiry `pressed()` is read before `expire()` and
`release_all` goes to the driver, because the lease cannot lift a button
itself; a sweep runs unprompted so the TTL is a promise.

containers.py to v2: `quarantine_plan()` -> `quarantine_argv()`, with the
before-any-per-session-rule ordering stated where the caller could get it
wrong. protocol.py: 9 NO_LEASE, 10 COMPOSITOR, the verb table, and the
`request_id` cache moved out of the server so the CLI agrees with it.

Tests: real AF_UNIX everywhere — a stateful fake compositor and the shipped
pointer driver behind a recording sink. No mocked sockets, no compositor, no
VM. 551 -> 693.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017mUq7QvQ9EZb2Wi35xj4cs
2026-10-02 19:47:33 +00:00

396 lines
16 KiB
Python

"""The impure half of containers: running the plans and reading the result back.
:mod:`hhstreamd.containers` decides *what* a container is — argv lists, a
workspace slot, an output name — and deliberately cannot run any of it. This
module is the other side of that line: it owns the compositor connection, turns
a :class:`~hhstreamd.containers.ContainerPlan` into real outputs and rules, and
then asks the compositor what actually happened. Keeping the two apart is what
lets every placement decision be unit-tested without a compositor, and confines
everything that *needs* one to a single file.
Three decisions worth finding here.
**Commands go over the request socket, not through ``hyprctl``.** The plans are
``["hyprctl", "keyword", ...]`` argv lists, and running them literally would
mean a subprocess per command, ``hyprctl`` on the broker's ``PATH``, and
``HYPRLAND_INSTANCE_SIGNATURE``/``XDG_RUNTIME_DIR`` set correctly in its
environment — three ways to fail that have nothing to do with the compositor.
``hyprctl`` itself does exactly one thing with those arguments: it joins them
with spaces and writes them to ``<runtime>/hypr/<sig>/.socket.sock``, which is
the socket this broker already holds open for queries. So :meth:`dispatch`
sends the argv's *content* down the socket ``hyprctl`` would have used. The
plan is still the authority on what runs and in what order; only the transport
is ours.
**Read back, never assume.** Every mutation is followed by a query (PLAN §4.2).
``create`` returns what the compositor says the window's workspace and output
are, not what the rule asked for — a rule that did not bind is the failure mode
this exists to catch, and a record that repeated our intention back to us would
hide it.
**Degrade, never guess.** No compositor means :meth:`available` is false and
every lifecycle verb carries on without one: a container of ``state:
"degraded"``, with every field it could not verify left ``None``. Nothing here
ever invents an output name, a workspace number or a window.
"""
from __future__ import annotations
import logging
from dataclasses import dataclass
from pathlib import Path
from typing import Any
from . import containers
from .ipc import Client, CompositorUnavailable, HyprlandIPC
log = logging.getLogger("hhstreamd.container_host")
#: Where a window that matched no container lands (PLAN §5.2). A special
#: workspace, so it is hidden rather than shown on whatever output is in front.
DEFAULT_QUARANTINE_WORKSPACE = "special:quarantine"
#: The container's size (CONTRACT-sessions.md §5).
DEFAULT_MODE = (1280, 720)
#: Hyprland answers a successful ``keyword``/``output`` with this, and anything
#: else with prose. Matched case-insensitively and with whitespace stripped.
OK_REPLY = "ok"
@dataclass(frozen=True)
class ContainerFacts:
"""What the compositor says about a session's window, after the fact.
Every field is ``None`` when the compositor did not say: there is no window
yet, or no workspace carries a monitor name. ``output`` is the monitor the
*window* is on, which is not necessarily the output we created — and when
the two differ, the rule did not bind and the caller must say so.
"""
workspace: int | None
output: str | None
window: dict[str, Any] | None
foreground: bool | None
class ContainerHost:
"""One compositor instance, and the containers this broker owns in it."""
def __init__(
self,
runtime_dir: Path | str | None,
*,
allocator: containers.WorkspaceAllocator,
signature: str | None = None,
mode: tuple[int, int] = DEFAULT_MODE,
quarantine_workspace: str = DEFAULT_QUARANTINE_WORKSPACE,
ipc: HyprlandIPC | None = None,
) -> None:
self.runtime_dir = None if runtime_dir is None else Path(runtime_dir)
self.allocator = allocator
self.mode = mode
self.quarantine_workspace = quarantine_workspace
self._wanted_signature = signature
self._ipc = ipc
self._signature: str | None = signature
self._last_error: str | None = None
if ipc is not None:
self._signature = signature or _signature_of(ipc)
# -- the connection ---------------------------------------------------
def ipc(self) -> HyprlandIPC:
"""The client for this instance, discovering it if we have none.
Rediscovery is a ``stat`` and is attempted on every call that needs the
compositor, so a compositor that comes back is picked up without a
broker restart. The signature, once known, is reused: a second
instance appearing must not silently move the broker's containers to a
different desktop.
"""
if self._ipc is not None:
return self._ipc
if self.runtime_dir is None:
raise CompositorUnavailable(
"no compositor runtime directory is configured; containers are disabled"
)
client = HyprlandIPC.discover(self.runtime_dir, self._wanted_signature or self._signature)
self._ipc = client
self._signature = _signature_of(client)
self._last_error = None
log.info("compositor instance %s at %s", self._signature, client.request_socket)
return client
@property
def signature(self) -> str | None:
"""The instance signature, or ``None`` if we never reached one."""
return self._signature
@property
def last_error(self) -> str | None:
return self._last_error
def available(self) -> bool:
"""True if the compositor answered just now. Never cached as true.
``version`` is the cheapest round trip that proves the socket is a live
compositor and not a leftover inode.
"""
try:
self.ipc().version()
except CompositorUnavailable as exc:
self._degrade(exc)
return False
return True
def _degrade(self, exc: CompositorUnavailable) -> None:
self._last_error = str(exc)
# Drop the client: its socket path may be stale, and the next call
# should rediscover rather than keep failing against a dead instance.
self._ipc = None
# -- running plans ----------------------------------------------------
def dispatch(self, argv: list[str]) -> str:
"""Run one ``["hyprctl", ...]`` argv over the request socket.
The reply is checked: Hyprland answers ``ok`` to a command it carried
out and prose to one it refused, and an unchecked dispatch is how a
container ends up recorded as created when the compositor declined.
"""
if not argv or argv[0] != "hyprctl":
raise ValueError(f"not a hyprctl plan entry: {argv!r}")
command = " ".join(argv[1:])
reply = self.ipc().query(command).strip()
if reply.lower() != OK_REPLY and reply != "":
raise CompositorUnavailable(f"compositor refused {command!r}: {reply[:200]!r}")
return reply
def run_plan(self, plan: list[list[str]]) -> None:
"""Run argv lists in the order given. Stops at the first refusal."""
for argv in plan:
self.dispatch(argv)
def install_quarantine(self) -> bool:
"""Install the catch-all backstop. Returns False when it is disabled.
**Called once at broker start-up, before any session's container
exists.** Hyprland applies window rules in the order they were
declared and this one matches every class, so installing it after a
per-session rule would override that rule and sweep the session's own
window into the special workspace. The ordering cannot live in
:mod:`hhstreamd.containers`, which runs nothing; it lives here, in the
one caller that could get it wrong.
"""
argv = containers.quarantine_argv(self.quarantine_workspace)
if argv is None:
log.info("the quarantine backstop is disabled; unmatched windows stay where they land")
return False
self.run_plan(argv)
return True
# -- containers -------------------------------------------------------
def create(self, session_id: str, app_id: str) -> containers.ContainerPlan:
"""Allocate a slot and build the session's container.
The slot is released again if the compositor refuses part way through,
because a half-built container must not also leak a workspace number.
Whatever *was* created is left for :meth:`remove` and for the start-up
scan: deleting an output while the compositor is misbehaving is how one
failure becomes two.
"""
workspace = self.allocator.allocate()
plan = containers.container_plan(
session_id, workspace, self.mode[0], self.mode[1], app_id
)
try:
self.run_plan(plan.create)
except (CompositorUnavailable, ValueError):
self.allocator.release(workspace)
raise
return plan
def remove(self, output: str) -> None:
"""Remove one output of ours. Refuses a name we could not have made."""
if not containers.contains_output(output):
raise ValueError(
f"refusing to remove output {output!r}: not one this broker creates"
)
self.dispatch(["hyprctl", "output", "remove", output])
def release(self, workspace: int | None) -> None:
"""Give a workspace slot back, tolerating one we never held.
Unlike the allocator's own ``release``, this is called from teardown
paths that also run for sessions started before the broker restarted,
or in degraded mode, where there is no slot to return. Losing a slot
is a leak; raising here would abort a teardown that has already killed
the application.
"""
if workspace is None:
return
try:
self.allocator.release(workspace)
except KeyError:
log.debug("workspace %s was not held by this allocator", workspace)
def reserve(self, workspaces: list[int]) -> list[int]:
"""Re-take slots a previous broker handed out. Returns what was taken.
The allocator's frozen interface (CONTRACT-sessions.md §3.2) has
``allocate``, ``release`` and ``in_use`` and no way to say "this one is
already mine", which adoption needs: the records restored at start-up
name workspaces that must not be handed to a new session. Allocating
from the bottom until each wanted slot has come up, then giving back
the ones we did not want, reserves them through the interface that
exists. The band is a few entries wide, so the cost is nothing; the
alternative is a second free list beside the allocator's, which is the
drift the allocator exists to prevent.
"""
wanted = {w for w in workspaces if isinstance(w, int) and not isinstance(w, bool)}
if not wanted:
return []
# Slots this allocator already holds are already reserved. Without
# this, a second reconcile walks the band looking for a number it has
# itself taken, exhausts it, and reports the band full.
taken: list[int] = sorted(wanted & set(self.allocator.in_use()))
wanted -= set(taken)
if not wanted:
return taken
spare: list[int] = []
while wanted - set(taken):
try:
slot = self.allocator.allocate()
except containers.NoSlots:
missing = sorted(wanted - set(taken))
log.error(
"cannot reserve adopted workspaces %s: the band is full; a new "
"session could be given one of them",
missing,
)
break
(taken if slot in wanted else spare).append(slot)
for slot in spare:
self.allocator.release(slot)
return sorted(taken)
# -- reading back -----------------------------------------------------
def read_back(self, app_id: str, pid: int | None = None) -> ContainerFacts | None:
"""What the compositor says about this session's window, or ``None``.
``None`` means no window has appeared yet, which is not a failure: an
application takes time to map one, and the caller polls. A window is
matched by its ``initial_class`` — the stamp the rule also matches —
and failing that by pid, so a session whose toolkit ignored the stamp
is still *observed*, even though its rule will not have bound.
"""
client = self._find(app_id, pid)
if client is None:
return None
workspace_monitor = {w.id: w.monitor for w in self.ipc().workspaces()}
output = workspace_monitor.get(client.workspace_id) if client.workspace_id else None
foreground: bool | None = None
if output is not None:
for monitor in self.ipc().monitors():
if monitor.name == output:
# "Foreground" is the monitor-active-workspace join, not
# the client's own `visible` flag: it answers "is anything
# — a human, the frame server — actually looking at this",
# which a mapped window on a hidden workspace is not.
foreground = monitor.active_workspace_id == client.workspace_id
break
return ContainerFacts(
workspace=client.workspace_id,
output=output,
window={
"stable_id": client.stable_id,
"address": client.address,
"class": client.class_,
"initial_class": client.initial_class,
"title": client.title,
"pid": client.pid,
},
foreground=foreground,
)
def _find(self, app_id: str, pid: int | None) -> Client | None:
by_pid: Client | None = None
for client in self.ipc().clients():
if client.initial_class == app_id:
return client
if pid is not None and pid > 0 and client.pid == pid:
by_pid = client
return by_pid
def survivors(self, app_id: str, output: str | None) -> list[dict[str, Any]]:
"""Windows of ours the compositor still has after a teardown.
Either identity counts: a window still carrying the session's class, or
any window still sitting on the output we were about to remove. Both
mean the teardown did not finish, and the caller reports them instead
of claiming success (PLAN §4.5).
"""
on_output: set[int] = set()
if output is not None:
on_output = {
workspace.id
for workspace in self.ipc().workspaces()
if workspace.monitor == output
}
found = []
for client in self.ipc().clients():
if client.initial_class == app_id or (
client.workspace_id is not None and client.workspace_id in on_output
):
found.append(
{
"address": client.address,
"pid": client.pid,
"class": client.class_,
"initial_class": client.initial_class,
"workspace": client.workspace_id,
}
)
return found
def our_outputs(self) -> list[str]:
"""Live outputs whose names this broker could have created.
:func:`hhstreamd.containers.contains_output` is the whole filter, and
it is the only thing standing between the start-up scan and somebody
else's monitor. A name it rejects is never returned, so it can never
be removed.
"""
return sorted(m.name for m in self.ipc().monitors() if containers.contains_output(m.name))
def _signature_of(client: HyprlandIPC) -> str | None:
"""The instance signature, read back off the socket path we connected to.
``HyprlandIPC.discover`` resolves the signature (from the argument, the
environment, or the single instance directory) but does not report which
one it chose, and the record has to carry it so a restarted broker
re-attaches to the same instance. The socket lives at
``<runtime>/hypr/<signature>/.socket.sock``, so its parent directory is the
answer.
"""
parent = client.request_socket.parent
return parent.name or None