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,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