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
This commit is contained in:
1 parent
20b2aee109
commit
129430bffd
20 files changed
+4805
-89
No files matched your search
@@ -0,0 +1,395 @@
|
||||
"""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
|
||||
Reference in new issue
Block a user