docs: the plan for workspaces and pointer input, and the frozen sessions contract
The plan is the researched design (one compositor, one output+workspace per session, serialised output-bound pointer input under a lease). The contract is the freeze point for a parallel build: file ownership per slice, the exact Python seams, the wire format, and the names and paths nobody may invent. Kept separate from docs/CONTRACT.md, which governs the frame socket and is untouched by this work.
This commit is contained in:
1 parent
7a81f9f334
commit
98374b8457
2 files changed
+962
No files matched your search
@@ -0,0 +1,300 @@
|
||||
# CONTRACT — sessions build (sessions-v1)
|
||||
|
||||
This file is the interface for the **session** work: the broker, containers,
|
||||
compositor IPC and pointer input. It is the sibling of `docs/CONTRACT.md`, which
|
||||
freezes the *frame-socket* wire format; that one is untouched by this build.
|
||||
|
||||
**Immutable without a version bump.** Every slice codes against this and nothing
|
||||
else. If something here is wrong or missing, **stop and report it in your final
|
||||
message** — the parent edits this file, not you. Do not widen your slice to work
|
||||
around a gap.
|
||||
|
||||
Version: sessions-v1 (2026-10-01).
|
||||
|
||||
---
|
||||
|
||||
## 1. What is being built, in one paragraph
|
||||
|
||||
A headless Hyprland desktop is driven by an agent. A broker (`hhstreamd`) starts
|
||||
allowlisted applications as **sessions** and tracks them. This build gives each
|
||||
session its **own output and workspace** (a spatial container), teaches the
|
||||
broker to **talk to the compositor** (IPC), and adds **serialised pointer input**
|
||||
aimed at one session, under a **lease** whose bookmark is stored with the
|
||||
session.
|
||||
|
||||
Read `docs/PLAN-workspaces-and-pointer.md` only if your brief tells you to. It
|
||||
describes the whole system; you are building one part.
|
||||
|
||||
---
|
||||
|
||||
## 2. File ownership — the rule that makes four sessions possible
|
||||
|
||||
| Slice | Owns (only these) |
|
||||
| --- | --- |
|
||||
| **A — stage0-rename** | `nix/module.nix`, `src/hhstream/cli.py` (the two socket-path defaults only), `examples/agent-eyes` |
|
||||
| **B — ipc-client** | `src/hhstreamd/ipc.py`, `tests/ipc/**` |
|
||||
| **C — containers** | `src/hhstreamd/containers.py`, `tests/containers/**` |
|
||||
| **D — pointer** | `src/hhstreamd/pointer.py`, `src/hhstream_pointer/**`, `tests/pointer/**`, `pyproject.toml`, `nix/package.nix` |
|
||||
| **parent (integration)** | `src/hhstreamd/{protocol,registry,manager,launcher,compositor,procmon}.py`, `checks/**`, `docs/**`, `src/hhstream/cli.py` (everything but the path defaults), `nix/module.nix` (after A merges) |
|
||||
|
||||
Two slices never edit the same file. A shared-file change you believe you need is
|
||||
a **report**, not an edit.
|
||||
|
||||
**Never touch:** `/etc/nixos` (outside this repo), anything under
|
||||
`/var/lib/hermes/nixos`, any systemd unit, any running service. Never run
|
||||
`nixos-rebuild`, `nixosTest`, `nix build .#checks.*`, or launch a GUI
|
||||
application. The parent serialises all of that on a 2-core machine.
|
||||
|
||||
---
|
||||
|
||||
## 3. Python seams (exact signatures — code to these)
|
||||
|
||||
### 3.1 `hhstreamd/ipc.py` (B)
|
||||
|
||||
```python
|
||||
class CompositorUnavailable(Exception):
|
||||
"""No request socket, or the compositor refused. Callers degrade, never guess."""
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Monitor:
|
||||
name: str; x: int; y: int; width: int; height: int; scale: float
|
||||
active_workspace_id: int | None
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Workspace:
|
||||
id: int; name: str; monitor: str | None; windows: int; is_special: bool
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Client:
|
||||
address: str; pid: int; workspace_id: int | None; monitor: str | None
|
||||
class_: str; initial_class: str; title: str; stable_id: str; visible: bool
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class CursorPos:
|
||||
x: int; y: int
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Event:
|
||||
name: str # "openwindow", "workspace", "monitorremoved", ...
|
||||
data: dict # parsed payload; keys are whatever the event carried
|
||||
|
||||
class HyprlandIPC:
|
||||
@classmethod
|
||||
def discover(cls, runtime_dir: Path, signature: str | None = None) -> "HyprlandIPC": ...
|
||||
# raises CompositorUnavailable. Signature from the argument, else
|
||||
# $HYPRLAND_INSTANCE_SIGNATURE, else the single directory under
|
||||
# <runtime_dir>/hypr/. More than one and no signature = CompositorUnavailable.
|
||||
|
||||
def __init__(self, request_socket: Path, event_socket: Path | None = None) -> None: ...
|
||||
|
||||
def version(self) -> str: ...
|
||||
def monitors(self) -> list[Monitor]: ...
|
||||
def workspaces(self) -> list[Workspace]: ...
|
||||
def clients(self) -> list[Client]: ...
|
||||
def cursorpos(self) -> CursorPos: ...
|
||||
def query(self, command: str) -> str: ... # raw request socket, for anything not wrapped
|
||||
def events(self) -> Iterator[Event]: ... # blocking; raises CompositorUnavailable on EOF
|
||||
def close(self) -> None: ...
|
||||
|
||||
def parse_event(line: str) -> Event: ... # "name>>a,b,c" -> Event
|
||||
```
|
||||
|
||||
Rules: every method raises `CompositorUnavailable` rather than returning a
|
||||
guess. `clients()` parses `clients -j`; `monitors()` parses `monitors -j`;
|
||||
`workspaces()` parses `workspaces -j`. Stdlib only.
|
||||
|
||||
### 3.2 `hhstreamd/containers.py` (C)
|
||||
|
||||
**Pure logic. No I/O, no subprocess, no socket, no import of `ipc.py`.** It
|
||||
computes command lines and parses nothing. Seams are primitives so this module
|
||||
stands alone.
|
||||
|
||||
```python
|
||||
@dataclass(frozen=True)
|
||||
class ContainerPlan:
|
||||
output: str # hh-<session-id>
|
||||
workspace: int
|
||||
mode: tuple[int, int] # width, height
|
||||
create: list[list[str]] # full argv lists, in order, each ["hyprctl", ...]
|
||||
teardown: list[list[str]]
|
||||
|
||||
def output_name(session_id: str) -> str: ...
|
||||
# "hh-" + session_id. Ids are already [a-z0-9-]; assert and raise ValueError otherwise.
|
||||
|
||||
def contains_output(name: str) -> bool: ...
|
||||
# True for names this broker creates (prefix "hh-"), so a start-up scan can
|
||||
# find orphans.
|
||||
|
||||
def container_plan(session_id: str, workspace: int, width: int, height: int,
|
||||
app_id: str) -> ContainerPlan: ...
|
||||
# create: output create headless <name> ["hyprctl","output","create","headless",name]
|
||||
# workspace rule ["hyprctl","keyword","workspace",
|
||||
# f"{workspace}, monitor:{name}, default:true, persistent:true"]
|
||||
# window rule ["hyprctl","keyword","windowrule",
|
||||
# f"match:initial_class ^{app_id}$, workspace {workspace}, monitor {name}"]
|
||||
# output mode ["hyprctl","keyword","monitor", f"{name},{width}x{height},auto,1"]
|
||||
# teardown: output remove <name> ["hyprctl","output","remove",name]
|
||||
|
||||
def app_id_for(session_id: str) -> str: ...
|
||||
# the bare "hh-<session-id>" the launcher sets on the app; "^hh-<session-id>$"
|
||||
# is built in container_plan.
|
||||
|
||||
def quarantine_plan(quarantine_workspace: str) -> ContainerPlan | None: ...
|
||||
# the backstop: every window matching no container goes to
|
||||
# special:quarantine. Returns the keyword argv, or None if disabled.
|
||||
|
||||
class WorkspaceAllocator:
|
||||
def __init__(self, base: int, count: int) -> None: ...
|
||||
def allocate(self) -> int: ... # lowest free slot in [base, base+count); raises NoSlots
|
||||
def release(self, workspace: int) -> None: ... # unknown id -> KeyError (a bug, not a no-op)
|
||||
def in_use(self) -> list[int]: ...
|
||||
|
||||
class NoSlots(Exception): ...
|
||||
```
|
||||
|
||||
### 3.3 `hhstreamd/pointer.py` (D)
|
||||
|
||||
Lease state machine + coordinate maths. **No Wayland, no socket, no I/O.** The
|
||||
clock is injected so expiry is testable without sleeping.
|
||||
|
||||
```python
|
||||
class LeaseBusy(Exception): # another session holds it
|
||||
def __init__(self, holder: str) -> None: ...
|
||||
class LeaseInvalid(Exception): # not held, or held by someone else / stale lease_id
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Bookmark:
|
||||
x: float; y: float # 0..1, output-local, normalised
|
||||
output: str
|
||||
at: str # ISO-8601 UTC
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class LeaseInfo:
|
||||
session_id: str; lease_id: str; acquired_at: float; expires_at: float
|
||||
hard_deadline: float
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class LeaseOutcome:
|
||||
bookmark: Bookmark | None; reason: str; buttons_lifted: list[str]
|
||||
|
||||
class PointerLease:
|
||||
def __init__(self, ttl_s: float = 30.0, max_s: float = 300.0,
|
||||
clock: Callable[[], float] = time.monotonic) -> None: ...
|
||||
def acquire(self, session_id: str) -> str: ... # -> lease_id; raises LeaseBusy
|
||||
def refresh(self, session_id: str, lease_id: str) -> None: ... # raises LeaseInvalid
|
||||
def release(self, session_id: str, lease_id: str, reason: str) -> LeaseOutcome: ...
|
||||
def state(self) -> dict: ... # {"holder": str|None, "since": float|None,
|
||||
# "lease_id": str|None, "expires_at": float|None}
|
||||
def expire(self) -> LeaseInfo | None: ...
|
||||
# force-release if past ttl or hard cap; returns what was released.
|
||||
# The caller (broker) lifts buttons on the driver side.
|
||||
def press(self, session_id: str, button: str) -> None: ...
|
||||
def unpress(self, session_id: str, button: str) -> list[str]: ...
|
||||
def pressed(self) -> list[str]: ...
|
||||
|
||||
def window_to_absolute(point: tuple[int, int], window: tuple[int, int, int, int],
|
||||
monitor: tuple[int, int, int, int]) -> tuple[float, float]:
|
||||
# point is window-local pixels; window is (x, y, w, h) global; monitor is
|
||||
# (x, y, w, h) global. Returns normalised 0..1 in the MONITOR's frame,
|
||||
# clamped to [0, 1]. Raises ValueError if the point is outside the window.
|
||||
```
|
||||
|
||||
### 3.4 `src/hhstream_pointer/**` (D) — the driver process
|
||||
|
||||
A separate process, because a Wayland client needs its own connection and a
|
||||
blocked driver must not stall the broker.
|
||||
|
||||
- Entry point `hhstream-pointer` (add to `pyproject.toml`:
|
||||
`hhstream-pointer = "hhstream_pointer.__main__:main"`).
|
||||
- Command line the module will pass, exactly:
|
||||
`hhstream-pointer --socket /run/hhstream/pointer.sock --compositor-runtime-dir /run/hypr-stream`
|
||||
- Uses **pywayland** (packaged as `python3Packages.pywayland`) and the **wlr
|
||||
virtual pointer XML** from `pkgs.wlr-protocols`
|
||||
(`share/wayland-protocols/wlr-unstable/zwlr-virtual-pointer-unstable-v1.xml`).
|
||||
Compile the protocol at build time or vendor the generated module under your
|
||||
directory — your choice, stated in your report. `pyproject.toml` and
|
||||
`nix/package.nix` are yours precisely so this is possible.
|
||||
- Binds `zwlr_virtual_pointer_manager_v1` **version 2** and uses
|
||||
`create_virtual_pointer_with_output(seat, output, id)` so coordinates are
|
||||
output-local. If only version 1 is offered, **report it — never silently fall
|
||||
back** to a global pointer, which would break aiming.
|
||||
- Private socket protocol with the broker, newline-delimited JSON:
|
||||
|
||||
```json
|
||||
{"op": "warp", "output": "hh-x", "x": 0.42, "y": 0.61} -> {"ok": true}
|
||||
{"op": "button", "button": "left", "state": "down"} -> {"ok": true}
|
||||
{"op": "frame"} -> {"ok": true}
|
||||
{"op": "pressed"} -> {"ok": true, "buttons": ["left"]}
|
||||
{"op": "release_all"} -> {"ok": true, "lifted": ["left"]}
|
||||
```
|
||||
|
||||
`{"ok": false, "error": "<text>"}` for anything rejected. The driver holds **no
|
||||
lease state** — the broker owns the lease; the driver is an executor that must
|
||||
never be trusted to serialise anything.
|
||||
|
||||
---
|
||||
|
||||
## 4. Wire format (broker control socket) — B, C and D do not implement this
|
||||
|
||||
Newline-delimited JSON over `/run/hhstream/control.sock`. Existing verbs are
|
||||
unchanged. New verbs (integration implements; listed so slices know what their
|
||||
code will be called with):
|
||||
|
||||
| Verb | Request (beyond `verb`, `request_id`) | Response |
|
||||
| --- | --- | --- |
|
||||
| `container.list` | — | `containers[]`, `orphans[]` |
|
||||
| `container.reconcile` | `id?` | `container`, `diff` |
|
||||
| `pointer.acquire` | `id`, `ttl_s?`, `restore?` | `lease_id`, `bookmark` |
|
||||
| `pointer.move` | `id`, `lease_id`, `x`, `y` \| `dx`, `dy` | `bookmark` |
|
||||
| `pointer.button` | `id`, `lease_id`, `button`, `state` | `buttons[]` |
|
||||
| `pointer.click` | `id`, `lease_id`, `button?`, `count?` | `bookmark` |
|
||||
| `pointer.release` | `id`, `lease_id` | `bookmark`, `released_by` |
|
||||
| `pointer.state` | — | `holder`, `since`, `lease_id` |
|
||||
|
||||
### Error codes (extend `ExitCode`, do not renumber)
|
||||
|
||||
| 0 OK | 2 USAGE | 3 NO_SUCH_SESSION | 4 BAD_STATE | 5 DAEMON_UNREACHABLE |
|
||||
| 6 POLICY | 7 TIMEOUT | 8 BUSY | **9 NO_LEASE (new)** | **10 COMPOSITOR (new)** |
|
||||
|
||||
Activity accounting is unchanged and load-bearing: **`touch` is the only mark of
|
||||
activity**; `list`, `status`, `logs`, `gc`, and every `pointer.*` verb do **not**
|
||||
reset the idle clock.
|
||||
|
||||
---
|
||||
|
||||
## 5. Names and paths (frozen)
|
||||
|
||||
| Thing | Value |
|
||||
| --- | --- |
|
||||
| Compositor runtime dir | `/run/hypr-stream` — **must be ≤ 25 chars** (socket paths must stay under `sun_path`'s 108-byte limit) |
|
||||
| Compositor request socket | `<runtime dir>/hypr/<signature>/.socket.sock` |
|
||||
| Compositor event socket | `<runtime dir>/hypr/<signature>/.socket2.sock` |
|
||||
| Broker control socket | `/run/hhstream/control.sock` |
|
||||
| Broker↔driver socket | `/run/hhstream/pointer.sock` |
|
||||
| Broker state dir | `/var/lib/hermes/hhstream-sessions` |
|
||||
| Session runtime dir | `/run/hhstream/sessions/<session-id>` |
|
||||
| Container output name | `hh-<session-id>` |
|
||||
| Container workspace band | `1000 + slot`, allocated from the registry's free list |
|
||||
| Container mode | `1280x720` |
|
||||
| Units | `hyprland-headless`, `hyprland-headless-stream`, `hhstream-sessions`, `hhstream-pointer` |
|
||||
| Binaries | `hhstream`, `hhstreamd`, `hhstream-server`, `hhstream-client`, `hhstream-pointer` |
|
||||
| Service account | `hermes`, supplementary group `hhstream` |
|
||||
|
||||
---
|
||||
|
||||
## 6. Rules of engagement
|
||||
|
||||
1. **Only your files** (§2). A shared-file change you need is a report.
|
||||
2. **Unit tests only.** `nix develop -c python -m pytest tests/<yours> -q`.
|
||||
Nothing that builds a VM, rebuilds the system, or touches a live service.
|
||||
3. **Stdlib only**, except slice D which may add `pywayland`.
|
||||
4. **Machine style:** module docstrings that say *why*, not what; comments carry
|
||||
reasoning; no TODO placeholders; no speculative generality.
|
||||
5. **Definition of done:** a commit on your branch; your tests pass; your final
|
||||
message states (a) what you built, (b) the exact test command and its result,
|
||||
(c) what you could **not** verify, (d) any contract gap you hit. A slice that
|
||||
"finishes" without (b) is not done.
|
||||
6. **Do not open by reading the whole repo.** Your brief plus this contract is
|
||||
your context. Read the two or three files you actually touch.
|
||||
7. If the contract is wrong, say so and stop. If your slice turns out to need
|
||||
another slice's file, say so and stop. Both are successful outcomes.
|
||||
@@ -0,0 +1,662 @@
|
||||
# Plan — per-session workspaces, outputs, and pointer input
|
||||
|
||||
Technical specification for the next milestone of the headless-Hyprland session
|
||||
broker. Every claim about the compositor in here is either **[RAN]** on this
|
||||
machine or read from the running build's source at tag `v0.56.2`; the evidence
|
||||
markers and citations are in `REPORT.md` (same directory as the brief that
|
||||
produced it).
|
||||
|
||||
Status: **proposal — not approved, nothing built.** Stage 0 is a prerequisite for
|
||||
all of it and is nearly free.
|
||||
|
||||
---
|
||||
|
||||
## 1. Goals and non-goals
|
||||
|
||||
### Goals
|
||||
|
||||
| ID | Goal | Verified possible? |
|
||||
| --- | --- | --- |
|
||||
| G1 | A session owns a spatial container: listable, capturable in isolation, and torn down as a container — not just a process group | Yes — one headless output + one persistent workspace per session |
|
||||
| G2 | A session's identifier is returned at start and is sufficient later to observe, keep alive, kill, and now *target input at* | Yes — `session start` already prints the bare id; the record gains container fields |
|
||||
| G3 | Mouse input aimed at one session, without disturbing another session's contents | Yes — output-bound virtual pointer, serialised by a broker-wide lease |
|
||||
| G4 | Several sessions coexist, isolated enough that one cannot disturb another's container | Partly — spatial isolation yes; *adversarial* isolation needs Stage 4; crash isolation needs Stage 5 and this machine cannot afford it |
|
||||
|
||||
### Non-goals (deliberate, for now)
|
||||
|
||||
- **Concurrent pointer input in one compositor.** Structurally impossible: one
|
||||
`wl_seat`, one `m_pointerPos`. A second cursor requires a second compositor.
|
||||
- **Per-tenant compositors on this machine.** Hyprland consumes 96.6% of a core
|
||||
continuously at `debug:vfr = false` with software rendering on a 2-core box.
|
||||
Stage 5 is specified but gated on the CPU question.
|
||||
- **Typing.** Keyboard injection uses the same seat and the same serialisation
|
||||
question; it is specified as an extension of the pointer lease (§6.7) but not
|
||||
in the first three stages.
|
||||
- **A general window-management API** (move/resize/stack). The session owns a
|
||||
container; it does not manage windows inside it.
|
||||
|
||||
---
|
||||
|
||||
## 2. Architecture
|
||||
|
||||
```
|
||||
┌──────────────────────────────┐
|
||||
frame clients ──▶│ hyprland-headless-stream │ JPEG frames of ONE output
|
||||
│ (frame server, stream.sock) │
|
||||
└──────────────┬───────────────┘
|
||||
│ grim -o <output>
|
||||
┌──────────────────────────────┴──────────────────────────────┐
|
||||
│ hyprland-headless.service — ONE compositor, N outputs │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ output hh-A │ │ output hh-B │ │ output main │ │
|
||||
│ │ ws 101 │ │ ws 102 │ │ ws 1 │ │
|
||||
│ │ [app A] │ │ [app B] │ │ wallpaper │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└───────▲──────────────────▲───────────────────▲──────────────┘
|
||||
│ request socket │ socket2 (events) │ virtual pointer
|
||||
│ hyprctl / IPC │ │ (output-bound)
|
||||
┌───────┴──────────────────┴───────────────────┴──────────────┐
|
||||
│ hhstream-sessions.service — the broker (as `hermes`) │
|
||||
│ registry │ launcher │ ipc client │ pointer service │ reaper │
|
||||
└───────▲─────────────────────────────────────────────────────┘
|
||||
│ control socket (JSON request/response)
|
||||
┌───────┴─────────────────────────────────────────────────────┐
|
||||
│ hhstream CLI — status│shot│run│record│session … │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
Four moving parts change; the frame server is untouched except for which output
|
||||
it captures.
|
||||
|
||||
### 2.1 Component responsibilities
|
||||
|
||||
| Component | Owns | Must not |
|
||||
| --- | --- | --- |
|
||||
| `hyprland-headless` (compositor) | seats, outputs, workspaces, windows, the one cursor | know about sessions |
|
||||
| `hhstreamd` (broker) | the registry, session lifetime, containers, the pointer lease, the audit log | guess compositor state; act on a container it did not create without verifying |
|
||||
| `hhstream` (CLI) | argument parsing, exit codes, human formatting | hold state; talk to the compositor directly |
|
||||
| frame server | encoding and publishing frames of a nominated output | know which output belongs to whom |
|
||||
|
||||
---
|
||||
|
||||
## 3. Stage 0 — rename the runtime directory (prerequisite)
|
||||
|
||||
**Problem.** `$XDG_RUNTIME_DIR` is `/run/hyprland-headless-stream` (29 chars).
|
||||
Hyprland's IPC sockets are `$XDG_RUNTIME_DIR/hypr/$HIS/.socket.sock` and
|
||||
`…/.socket2.sock`, and the instance signature alone is ~30 chars, so the path
|
||||
exceeds `sun_path`'s 108-byte limit. The compositor logs
|
||||
`ERR ]: Socket2 path is too long. (2) IPC will not work.` **[RAN]**
|
||||
|
||||
**Consequence today.** The *request* socket works by luck of residual truncation
|
||||
(it is silently a different, shorter path both sides agree on); the *event*
|
||||
socket does not work at all. A generated comment in the Hyprland config asserts
|
||||
the IPC is misnamed and that `hyprctl clients` cannot connect — that is wrong in
|
||||
cause and conclusion; `hyprctl version|monitors|workspaces|clients|devices|
|
||||
layers|instances|cursorpos|status` all answer correctly against the live
|
||||
compositor **[RAN]**.
|
||||
|
||||
**Change.** Rename to `/run/hypr-stream` (15 chars) everywhere:
|
||||
|
||||
- `nix/module.nix`: `RuntimeDirectory` for both units, the published socket
|
||||
`default`, and the broker's `--compositor-runtime-dir`.
|
||||
- `/etc/nixos/hyprland-stream.nix`: `socketPath`, `sessions.stateDir` is
|
||||
unaffected.
|
||||
- The frame server's `HOME`/`WorkingDirectory`.
|
||||
- The `hhstream` CLI's default frame socket.
|
||||
- Remove the incorrect comment claiming IPC is broken, and replace it with the
|
||||
measured reason for the name length (**hard requirement: ≤ 25 chars**, so
|
||||
socket paths stay under `sun_path`).
|
||||
|
||||
**Gate.** In a VM: both sockets exist at their real names; `hyprctl` answers;
|
||||
a socket2 client receives `openwindow`/`workspace` events for a window it
|
||||
created. **Rollback:** the rename is config-only; reverting restores today's
|
||||
behaviour exactly (including the broken event socket).
|
||||
|
||||
**Risk.** Anything holding the old path. Enumerated above; there is nothing else
|
||||
on this machine.
|
||||
|
||||
---
|
||||
|
||||
## 4. Stage 1 — the broker speaks IPC
|
||||
|
||||
### 4.1 IPC client (`src/hhstreamd/ipc.py`)
|
||||
|
||||
One client, two sockets:
|
||||
|
||||
| Socket | Use | Failure behaviour |
|
||||
| --- | --- | --- |
|
||||
| `hypr/$HIS/.socket.sock` | request/response queries | retry once, then degrade (§4.4) |
|
||||
| `hypr/$HIS/.socket2.sock` | event stream | subscribe; on loss, reconcile by re-querying |
|
||||
|
||||
Instance discovery: `HYPRLAND_INSTANCE_SIGNATURE` if set, else the single
|
||||
`$XDG_RUNTIME_DIR/hypr/<sig>` directory. Store the signature in the session
|
||||
record so a restart re-attaches to the same instance rather than guessing.
|
||||
|
||||
Commands used (all **[RAN]** as available on this build):
|
||||
|
||||
| Purpose | Command |
|
||||
| --- | --- |
|
||||
| liveness / version | `version` |
|
||||
| outputs and their rects | `monitors` (with per-output `x,y,width,height,scale`) |
|
||||
| workspaces and their monitors | `workspaces` |
|
||||
| windows with class, title, workspace, monitor, `stableId` | `clients -j` |
|
||||
| cursor position (diagnostics only) | `cursorpos` |
|
||||
|
||||
Events consumed from socket2: `openwindow`, `closewindow`, `movewindow`,
|
||||
`movewindowv2`, `activewindow`, `activewindowv2`, `workspace`, `workspacev2`,
|
||||
`focusedmon`, `monitoradded`, `monitorremoved`, `urgent`.
|
||||
|
||||
### 4.2 Reconciler
|
||||
|
||||
An event stream that can break is not a source of truth. So:
|
||||
|
||||
1. Every mutation the broker performs is followed by a **read-back** of the
|
||||
affected fact (`clients -j` filtered to the session's container).
|
||||
2. On socket2 reconnect, a full reconcile runs: for each live session, compare
|
||||
the record against `clients -j` and repair or report.
|
||||
3. Reconciliation is the *only* writer of `window`/`workspace`/`output` fields
|
||||
from events; events merely schedule a reconcile of one session.
|
||||
|
||||
### 4.3 Record fields this fills
|
||||
|
||||
`workspace`, `window`, `foreground`, plus new `container` (§7). `foreground` is
|
||||
defined as the **monitor-active-workspace join**, not the client's `visible`
|
||||
field, so it means "a human or the frame server is actually looking at this".
|
||||
|
||||
### 4.4 Degraded mode
|
||||
|
||||
If no IPC is reachable: sessions still start, stop, reap and are tracked by
|
||||
process identity — exactly today's behaviour. `workspace`/`window` stay `null`
|
||||
(never guessed), `container: "none"`, and one line is logged at startup and
|
||||
reported in `status`. Lifecycle verbs never depend on IPC.
|
||||
|
||||
### 4.5 Teardown cross-check
|
||||
|
||||
Today teardown is process-group only. From here: after killing, verify from the
|
||||
compositor (no client with this session's app-id remains) and report a
|
||||
discrepancy as `survivors: [...]` rather than declaring success. Two independent
|
||||
sources — `pidfd`/`/proc` and the compositor — must agree.
|
||||
|
||||
---
|
||||
|
||||
## 5. Stage 2 — one output and one workspace per session
|
||||
|
||||
### 5.1 Container creation (on `start`)
|
||||
|
||||
1. `hyprctl output create headless hh-<session-id>` **[UNVERIFIED — experiment 3]**
|
||||
(strongly implied: Hyprland requests the headless backend as
|
||||
`AQ_BACKEND_REQUEST_MANDATORY`; `dispatchOutput` checks
|
||||
`getImplementations()` for `AQ_BACKEND_HEADLESS`).
|
||||
2. Generate a synthetic config for that output via `hyprctl keyword` (immediate,
|
||||
instance-scoped, no reload):
|
||||
- `workspace = <n>, monitor:hh-<id>, default:true, persistent:true`
|
||||
- `windowrule = match:initial_class ^hh-<id>$, workspace <n>, monitor hh-<id>`
|
||||
- the output's mode, taken from the container's size (default 1280×720).
|
||||
3. Launch the app with a matching identity so the rule binds: the app is
|
||||
started in a **`systemd-run --user` scope? No** — see §5.4 — the app is
|
||||
launched as today (plain `Popen`), with `--class`/`--app-id` set per app in
|
||||
the policy where the app supports it, and `XDPP_APP_ID`-style environment
|
||||
where it does not.
|
||||
4. Read back: the client's `workspace`, `monitor` and `stableId`; write them to
|
||||
the record.
|
||||
|
||||
Workspace numbering: containers get workspaces from a reserved band
|
||||
(1000 + slot) so nothing collides with the operator's own workspaces; the slot
|
||||
is allocated from a free list held in the registry and released on teardown.
|
||||
|
||||
### 5.2 The catch-all window rule
|
||||
|
||||
The current config has `windowrule = match:class .*, float on, size 1040 560,
|
||||
center on` — justified by the belief that IPC could not be queried. With Stage 1
|
||||
that belief is gone, so it is replaced by:
|
||||
|
||||
- per-container rules (`match:initial_class ^hh-<id>$`), and
|
||||
- a **quarantine backstop**: `match:class .*, workspace special:quarantine`.
|
||||
A window that matches no container lands in a hidden special workspace and is
|
||||
reported by `session list --unmatched`, instead of appearing on whatever
|
||||
output happened to be focused.
|
||||
|
||||
### 5.3 Teardown (on `kill`, reap, or gc)
|
||||
|
||||
1. Send the configured signal to the process group; wait `grace`; escalate.
|
||||
2. `hyprctl output remove hh-<id>` — removes the output, and with it the
|
||||
container. Windows on it are destroyed by the compositor when their surface
|
||||
is destroyed.
|
||||
3. Release the workspace number and the pointer bookmark.
|
||||
4. Record a tombstone with `container: "removed"` and the reason.
|
||||
|
||||
Reversible in one step: `output remove` is the container's deletion, and it is
|
||||
also the recovery path — a broker that has lost its registry can enumerate
|
||||
outputs named `hh-*` and converge (an orphan `hh-*` output with no session is
|
||||
either re-adopted or removed, never left behind).
|
||||
|
||||
### 5.4 Per-session capture
|
||||
|
||||
- `grim -o hh-<id> out.jpg` captures one container in isolation.
|
||||
- The frame server keeps publishing the **main** output for backwards
|
||||
compatibility (`hhstream shot`), and gains `--output hh-<id>` to publish or
|
||||
capture a specific container.
|
||||
- `grim -T <stableId>` (a window on a non-visible workspace) is **unverified**
|
||||
(experiment 1). The design does not depend on it: containers are outputs, so
|
||||
`grim -o` is always available. `-T` is a convenience if it works.
|
||||
|
||||
### 5.5 Container sizing and cost
|
||||
|
||||
Each output is a real render target. At `vfr = false` the compositor renders
|
||||
every output every frame **[UNVERIFIED — experiment 2]**. Therefore:
|
||||
|
||||
- `max_sessions` gains a **container budget** (`max_containers`, default 2 on
|
||||
this machine, to be re-derived from the measurement).
|
||||
- The measurement decides whether `vfr = true` is adopted (screencopy may drive
|
||||
rendering on demand, making it free performance). If `vfr` stays false, the
|
||||
container budget is a hard CPU decision, not a preference.
|
||||
|
||||
---
|
||||
|
||||
## 6. Stage 3 — the pointer lease and driver
|
||||
|
||||
### 6.1 What the compositor provides
|
||||
|
||||
- `zwlr_virtual_pointer_manager_v1` **version 2** is a live global **[RAN]**.
|
||||
- `create_virtual_pointer_with_output(seat, output, id)` — Hyprland stores
|
||||
`m_boundOutput` on the device and maps normalised absolute motion into that
|
||||
output's rectangle (`CPointerManager::warpAbsolute`, `PointerManager.cpp:905-920`)
|
||||
**[SRC]**.
|
||||
- `motion_absolute(time, x, y, w, h)`, `button(time, btn, state)`, `frame()`.
|
||||
- **No per-device position exists** (`IPointer.hpp`: only `m_boundOutput`,
|
||||
`m_connected`, flip flags, scroll factor) and **no query** for the cursor
|
||||
position. Position is one global `m_pointerPos`.
|
||||
|
||||
### 6.2 The lease — state machine
|
||||
|
||||
```
|
||||
acquire (free) release / ttl / crash
|
||||
FREE ───────────────▶ HELD(lease) ─────────────────────────▶ FREE
|
||||
▲ │ ▲
|
||||
│ force-release │ │ events (move/click) refresh TTL
|
||||
└───────────────────────┘ │
|
||||
└── any verb without the lease → BUSY (8)
|
||||
```
|
||||
|
||||
| Transition | Trigger | Side effects |
|
||||
| --- | --- | --- |
|
||||
| acquire | `session pointer acquire <id>` | take lock; warp from bookmark (or output centre); start TTL |
|
||||
| refresh | any gesture verb with a valid lease | extend TTL |
|
||||
| release | `session pointer release <id>` | write bookmark; lift any pressed buttons; free lock; stamp reason |
|
||||
| timeout | TTL (default 30 s) with no verb, or hard cap (default 300 s) | force-release; lift buttons; event `pointer_lease_timeout` |
|
||||
| crash | broker restart | leases are stale by definition → free; bookmarks intact |
|
||||
|
||||
Rules:
|
||||
|
||||
- **One holder.** The lock is broker-wide because the cursor is one. A second
|
||||
`acquire` returns `BUSY` (8) with the current holder's id.
|
||||
- **Gesture atomicity.** The lease must span warp → press → move → release. The
|
||||
broker will not interleave another session's events, and it *refuses*
|
||||
`pointer move` for a session that does not hold the lease.
|
||||
- **Never leave a button down.** On release/timeout with any button pressed, the
|
||||
broker sends the button-up and records `buttons_lifted: [BTN_LEFT]`.
|
||||
- **Bookmark written on every move and on release**, so a crash leaves the last
|
||||
real position.
|
||||
|
||||
### 6.3 Bookmark representation
|
||||
|
||||
```json
|
||||
"bookmark": {"x": 0.42, "y": 0.61, "output": "hh-<id>", "at": "2026-10-01T…Z"}
|
||||
```
|
||||
|
||||
Output-local **normalised** coordinates, because that is the frame
|
||||
`motion_absolute` already speaks: the value survives output resizes, layout
|
||||
changes and container renumbering, and needs no conversion on the way in.
|
||||
|
||||
### 6.4 Aiming
|
||||
|
||||
Converting a window-local pixel target to `motion_absolute` inputs:
|
||||
|
||||
1. Get the client's box from `clients -j` (or the container's rect if aiming at
|
||||
the output).
|
||||
2. Map box-local `(px, py)` → global → subtract the output's `(x, y)` from
|
||||
`monitors` → divide by the output's width/height.
|
||||
3. Emit `motion_absolute(t, X, Y, X_extent, Y_extent)` then `frame()`.
|
||||
4. Settle: `animations = false` is already set and is now a **correctness**
|
||||
requirement — a composition animation between warp and click moves the target
|
||||
under the cursor.
|
||||
|
||||
### 6.5 Driver placement
|
||||
|
||||
The driver is a **separate small process**, `hhstream-pointer`, not part of the
|
||||
broker's event loop: a Wayland client needs a connection of its own, and a
|
||||
blocked driver must not stall session lifecycle. The broker owns the lease and
|
||||
speaks to the driver over a private socket; the driver owns the Wayland
|
||||
connection and the per-session `zwlr_virtual_pointer_v1` objects. If the driver
|
||||
dies, the broker force-releases the lease.
|
||||
|
||||
### 6.6 What the lease does not protect
|
||||
|
||||
Nothing in the compositor stops *any* client from creating its own virtual
|
||||
pointer and moving the shared cursor — the global is advertised to everyone. The
|
||||
lease disciplines our sessions; it does not enforce against a hostile one. Stage
|
||||
4 is what makes it enforceable (the compositor's own global filter can deny
|
||||
input injection to a sandboxed session).
|
||||
|
||||
### 6.7 Keyboard (specified, later)
|
||||
|
||||
Same seat, same serialisation. `zwp_virtual_keyboard_manager_v1` exists **[RAN]**.
|
||||
The lease gains a `keyboard` flag so a typing burst is atomic; no new mechanism
|
||||
is needed. Not in Stages 0–3.
|
||||
|
||||
---
|
||||
|
||||
## 7. Data model — the session record (schema 3)
|
||||
|
||||
Today (`schema: 2`) the record has identity, lifecycle, and reserved-but-empty
|
||||
spatial fields. Schema 3 adds the container and the pointer, and makes the
|
||||
existing `null`s meaningful:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": 3,
|
||||
"id": "foot-v7r4li",
|
||||
"app": "foot",
|
||||
"argv": ["…"],
|
||||
|
||||
"pid": 1288, "pgid": 1288, "sid": 1288,
|
||||
"pid_starttime": 8100, "boot_id": "…",
|
||||
"exit_detected_by": "pidfd",
|
||||
|
||||
"state": "ready", // spawned|ready|exited|killed|reaped|failed
|
||||
"created_at": "…", "created_boottime": 81.0,
|
||||
"ready_signal": "spawned",
|
||||
"idle_timeout_s": 10800.0, "last_activity_at": "…", "last_activity_boottime": 106.5,
|
||||
"tombstoned_boottime": null,
|
||||
|
||||
"home": "/var/lib/hermes", "ephemeral_home": false,
|
||||
"runtime_dir": "/run/hhstream/sessions/foot-v7r4li",
|
||||
"log_path": "/var/lib/hermes/hhstream-sessions/logs/foot-v7r4li.log",
|
||||
|
||||
"container": { // NEW — null until Stage 2
|
||||
"output": "hh-foot-v7r4li",
|
||||
"workspace": 1003,
|
||||
"mode": {"width": 1280, "height": 720},
|
||||
"created_by": "broker",
|
||||
"state": "owned" // owned|degraded|removed|orphan
|
||||
},
|
||||
|
||||
"window": {"stable_id": "…", "class": "foot", "title": "…"}, // Stage 1
|
||||
"workspace": 1003, // Stage 1
|
||||
"foreground": false, // Stage 1 (monitor-active join)
|
||||
|
||||
"pointer": { // NEW — Stage 3, per-session bookmark
|
||||
"bookmark": {"x": 0.42, "y": 0.61, "output": "hh-foot-v7r4li", "at": "…"},
|
||||
"last_released_at": "…", "released_by": "lease|timeout|crash|kill"
|
||||
},
|
||||
|
||||
"command_count": 8, "adopted": false, "last_error": null,
|
||||
"signature": "efb5…" // NEW — HYPRLAND_INSTANCE_SIGNATURE
|
||||
}
|
||||
```
|
||||
|
||||
Invariants:
|
||||
|
||||
- `container: null` means "no spatial container" (degraded or pre-Stage-2), never
|
||||
"unknown but probably something".
|
||||
- `pointer` is written on release and on every move; a missing `pointer` is
|
||||
"never used", not "position unknown".
|
||||
- Every field the broker cannot verify stays `null`. No field is ever guessed.
|
||||
|
||||
---
|
||||
|
||||
## 8. Wire protocol (broker control socket)
|
||||
|
||||
Newline-delimited JSON request/response over the existing control socket. Every
|
||||
request gains a `request_id` (client-supplied) for idempotency; the broker keeps
|
||||
the last N completed ids per session and returns the recorded answer rather than
|
||||
repeating a mutation.
|
||||
|
||||
### 8.1 Verbs
|
||||
|
||||
| Verb | Request | Response | Stage |
|
||||
| --- | --- | --- | --- |
|
||||
| `session.start` | `app`, `argv[]`, `idle_timeout_s?`, `home?`, `ephemeral_home?`, `container?` | `session` (record) | existing (+container) |
|
||||
| `session.list` | `all?` | `sessions[]` | existing |
|
||||
| `session.status` | `id`, `events?` | `session`, `events[]` | existing |
|
||||
| `session.touch` | `id` | `session` | existing |
|
||||
| `session.kill` | `id`, `grace?`, `signal?` | `session`, `survivors[]` | existing (+cross-check) |
|
||||
| `session.gc` | — | `removed[]`, `orphans[]` | existing |
|
||||
| `session.adopt` | `pid`, `app?`, `idle_timeout_s?` | `session` | existing |
|
||||
| `session.logs` | `id`, `lines?` | `text` | existing |
|
||||
| `container.list` | — | `containers[]` (incl. orphans) | **2** |
|
||||
| `container.reconcile` | `id?` | `container`, `diff` | **2** |
|
||||
| `pointer.acquire` | `id`, `ttl_s?`, `restore?` | `lease_id`, `bookmark` | **3** |
|
||||
| `pointer.move` | `id`, `lease_id`, `x`, `y` \| `dx`, `dy` | `bookmark` | **3** |
|
||||
| `pointer.button` | `id`, `lease_id`, `button`, `state` | `buttons[]` | **3** |
|
||||
| `pointer.click` | `id`, `lease_id`, `button?`, `count?` | `bookmark` | **3** |
|
||||
| `pointer.release` | `id`, `lease_id` | `bookmark`, `released_by` | **3** |
|
||||
| `pointer.state` | — | `held_by`, `since`, `bookmark` | **3** |
|
||||
|
||||
### 8.2 Error model
|
||||
|
||||
Existing exit/status codes are kept and extended:
|
||||
|
||||
| Code | Name | Meaning | New? |
|
||||
| --- | --- | --- | --- |
|
||||
| 0 | OK | | |
|
||||
| 2 | USAGE | malformed request | |
|
||||
| 3 | NO_SUCH_SESSION | unknown id | |
|
||||
| 4 | BAD_STATE | e.g. kill on a reaped session | |
|
||||
| 5 | DAEMON_UNREACHABLE | socket missing/refused | |
|
||||
| 6 | POLICY | app or argument not allowlisted; container budget exhausted | |
|
||||
| 7 | TIMEOUT | wait_ready/grace expired | |
|
||||
| 8 | BUSY | **pointer lease held by another session** | |
|
||||
| 9 | NO_LEASE | **verb requires the lease and this session does not hold it** | new |
|
||||
| 10 | COMPOSITOR | **IPC or output operation failed; session survives in degraded mode** | new |
|
||||
|
||||
`COMPOSITOR` is distinct from a session failure on purpose: losing the
|
||||
compositor must not look like losing the session.
|
||||
|
||||
### 8.3 Activity accounting (unchanged, restated because it is load-bearing)
|
||||
|
||||
`touch` is the only mark of activity. `list`, `status`, `logs`, `gc`, and **all
|
||||
`pointer.*` verbs** do *not* reset the idle clock — a session that is being
|
||||
clicked in must still be kept alive explicitly, or a driven-but-idle session
|
||||
would never be reaped.
|
||||
|
||||
---
|
||||
|
||||
## 9. CLI surface
|
||||
|
||||
```
|
||||
hhstream status
|
||||
hhstream shot [--out FILE] [--output NAME] # --output NEW
|
||||
hhstream run [--] CMD… # unmanaged
|
||||
hhstream record [--seconds N] [--out FILE] [--output NAME]
|
||||
|
||||
hhstream session start APP [-- ARGV…] [--json]
|
||||
[--idle-timeout D] [--wait-ready D] [--home P | --ephemeral-home]
|
||||
[--no-container] # NEW: skip the container
|
||||
hhstream session list [--all] [--json]
|
||||
hhstream session status ID [--events N] [--json]
|
||||
hhstream session touch ID
|
||||
hhstream session kill ID [--grace D] [--signal S]
|
||||
hhstream session logs ID [--lines N] [--follow]
|
||||
hhstream session gc
|
||||
hhstream session adopt --pid PID [--app A] [--idle-timeout D]
|
||||
|
||||
hhstream session container ID [--json] # NEW
|
||||
hhstream session reconcile [ID] # NEW
|
||||
|
||||
hhstream session pointer acquire ID [--ttl D] [--no-restore] # NEW
|
||||
hhstream session pointer move ID --to X,Y | --by DX,DY # NEW
|
||||
hhstream session pointer click ID [--button left|right|middle] # NEW
|
||||
hhstream session pointer down ID [--button B] # NEW
|
||||
hhstream session pointer up ID [--button B] # NEW
|
||||
hhstream session pointer release ID # NEW
|
||||
hhstream session pointer state [--json] # NEW
|
||||
```
|
||||
|
||||
Human output keeps the current conventions: the bare identifier on stdout for
|
||||
`start`, detail on stderr, `--json` for the protocol object. Machine-facing
|
||||
consumers always use `--json`; human text is never parsed.
|
||||
|
||||
`list` gains two columns and one honest gap marker:
|
||||
|
||||
```
|
||||
ID APP STATE WS OUTPUT POINTER IDLE EXPIRES
|
||||
foot-v7r4li foot ready 1003 hh-foot-v7r4li free 0:12 2:59:48
|
||||
chromium-abc chromium ready 1004 hh-chromium-abc held:foot 0:03 2:59:57
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Policy (TOML) — new keys
|
||||
|
||||
```toml
|
||||
[broker]
|
||||
max_sessions = 4
|
||||
max_containers = 2 # NEW — CPU-bounded, from experiment 2
|
||||
degraded_ok = true # NEW — allow sessions with no container/ IPC
|
||||
|
||||
[compositor]
|
||||
signature = "auto" # NEW — or a pinned HYPRLAND_INSTANCE_SIGNATURE
|
||||
runtime_dir = "/run/hypr-stream" # NEW — must be ≤25 chars
|
||||
workspace_base = 1000 # NEW — reserved band for containers
|
||||
container_mode = "1280x720" # NEW
|
||||
quarantine_enabled = true # NEW
|
||||
|
||||
[pointer]
|
||||
lease_ttl_s = 30 # NEW — idle TTL before force-release
|
||||
lease_max_s = 300 # NEW — hard cap for a single lease
|
||||
settle_ms = 60 # NEW — wait after warp before pressing
|
||||
button_default = "left"
|
||||
restore_on_acquire = true # NEW — warp from bookmark
|
||||
|
||||
[apps.<name>]
|
||||
exec = "…"
|
||||
args_allow = [ … ] # unchanged: per-argument fnmatch, no shell
|
||||
app_id = "hh-<session>" # NEW — identity the window rule matches
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. NixOS module changes
|
||||
|
||||
Options added to `services.hyprland-headless-stream`:
|
||||
|
||||
| Option | Type | Default | Purpose |
|
||||
| --- | --- | --- | --- |
|
||||
| `sessions.containers.enable` | bool | `true` | per-session output+workspace |
|
||||
| `sessions.containers.max` | int | `2` | CPU budget (measure first) |
|
||||
| `sessions.containers.mode` | str | `"1280x720"` | container size |
|
||||
| `sessions.containers.workspaceBase` | int | `1000` | reserved band |
|
||||
| `sessions.pointer.enable` | bool | `false` | start `hhstream-pointer` |
|
||||
| `sessions.pointer.leaseTtl` | int (s) | `30` | |
|
||||
| `sessions.pointer.leaseMax` | int (s) | `300` | |
|
||||
|
||||
Unit changes:
|
||||
|
||||
- `hyprland-headless.service`, `hyprland-headless-stream.service`,
|
||||
`hhstream-sessions.service`: `RuntimeDirectory` → `hypr-stream` (Stage 0).
|
||||
- New `hhstream-pointer.service`: same user `hermes`, supplementary group
|
||||
`hhstream` (it needs the compositor's Wayland socket), `After=` the
|
||||
compositor, `Restart=on-failure`, `KillMode=process` (same reasoning as the
|
||||
broker: it must not take sessions down when it restarts).
|
||||
- tmpfiles: the pointer service's private runtime dir; the state dir already
|
||||
exists.
|
||||
- Assertion: `runtimeDirectory` length ≤ 25, failing evaluation rather than
|
||||
producing a compositor with a broken event socket.
|
||||
|
||||
---
|
||||
|
||||
## 12. Isolation (Stage 4) and per-tenant compositors (Stage 5)
|
||||
|
||||
**Stage 4 — sandbox a session's application.** Launch it through a
|
||||
`wp_security_context_manager_v1` listener with `sandbox_engine` and
|
||||
`app_id`/`instance_id` set per session, and hand it the restricted socket instead
|
||||
of the compositor's. The compositor's global filter then denies it: screen
|
||||
capture, input injection, enumerating other sessions' windows, layer-shell
|
||||
overlays, clipboard reads. This is what gives the pointer lease teeth (§6.6).
|
||||
Still not achievable: protection from a compositor crash, `xdg_activation`
|
||||
focus-stealing, and a stray window landing on another container.
|
||||
|
||||
**Stage 5 — per-tenant compositors.** `hyprland-session@.service` template;
|
||||
headless backend (never nested, never DRM); per-instance `RuntimeDirectory`
|
||||
≤25 chars; ideally a per-tenant user; per-session socket resolution in the broker
|
||||
instead of one global `--compositor-runtime-dir`. Gives truly concurrent
|
||||
pointers, crash isolation, kernel-level separation. **Gated on the CPU
|
||||
measurement** — at 96.6% of a core for one compositor on a 2-core box, this is
|
||||
not affordable today.
|
||||
|
||||
---
|
||||
|
||||
## 13. Failure modes
|
||||
|
||||
| Failure | Detection | Behaviour |
|
||||
| --- | --- | --- |
|
||||
| Compositor restarts | socket2 EOF; `version` fails | sessions are dead (their clients died with it) → mark `container: orphan`, reaper reports; broker re-attaches, does not pretend |
|
||||
| Broker restarts | unit restart | sessions live on (`KillMode=process`, plain `Popen`); adoption re-reads `clients -j` and re-binds containers by output name |
|
||||
| Output creation fails | `hyprctl output create` error | session starts **without** a container, `container: "degraded"`, exit code 10 from `container` verbs, lifecycle unaffected |
|
||||
| socket2 path too long | compositor log line | refuse to start in container mode; assert in the module (Stage 0 prevents it) |
|
||||
| A window matches no container | `openwindow` + no rule match | quarantined to a hidden workspace; reported by `container.list` as orphan |
|
||||
| Pointer driver dies | socket EOF | force-release the lease with reason `driver_gone`; sessions unaffected |
|
||||
| Lease holder goes silent | TTL | force-release after `lease_ttl_s`; buttons lifted; audit event |
|
||||
| Stuck button | button state in the lease | lifted on release/timeout; `buttons_lifted` recorded |
|
||||
| Registry lost, containers present | start-up scan | enumerate `hh-*` outputs and adopt or remove; never leave a container unattended |
|
||||
| `grim -o` fails on a container | capture error | frame server falls back to the main output and reports degraded, rather than publishing a black frame |
|
||||
|
||||
---
|
||||
|
||||
## 14. Testing and acceptance gates
|
||||
|
||||
Same discipline as today: **unit tests plus a real NixOS VM check per stage, all
|
||||
green before any switch**, and each check must be shown to fail when its
|
||||
mechanism is broken (mutation test), because twice now a check passed for the
|
||||
wrong reason.
|
||||
|
||||
| Stage | Unit | VM check | Key assertions |
|
||||
| --- | --- | --- | --- |
|
||||
| 0 | socket-path length is derived, not hardcoded | extend `vm-hyprland` | both sockets exist at real names; a socket2 subscriber receives `openwindow` for a window the test creates; `hyprctl` answers |
|
||||
| 1 | IPC parse/format against recorded fixtures; reconciler diff logic | `vm-ipc` | `workspace`/`window`/`foreground` are filled and match `clients -j`; teardown cross-check reports a deliberately-orphaned window as a survivor |
|
||||
| 2 | workspace-slot allocator; rule generation | `vm-containers` | one output per session, named `hh-*`; a second window of the same app lands in the same container; an unmatched window is quarantined; `grim -o` captures only that container; teardown removes the output |
|
||||
| 3 | lease state machine (TTL, hard cap, force-release, button lift); coordinate conversion | `vm-pointer` | acquire warps from the bookmark; a click lands where aimed (verified by reading back the *app's* state, not pixels); a second acquire returns BUSY; timeout releases and lifts buttons; a broker restart leaves the lock free and the bookmark intact |
|
||||
| 4 | policy filter expectations | `vm-sandbox` | a sandboxed app cannot bind a virtual pointer or capture the screen (both fail with a protocol error) |
|
||||
|
||||
Every check runs with an injected clock for the TTL logic, and with real time
|
||||
for at least one reap/expiry assertion — the existing `vm-sessions` does exactly
|
||||
this and it is why the race in the negative control was found.
|
||||
|
||||
---
|
||||
|
||||
## 15. Open questions and experiments
|
||||
|
||||
1. **Window capture off-screen** (`grim -T <stableId>`) — unverified; the design
|
||||
does not depend on it (containers are outputs).
|
||||
2. **Container cost at `vfr = false`** — gates `max_containers` and Stage 5.
|
||||
Procedure: create one headless output, measure the compositor's CPU for a
|
||||
minute, remove it; repeat with `vfr = true` and check the frame server still
|
||||
receives frames. Both mutate a live desktop, which is why they were not run.
|
||||
3. **Does `hyprctl output create headless` succeed on this instance?** Implied by
|
||||
source, unverified.
|
||||
4. **Decision, operator:** is serialised pointer input acceptable, or is
|
||||
concurrent input a hard requirement? Only the latter forces Stage 5.
|
||||
5. **Decision, operator:** the container budget (`max_containers`) if experiment
|
||||
2 shows a per-output cost that matters.
|
||||
6. **Decision, operator:** whether `hhstream pointer` verbs are part of the
|
||||
session-lease API now, or the lease is internal until input injection is
|
||||
proven useful end-to-end.
|
||||
|
||||
---
|
||||
|
||||
## 16. Recommended sequencing
|
||||
|
||||
1. **Stage 0** — rename, measured reason in the comment. Hours, unblocks
|
||||
everything, worth doing alone.
|
||||
2. **Stage 1** — IPC client + reconciler + record fields. Small.
|
||||
3. **Experiment 2** (cost) — because it sets `max_containers` and whether Stage
|
||||
5 is ever reachable.
|
||||
4. **Stage 2** — containers. Small-to-medium.
|
||||
5. **Stage 3** — pointer lease + driver. Small, given the lease is specified
|
||||
here.
|
||||
6. **Stage 4** — sandboxing, when adversarial isolation is wanted.
|
||||
7. **Stage 5** — only on evidence.
|
||||
|
||||
Each stage ships with its check, its rollback (revert the commit; containers and
|
||||
outputs are removed by `gc`), and an entry in the audit trail.
|
||||
Reference in new issue
Block a user