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:
HermenixandClaude Opus 5 committed 2026-10-02 19:47:33 +00:00
1 parent 20b2aee109
commit 129430bffd
20 files changed
+4805 -89

No files matched your search

+395
View File
@@ -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
+27 -27
View File
@@ -173,44 +173,44 @@ def container_plan(
)
def quarantine_plan(quarantine_workspace: str) -> ContainerPlan | None:
def quarantine_argv(quarantine_workspace: str) -> list[list[str]] | None:
"""The backstop rule: a window that matched no container goes here.
Without it, a window with an unexpected class — a dialog spawned by a
helper process, a toolkit that rewrites its class — lands on whatever
workspace is in front, which is the leak containers exist to prevent. The
rule matches every class and is therefore emitted *before* the per-session
rules, which are anchored and more specific.
workspace is in front, which is the leak containers exist to prevent.
``quarantine_workspace`` is a workspace *name* (``special:quarantine``), not
a slot out of the allocator's band, so the returned plan carries no output
and no mode: it is a rule, not a container. An empty or blank name means
the operator turned the backstop off, and the answer is ``None`` rather than
a plan with an empty command list — a caller that gets a plan should always
have something to run.
**Install it before any per-session rule.** Hyprland evaluates window
rules in the order the keywords were issued and this one matches every
class, so a quarantine rule issued *after* a session's anchored rule
overrides it and every window in the system ends up in the special
workspace — containers included. The ordering cannot be enforced from
here, because this module never runs anything; the broker installs it once
at start-up, before the first ``container_plan`` is executed, and
:mod:`hhstreamd.container_host` says so at the call site.
``quarantine_workspace`` is a workspace *name* (``special:quarantine``),
not a slot out of the allocator's band — which is why this returns bare
argv and not a :class:`ContainerPlan` (CONTRACT-sessions.md v2 §3.2): a
quarantine rule has no output, no numbered workspace and no mode, and
``container_plan`` refuses the zero size one would have to invent. An
empty or blank name is how "disabled" is spelled, and the answer is
``None`` rather than an empty list — a caller that gets commands should
always have something to run.
"""
target = quarantine_workspace.strip()
if not target:
return None
_checked_rule_value(target, "quarantine_workspace")
return ContainerPlan(
output="",
workspace=0,
mode=(0, 0),
create=[
[
"hyprctl",
"keyword",
"windowrule",
f"match:initial_class .*, workspace {target}",
]
],
# A keyword rule cannot be unset one at a time, and this one is not
# per-session anyway: it is installed once at start-up and goes away
# with the compositor.
teardown=[],
)
return [
[
"hyprctl",
"keyword",
"windowrule",
f"match:initial_class .*, workspace {target}",
]
]
class WorkspaceAllocator:
+210
View File
@@ -0,0 +1,210 @@
"""The broker's end of the private driver socket (CONTRACT-sessions.md §3.4).
The pointer driver is a separate process because a Wayland client needs its own
connection; this module is the five-verb client that talks to it. It is the
only place in the broker that knows the driver's wire format, so the driver and
the broker can be read against each other in two files.
**It holds no lease state and asks for none.** The driver is an executor: it
will warp anywhere it is told, and the only thing that stops two sessions
fighting over the one cursor is the lease in :mod:`hhstreamd.manager`. Putting
even a session id in a request here would suggest otherwise, so none of these
methods takes one.
**Blocking, with a short timeout, and deliberately synchronous.** The driver
is local, the requests are one small line each, and the broker is the only
peer. An async client would buy nothing but a way to interleave two warps.
The caller runs it off the event loop (``asyncio.to_thread``) so a wedged
driver cannot stall session lifecycle — which is the whole reason the driver is
a separate process — and the lock below makes that safe: one request on the
wire at a time, whatever thread asks.
**One connection, checked before every use, never retried after one.** The
driver's server handles one connection at a time and reads lines from it until
EOF, so a connection per request would work but would churn the accept loop.
A held connection can die under us when the driver restarts, so it is tested
for EOF before each write and silently replaced — but a request that *was*
written and then went unanswered is never sent again, because a repeated
``button down`` is a click the agent did not ask for. Every failure is
:class:`DriverUnavailable` — never a guess, and never a silent no-op, because a
dropped ``release_all`` leaves a mouse button down.
"""
from __future__ import annotations
import json
import logging
import select
import socket
import threading
from pathlib import Path
from typing import Any
log = logging.getLogger("hhstreamd.driver")
#: The driver answers from memory; it does not render, wait for a frame
#: callback or ask the compositor anything. This only bounds a driver that has
#: stopped answering at all.
DEFAULT_TIMEOUT_S = 2.0
#: Matches the driver's own ceiling (``hhstream_pointer.server``).
MAX_LINE_BYTES = 1 << 20
class DriverUnavailable(Exception):
"""The driver could not be reached, or did not answer intelligibly.
Distinct from :class:`DriverRejected`: this one means the cursor's state is
now unknown, so the broker drops the lease rather than carrying on.
"""
class DriverRejected(Exception):
"""The driver understood the request and refused it (``ok: false``)."""
class PointerDriver:
"""A client for one driver socket. Thread-safe; one request at a time."""
def __init__(self, socket_path: Path | str, *, timeout_s: float = DEFAULT_TIMEOUT_S) -> None:
self.socket_path = Path(socket_path)
self.timeout_s = float(timeout_s)
self._lock = threading.Lock()
self._sock: socket.socket | None = None
self._stream = None
# -- the five verbs ---------------------------------------------------
def warp(self, output: str, x: float, y: float) -> None:
"""Aim at ``x``/``y``, each 0..1 in ``output``'s own frame."""
self.request({"op": "warp", "output": output, "x": float(x), "y": float(y)})
def button(self, button: str, state: str) -> None:
self.request({"op": "button", "button": button, "state": state})
def frame(self) -> None:
"""Commit what was queued. Nothing the driver was sent is delivered
to the compositor until this, so every gesture ends with one."""
self.request({"op": "frame"})
def pressed(self) -> list[str]:
"""What the *driver* believes is down.
The lease keeps its own set, and this is the one that matters when the
two disagree: the driver's is the one the compositor saw.
"""
reply = self.request({"op": "pressed"})
return _string_list(reply.get("buttons"), "pressed")
def release_all(self) -> list[str]:
"""Lift everything, returning what came up. Called on expiry."""
reply = self.request({"op": "release_all"})
return _string_list(reply.get("lifted"), "release_all")
# -- plumbing ---------------------------------------------------------
def request(self, message: dict[str, Any]) -> dict[str, Any]:
"""One request, one reply. Raises rather than returning a guess."""
with self._lock:
try:
return self._exchange(message)
except (OSError, ValueError) as exc:
# The connection is now of unknown state — a half-written
# request, a partial reply — so it is dropped rather than
# reused for the next verb.
self._disconnect()
raise DriverUnavailable(
f"pointer driver {self.socket_path}: {exc}"
) from exc
def close(self) -> None:
with self._lock:
self._disconnect()
def _exchange(self, message: dict[str, Any]) -> dict[str, Any]:
stream = self._connect()
line = json.dumps(message, separators=(",", ":")).encode("ascii") + b"\n"
stream.write(line)
stream.flush()
reply_line = stream.readline(MAX_LINE_BYTES + 1)
if not reply_line:
# The driver went away between the write and the reply, so whether
# it carried the request out is unknowable. **Not retried**: a
# repeated ``button down`` is a second press the agent never asked
# for, and the broker's answer to an unknown cursor is to drop the
# lease, not to guess again.
raise OSError("the driver closed the connection without answering")
if len(reply_line) > MAX_LINE_BYTES:
raise ValueError("reply exceeds the frame limit")
reply = json.loads(reply_line)
if not isinstance(reply, dict):
raise ValueError(f"reply is not an object: {type(reply).__name__}")
if not reply.get("ok"):
raise DriverRejected(str(reply.get("error") or "the driver refused the request"))
return reply
def _connect(self):
if self._stream is not None and not self._stale():
return self._stream
self._disconnect()
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
try:
sock.settimeout(self.timeout_s)
sock.connect(str(self.socket_path))
except OSError:
sock.close()
raise
self._sock = sock
self._stream = sock.makefile("rwb")
log.debug("connected to the pointer driver at %s", self.socket_path)
return self._stream
def _stale(self) -> bool:
"""True if the held connection has died since the last verb.
The driver never speaks unsolicited, so a readable socket can only be
at EOF — the driver restarted, or was stopped. Checking costs one
non-blocking ``select`` and is what makes reconnecting safe: the
request is written only to a connection that was alive when it was
written, so there is never a question of whether a retry would repeat
a click.
"""
sock = self._sock
if sock is None:
return True
try:
readable, _, _ = select.select([sock], [], [], 0)
except (OSError, ValueError):
return True
return bool(readable)
def _disconnect(self) -> None:
stream, self._stream = self._stream, None
sock, self._sock = self._sock, None
for closeable in (stream, sock):
if closeable is None:
continue
try:
closeable.close()
except OSError:
pass
def _string_list(value: Any, what: str) -> list[str]:
"""A list of button names, or a malformed reply — never a silent ``[]``.
An empty list is a real answer ("nothing was down"); anything that is not a
list of strings means the broker and the driver disagree about the
protocol, and treating that as "nothing was down" is how a button stays
pressed forever.
"""
if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
raise DriverUnavailable(f"{what}: expected a list of button names, got {value!r}")
return list(value)
+38 -3
View File
@@ -32,6 +32,18 @@ environment at spawn. Without that option the old inherited-environment
behaviour stands, and the daemon warns at startup that applications may not
reach a compositor.
**The container stamp.** A session's window rule matches ``initial_class
^hh-<id>$``, so the application has to report that class or the rule binds to
nothing and the window lands outside its container. The only lever this module
has is the environment (:data:`APP_ID_ENV`), because the alternative — a
per-app ``--app-id``/``--class`` flag — would have to come from the allowlist,
and the allowlist is not this slice's file. The variables below are the ones
that are actually read by something: SDL's two, X11's ``RESOURCE_NAME`` (which
XWayland clients surface as ``WM_CLASS``), and ``HHSTREAM_APP_ID`` for a
wrapper script that knows what to do with it. **A GTK or Qt application
ignores all of them**, which is a real limit and is reported as one: the
read-back after launch is what tells the broker the rule did not bind.
The app runs as **the same unprivileged user as the daemon** and inherits the
real home directory. M0 invents no service account and forces no throwaway
``HOME``; ``--home`` pins a different one and ``--ephemeral-home`` opts in to a
@@ -52,6 +64,19 @@ from .registry import Session
log = logging.getLogger("hhstreamd.launcher")
#: The variables that carry the container stamp, each read by something real:
#: SDL sets the surface's app id from its two, Xlib's ``XSetClassHint`` falls
#: back to ``RESOURCE_NAME`` for an XWayland client's ``WM_CLASS``, and
#: ``HHSTREAM_APP_ID`` is the broker's own name for it. A toolkit that reads
#: none of them (GTK, Qt) keeps its own class and its window rule will not
#: bind; that is visible in the read-back, not papered over here.
APP_ID_ENV = (
"HHSTREAM_APP_ID",
"SDL_VIDEO_WAYLAND_WMCLASS",
"SDL_VIDEO_X11_WMCLASS",
"RESOURCE_NAME",
)
#: Environment variables the daemon's own plumbing must not leak into an app.
_STRIPPED = (
"HHSTREAM_SOCKET",
@@ -104,7 +129,7 @@ class Launcher:
# ---- environment -------------------------------------------------
def build_env(self, session_id: str, home: Path) -> dict[str, str]:
def build_env(self, session_id: str, home: Path, app_id: str | None = None) -> dict[str, str]:
"""The app's environment.
It inherits the daemon's, minus the daemon's own configuration, plus a
@@ -133,6 +158,9 @@ class Launcher:
env["HHSTREAM_SESSION_ID"] = session_id
if self.compositor is not None:
env.update(self.compositor.env())
if app_id:
for name in APP_ID_ENV:
env[name] = app_id
return env
def resolve_home(self, session_id: str, home: str | None, ephemeral: bool) -> tuple[Path, bool]:
@@ -184,8 +212,15 @@ class Launcher:
*,
home: str | None = None,
ephemeral_home: bool = False,
app_id: str | None = None,
) -> Spawned:
"""Start the application. Raises ``OSError`` if it cannot be executed."""
"""Start the application. Raises ``OSError`` if it cannot be executed.
``app_id`` is the container stamp: the class the session's window rule
matches on. It reaches the application through the environment only
(see :data:`APP_ID_ENV` and the module docstring), so passing it is a
request, not a guarantee.
"""
if not argv:
raise ValueError("argv is empty")
@@ -196,7 +231,7 @@ class Launcher:
raise ValueError(f"argv[0] must be an absolute path, got {argv[0]!r}")
home_path, is_ephemeral = self.resolve_home(session_id, home, ephemeral_home)
env = self.build_env(session_id, home_path)
env = self.build_env(session_id, home_path, app_id)
log_file = self.log_path(session_id)
log_file.parent.mkdir(parents=True, exist_ok=True, mode=0o750)
+1105 -22
View File
File diff suppressed because it is too large. Load diff
+114
View File
@@ -9,6 +9,7 @@ rest of ``hhstreamd``.
from __future__ import annotations
import collections
import enum
import json
from typing import Any
@@ -48,6 +49,14 @@ class ExitCode(enum.IntEnum):
POLICY = 6
TIMEOUT = 7
BUSY = 8
#: The verb needs the pointer lease and this session does not hold it.
#: Distinct from BUSY, which is "someone else holds it": an agent that
#: sees 9 must acquire, one that sees 8 must wait.
NO_LEASE = 9
#: An IPC or output operation failed. **The session is not lost** — it
#: keeps running in degraded mode — so this must never be confused with a
#: session failure, which is what a shared code would do.
COMPOSITOR = 10
#: Machine-readable error names, grouped by the exit code they map to. Every
@@ -80,6 +89,9 @@ EXIT_CODE_FOR_ERROR: dict[str, ExitCode] = {
"not_allowlisted": ExitCode.POLICY,
"argument_refused": ExitCode.POLICY,
"session_cap_reached": ExitCode.POLICY,
# The workspace band is full. A policy refusal and not a compositor
# failure: the compositor is fine, the broker is at its budget.
"container_budget": ExitCode.POLICY,
"refused": ExitCode.POLICY,
# 7 — timed out
"timeout": ExitCode.TIMEOUT,
@@ -87,6 +99,15 @@ EXIT_CODE_FOR_ERROR: dict[str, ExitCode] = {
# 8 — busy
"busy": ExitCode.BUSY,
"already_managed": ExitCode.BUSY,
"pointer_busy": ExitCode.BUSY,
# 9 — the lease is required and not held
"no_lease": ExitCode.NO_LEASE,
# 10 — the compositor side failed; the session itself is fine
"compositor": ExitCode.COMPOSITOR,
"compositor_unavailable": ExitCode.COMPOSITOR,
"no_container": ExitCode.COMPOSITOR,
"driver_unavailable": ExitCode.COMPOSITOR,
"driver_refused": ExitCode.COMPOSITOR,
}
@@ -103,6 +124,99 @@ def exit_code_for(error: str | None) -> ExitCode:
return EXIT_CODE_FOR_ERROR.get(error, ExitCode.BAD_STATE)
# --------------------------------------------------------------------------
# Verbs and `request_id` idempotency (PLAN §8)
# --------------------------------------------------------------------------
#: Every verb the daemon answers. The container and pointer verbs are dotted
#: and the original eight are not, because the original eight are frozen
#: (CONTRACT-sessions.md §4: "existing verbs are unchanged") and renaming them
#: would break every agent for a cosmetic gain.
VERBS = (
"ping",
"start",
"list",
"status",
"touch",
"kill",
"gc",
"adopt",
"logs",
"container.list",
"container.reconcile",
"pointer.acquire",
"pointer.move",
"pointer.button",
"pointer.click",
"pointer.release",
"pointer.state",
)
#: Verbs whose reply is remembered by ``request_id``, so a caller that died
#: before reading the reply can retry without the mutation happening twice.
#:
#: The read verbs are absent deliberately: they are idempotent already, so a
#: retry costs nothing, and a cached ``list`` would be a stale one. Every
#: ``pointer.*`` verb that moves something is here, because a retried click is
#: a second click — the one failure an agent cannot undo.
MUTATING_VERBS = frozenset(
{
"start",
"touch",
"kill",
"adopt",
"gc",
"container.reconcile",
"pointer.acquire",
"pointer.move",
"pointer.button",
"pointer.click",
"pointer.release",
}
)
#: How many completed replies are kept. Bounded because a client chooses the
#: ids: an unbounded cache is memory a peer controls.
DEDUP_ENTRIES = 64
class IdempotencyCache:
"""The last N mutating replies, by ``request_id``.
A retry returns *the recorded answer*, including a recorded failure: an
agent that retries a ``start`` which was refused by policy must see the
refusal again, not a second attempt that might succeed and leave it with
an application it has no id for. Replies are returned with
``deduplicated: true`` so the caller can tell a replay from a fresh answer
rather than having to infer it.
"""
def __init__(self, capacity: int = DEDUP_ENTRIES) -> None:
self.capacity = capacity
self._entries: collections.OrderedDict[str, dict[str, Any]] = collections.OrderedDict()
def lookup(self, op: str, request_id: Any) -> dict[str, Any] | None:
"""The recorded reply for this id, or ``None`` to go ahead and do it."""
if not isinstance(request_id, str) or op not in MUTATING_VERBS:
return None
recorded = self._entries.get(request_id)
if recorded is None:
return None
return {**recorded, "deduplicated": True}
def remember(self, op: str, request_id: Any, response: dict[str, Any]) -> None:
if not isinstance(request_id, str) or op not in MUTATING_VERBS:
return
self._entries[request_id] = dict(response)
self._entries.move_to_end(request_id)
while len(self._entries) > self.capacity:
self._entries.popitem(last=False)
def __len__(self) -> int:
return len(self._entries)
# --------------------------------------------------------------------------
# Message construction
# --------------------------------------------------------------------------
+124 -1
View File
@@ -22,7 +22,12 @@ from .clock import Clock, iso
log = logging.getLogger("hhstreamd.registry")
SCHEMA = 2
#: 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
#: Tombstones survive this long so a ``status`` after an unexplained failure
#: still answers the question. ``gc`` prunes them.
@@ -34,6 +39,28 @@ DEFAULT_TOMBSTONE_TTL_S = 3600.0
ACTIVITY_FLUSH_INTERVAL_S = 15.0
class ContainerState:
"""What the broker knows about a session's spatial container.
These are the only four answers. ``container: null`` is a fifth and
different thing — "this session has no container at all" — and nothing here
means "probably something": a field the compositor did not confirm stays
``None`` (PLAN §7).
"""
#: Created by us, and the compositor still shows the output.
OWNED = "owned"
#: No IPC, so nothing was created and nothing can be verified. The session
#: still starts, stops and is reaped by process identity (PLAN §4.4).
DEGRADED = "degraded"
#: Torn down on purpose: the output was removed and the slot released.
REMOVED = "removed"
#: The record and the compositor disagree — the output we recorded is not
#: there, or an output of ours has no live session. Never deleted on a
#: guess; reconciliation decides.
ORPHAN = "orphan"
class State:
STARTING = "starting"
READY = "ready"
@@ -102,6 +129,19 @@ class Session:
workspace: int | None = None
window: Any = None
foreground: bool | None = None
#: ``{output, workspace, mode, created_by, state}`` or ``None`` for "no
#: container". A dict rather than a nested dataclass because
#: :meth:`to_dict` is ``asdict`` and :meth:`from_dict` is ``cls(**data)``:
#: a dataclass would serialise and come back as a dict anyway, and the
#: asymmetry is where a half-migrated record would hide.
container: dict[str, Any] | None = None
#: ``{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
#: ``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.
signature: str | None = None
command_count: int = 0
exit_code: int | None = None
exit_detected_by: str | None = None
@@ -147,6 +187,7 @@ class Session:
@classmethod
def from_dict(cls, data: dict[str, Any]) -> "Session":
data = migrate(data)
known = {f for f in cls.__dataclass_fields__}
unknown = set(data) - known
if unknown:
@@ -168,6 +209,88 @@ class Session:
return data
def container_record(
*,
output: str | None,
workspace: int | None,
mode: tuple[int, int] | None,
created_by: str,
state: str,
) -> dict[str, Any]:
"""One ``container`` sub-record (PLAN §7).
Every argument is explicit and may be ``None`` because the degraded case is
the common one: there is a container *state* to report long before there is
an output to name, and the alternative — leaving the key out — would read
as "no container" when what we mean is "a container we could not verify".
"""
return {
"output": output,
"workspace": workspace,
"mode": None if mode is None else {"width": mode[0], "height": mode[1]},
"created_by": created_by,
"state": state,
}
def pointer_record(
*,
bookmark: dict[str, Any] | None,
last_released_at: str | None,
released_by: str | None,
) -> dict[str, Any]:
"""One ``pointer`` sub-record: where the cursor was left, and by what.
Written on every move and on release. A session that has one has been
aimed at; a session that has none never was.
"""
return {
"bookmark": bookmark,
"last_released_at": last_released_at,
"released_by": released_by,
}
def migrate(data: dict[str, Any]) -> dict[str, Any]:
"""Bring a record read from disk up to :data:`SCHEMA`.
A schema-2 record is **adopted, not rejected**: its application is very
likely still running, and the daemon that wrote it knew nothing of
containers, so the honest value for every field schema 3 added is ``None``
— "no container", "the pointer was never used here", "we do not know which
compositor instance this was". Each of those is a defined value, which is
the whole reason the migration can be this short.
A record from a *newer* schema is left alone and loudly logged: the fields
this daemon does not know are dropped by :meth:`Session.from_dict`, and
guessing at what a future version meant would be worse than running with
the subset we understand.
"""
schema = data.get("schema")
if schema == SCHEMA:
return data
if isinstance(schema, int) and schema > SCHEMA:
log.error(
"record %s is schema %s, newer than this daemon's %s; reading the fields "
"this version knows and leaving the rest",
data.get("id"),
schema,
SCHEMA,
)
return data
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"):
upgraded.setdefault(key, None)
upgraded["schema"] = SCHEMA
log.info("migrated record %s from schema %s to %s", data.get("id"), schema, SCHEMA)
return upgraded
def mint_id(app: str, taken: set[str], *, rng: Any = secrets) -> str:
"""``<app-slug>-<6 base32 chars>`` (DESIGN.md §2.2).
+90 -22
View File
@@ -13,7 +13,6 @@ This module is framing and dispatch only. Every decision lives in
from __future__ import annotations
import asyncio
import collections
import contextlib
import logging
import os
@@ -35,14 +34,9 @@ DEFAULT_REQUEST_TIMEOUT_S = 5.0
#: A `kill` may legitimately take `grace` seconds, so it gets its own budget.
KILL_TIMEOUT_MARGIN_S = 5.0
#: Replies to mutating verbs are remembered so a CLI that died before reading
#: the reply can retry without launching a second application.
DEDUP_ENTRIES = 64
#: Verbs whose replies are cached by `request_id`. The read verbs are absent
#: deliberately: they are idempotent, so a retry costs nothing and a cached
#: `list` would be a stale one.
MUTATING_VERBS = frozenset({"start", "touch", "kill", "adopt", "gc"})
#: `request_id` idempotency lives in `protocol` (which verbs mutate, how many
#: replies are kept, what a replay looks like) because the CLI has to agree
#: with it and the CLI imports that module and not this one.
class ControlServer:
@@ -59,7 +53,7 @@ class ControlServer:
self.request_timeout_s = request_timeout_s
self.socket_mode = socket_mode
self._server: asyncio.AbstractServer | None = None
self._dedup: collections.OrderedDict[str, dict[str, Any]] = collections.OrderedDict()
self._dedup = protocol.IdempotencyCache()
self._ops: dict[str, Callable[[dict[str, Any], dict[str, Any]], Awaitable[dict[str, Any]]]] = {
"ping": self._op_ping,
"start": self._op_start,
@@ -70,6 +64,14 @@ class ControlServer:
"gc": self._op_gc,
"adopt": self._op_adopt,
"logs": self._op_logs,
"container.list": self._op_container_list,
"container.reconcile": self._op_container_reconcile,
"pointer.acquire": self._op_pointer_acquire,
"pointer.move": self._op_pointer_move,
"pointer.button": self._op_pointer_button,
"pointer.click": self._op_pointer_click,
"pointer.release": self._op_pointer_release,
"pointer.state": self._op_pointer_state,
}
# ------------------------------------------------------------------
@@ -188,9 +190,8 @@ class ControlServer:
"unknown_op", f"unknown op {op!r}", hint=f"known: {', '.join(sorted(self._ops))}"
)
if isinstance(request_id, str) and op in MUTATING_VERBS and request_id in self._dedup:
cached = dict(self._dedup[request_id])
cached["deduplicated"] = True
cached = self._dedup.lookup(op, request_id)
if cached is not None:
return cached
timeout = self.request_timeout_s
@@ -224,8 +225,7 @@ class ControlServer:
response.setdefault("elapsed_ms", elapsed_ms)
if isinstance(request_id, str):
response["request_id"] = request_id
if op in MUTATING_VERBS:
self._remember(request_id, response)
self._dedup.remember(op, request_id, response)
self.manager.audit.emit(
"request",
@@ -239,12 +239,6 @@ class ControlServer:
)
return response
def _remember(self, request_id: str, response: dict[str, Any]) -> None:
self._dedup[request_id] = dict(response)
self._dedup.move_to_end(request_id)
while len(self._dedup) > DEDUP_ENTRIES:
self._dedup.popitem(last=False)
# ------------------------------------------------------------------
# ops
# ------------------------------------------------------------------
@@ -290,7 +284,7 @@ class ControlServer:
return protocol.ok(id=record["id"], state=record["state"], session=record)
async def _op_gc(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]:
return protocol.ok(**self.manager.gc())
return protocol.ok(**await self.manager.gc())
async def _op_adopt(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]:
record = await self.manager.adopt(
@@ -300,6 +294,80 @@ class ControlServer:
)
return protocol.ok(id=record["id"], state=record["state"], session=record)
async def _op_container_list(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(**self.manager.container_list())
async def _op_container_reconcile(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(**await self.manager.container_reconcile(request.get("id")))
async def _op_pointer_acquire(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(
**await self.manager.pointer_acquire(
request.get("id"),
ttl_s=request.get("ttl_s"),
# Restoring is the default: the bookmark exists so a gesture
# can be picked up where it was left, and a caller that wants
# the centre of the output says so.
restore=bool(request.get("restore", True)),
)
)
async def _op_pointer_move(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(
**await self.manager.pointer_move(
request.get("id"),
request.get("lease_id"),
x=request.get("x"),
y=request.get("y"),
dx=request.get("dx"),
dy=request.get("dy"),
)
)
async def _op_pointer_button(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(
**await self.manager.pointer_button(
request.get("id"),
request.get("lease_id"),
request.get("button"),
request.get("state"),
)
)
async def _op_pointer_click(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(
**await self.manager.pointer_click(
request.get("id"),
request.get("lease_id"),
request.get("button", "left"),
request.get("count", 1),
)
)
async def _op_pointer_release(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(
**await self.manager.pointer_release(request.get("id"), request.get("lease_id"))
)
async def _op_pointer_state(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(**self.manager.pointer_state())
async def _op_logs(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]:
return protocol.ok(
**self.manager.logs(