the surface: CLI verbs, the module's options, and three checks the compositor votes in
Everything below the CLI was merged and green against fakes; none of it was
reachable and none of it had ever met a compositor. This wires it up and then
puts the compositor in a position to disagree.
CLI (src/hhstream/cli.py, src/hhstream_session/**)
session container [ID], session reconcile [ID], and the seven pointer verbs
from PLAN §9. `start` still prints the bare session id and nothing else.
`list` gains WS / OUTPUT / POINTER, with the gap marker where a value is
genuinely unknown rather than a blank that reads as zero -- the POINTER
column needs a second, read-only `pointer.state` call because the `list`
reply carries no lease state.
The lease id is cached in `hhstream_session.lease` (under
$XDG_RUNTIME_DIR), because PLAN §9's gesture verbs take no --lease and the
wire requires a lease_id on every one of them; --lease and $HHSTREAM_LEASE
override it, and a `no_lease` refusal drops the stale entry.
Exit codes are the contract's: a gesture with no lease is 9 and never
reaches the broker, and a compositor failure is 10 with a message that says
the session is still running. `kill` now warns about
`session.container_survivors` -- windows the compositor still shows -- and
distinguishes `null` ("could not ask") from `[]`.
`shot`/`record --output NAME` capture one container through `grim -o`; the
frame socket publishes the main output only, so it cannot do it.
Module (nix/module.nix)
sessions.containers.{enable,max,mode,workspaceBase},
sessions.pointer.{enable,leaseTtl,leaseMax}, rendered into the generated
TOML with §10's key names. hhstream-pointer.service: the operator's account,
supplementary group hhstream, After=/BindsTo= the compositor,
Restart=on-failure, KillMode=process, and the command line §3.4 freezes.
tmpfiles for /run/hhstream plus RuntimeDirectoryPreserve on the broker,
without which restarting the broker deletes the driver's socket out from
under it. The runtime-directory length assertion is untouched.
And ExecStartPost on the compositor, opening its IPC directory to its own
group: Hyprland creates <runtime>/hypr with S_IRWXU, so the broker -- a
different account by design -- could not reach the request or event socket
at all, and degraded silently exactly as it is built to.
Checks (checks/**)
vm-ipc: both sockets at their frozen names, measured against sun_path's 108
bytes, and a socket2 subscriber that receives an openwindow for a window the
test creates. The subscriber is the shipped HyprlandIPC, not a second
implementation: this check exists to prove that this client hears this
compositor.
vm-containers: one hh-* output per session at the container mode, the window
on it, a second window of the same application beside it, an unmatched
window quarantined, grim -o isolating one container, teardown removing the
output and freeing the slot. PLAN experiment 3 is answered: `hyprctl output
create headless` works.
vm-pointer: a version-2 virtual pointer, a warp and a click whose
coordinates the *application* reports, BUSY naming the holder, an expired
lease swept with its held button lifted, and a broker restart that leaves
the lock free, the bookmark intact and the driver reachable.
checks/lib gains the guest the three share, their test-script helpers (no
assertions live there), an event-socket subscriber and a Wayland client that
says where it was clicked -- nothing in nixpkgs both honours
$HHSTREAM_APP_ID and reports pointer events.
Reported, not worked around: the broker reads none of the container or
pointer config (policy.py takes [defaults] and [apps] only), `start` has no
no_container field so --no-container is refused rather than silently ignored,
and nix/hyprland-conf.nix sets input:follow_mouse = 0, which sends pointer
events to the focused window only -- measured, with the cursor at the aimed
pixel and no client told. README.dev.md has the evidence for each.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WQy29x9AfHWyzNd1f7XPGK
This commit is contained in:
1 parent
57fdd4f636
commit
de408e4b7f
19 files changed
+4304
-98
No files matched your search
+263
-10
@@ -13,6 +13,11 @@ from typing import Any
|
||||
|
||||
from hhstreamd.clock import format_duration
|
||||
|
||||
#: The honest gap. Printed wherever a value is genuinely unknown, because the
|
||||
#: alternative — a blank cell — reads as zero or as "no", and the three columns
|
||||
#: added in this milestone (``WS``, ``OUTPUT``, ``POINTER``) are unknown exactly
|
||||
#: when the compositor could not be asked. That is the case a reader most needs
|
||||
#: to be able to see.
|
||||
DASH = "—"
|
||||
|
||||
|
||||
@@ -35,19 +40,48 @@ def render_table(rows: list[list[str]], headers: list[str]) -> str:
|
||||
return "\n".join(out)
|
||||
|
||||
|
||||
def render_list(sessions: list[dict[str, Any]]) -> str:
|
||||
def pointer_cell(session_id: str, holder: Any, *, known: bool) -> str:
|
||||
"""The ``POINTER`` column for one row (PLAN §9).
|
||||
|
||||
Three facts, told apart on purpose: this session holds the one cursor
|
||||
(``held``), somebody else does and the row says who (``held:<id>``), or
|
||||
nobody does (``free``). ``known=False`` is the fourth case and prints the
|
||||
gap marker — the broker could not be asked who holds it, which is not the
|
||||
same as nobody holding it.
|
||||
"""
|
||||
|
||||
if not known:
|
||||
return DASH
|
||||
if holder is None:
|
||||
return "free"
|
||||
return "held" if holder == session_id else f"held:{holder}"
|
||||
|
||||
|
||||
def render_list(
|
||||
sessions: list[dict[str, Any]],
|
||||
*,
|
||||
pointer_holder: Any = None,
|
||||
pointer_known: bool = False,
|
||||
) -> str:
|
||||
"""The default view.
|
||||
|
||||
``EXPIRES IN`` is on it rather than behind a flag because it is the number
|
||||
an agent actually needs.
|
||||
|
||||
There is **no ``FG`` column** (DESIGN.md §1.4, amended): foreground-ness
|
||||
needs compositor IPC, which this milestone does not have, so the column was
|
||||
``?`` on every row of every listing — a header and six columns of width
|
||||
paying for no information, and a reader who has to learn that ``?`` means
|
||||
*unknown* rather than *no*. ``foreground`` stays in the record and in
|
||||
``status``, where it is one line among many and can become real without
|
||||
changing the shape of this table.
|
||||
``WS`` / ``OUTPUT`` / ``POINTER`` are the columns PLAN §9 asks for, and they
|
||||
are *after* ``PID`` rather than before it: the position of the existing
|
||||
columns is something callers already read (and a VM check asserts on), so
|
||||
the new ones are appended where nothing has to shift.
|
||||
|
||||
There is still **no ``FG`` column** (DESIGN.md §1.4, amended): it would be
|
||||
a sixth narrow column carrying a tri-state almost nobody branches on, and
|
||||
``status`` reports foreground in a line of its own. ``WS`` and ``OUTPUT``
|
||||
earn their width differently — they are how a caller finds the container to
|
||||
point ``grim -o`` or a pointer verb at.
|
||||
|
||||
``pointer_known`` exists because the ``list`` reply carries no lease state:
|
||||
the holder comes from a second, read-only ``pointer.state`` call, and when
|
||||
that call fails the column must say *unknown* rather than *free*.
|
||||
"""
|
||||
|
||||
if not sessions:
|
||||
@@ -64,17 +98,193 @@ def render_list(sessions: list[dict[str, Any]]) -> str:
|
||||
idle = DASH
|
||||
left = s.get("tombstone_expires_in_s")
|
||||
expires = f"(tombstone, {format_duration(left)} left)" if left is not None else DASH
|
||||
container = s.get("container") or {}
|
||||
rows.append(
|
||||
[
|
||||
_cell(s.get("id")),
|
||||
_cell(s.get("app")),
|
||||
_cell(s.get("state")),
|
||||
_cell(s.get("pid")) if live else DASH,
|
||||
_cell(s.get("workspace")),
|
||||
_cell(container.get("output")),
|
||||
pointer_cell(str(s.get("id")), pointer_holder, known=pointer_known)
|
||||
if live
|
||||
else DASH,
|
||||
idle,
|
||||
expires,
|
||||
]
|
||||
)
|
||||
return render_table(rows, ["ID", "APP", "STATE", "PID", "IDLE", "EXPIRES IN"])
|
||||
return render_table(
|
||||
rows,
|
||||
["ID", "APP", "STATE", "PID", "WS", "OUTPUT", "POINTER", "IDLE", "EXPIRES IN"],
|
||||
)
|
||||
|
||||
|
||||
def render_containers(reply: dict[str, Any]) -> str:
|
||||
"""``session container`` with no id: every container, and every orphan.
|
||||
|
||||
The orphan list is the reason this view exists at all. ``hh-*`` outputs with
|
||||
no live session are the thing a start-up scan removes, and until they are
|
||||
printed somewhere an operator has no way to see that the compositor is
|
||||
carrying render targets nobody owns.
|
||||
"""
|
||||
|
||||
rows = []
|
||||
for row in reply.get("containers") or []:
|
||||
rows.append(
|
||||
[
|
||||
_cell(row.get("id")),
|
||||
_cell(row.get("app")),
|
||||
_cell(row.get("output")),
|
||||
_cell(row.get("workspace")),
|
||||
render_mode(row.get("mode")),
|
||||
_cell(row.get("state")),
|
||||
_cell(row.get("window")),
|
||||
]
|
||||
)
|
||||
lines = [
|
||||
render_table(rows, ["ID", "APP", "OUTPUT", "WS", "MODE", "STATE", "WINDOW"])
|
||||
if rows
|
||||
else "no containers"
|
||||
]
|
||||
lines.append(f"compositor: {_cell(reply.get('compositor'))}")
|
||||
if reply.get("error"):
|
||||
lines.append(f" {reply['error']}")
|
||||
in_use = reply.get("workspaces_in_use")
|
||||
lines.append(
|
||||
"workspaces: " + (", ".join(str(w) for w in in_use) if in_use else "none in use")
|
||||
)
|
||||
orphans = reply.get("orphans")
|
||||
if orphans is None:
|
||||
# Not `[]`: "could not look" and "looked, found none" are different
|
||||
# claims and only one of them is reassuring.
|
||||
lines.append(f"orphans: {DASH} (the compositor could not be asked)")
|
||||
elif orphans:
|
||||
lines.append(
|
||||
f"orphans: {len(orphans)} hh-* output(s) no live session claims: "
|
||||
+ ", ".join(orphans)
|
||||
)
|
||||
else:
|
||||
lines.append("orphans: none")
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def render_container(reply: dict[str, Any]) -> str:
|
||||
"""``session container ID``: one session's container, and its drift."""
|
||||
|
||||
container = reply.get("container")
|
||||
lines = [f"{_cell(reply.get('id'))}"]
|
||||
if not container:
|
||||
lines.append(f" container {DASH} (this session has none)")
|
||||
else:
|
||||
lines.append(
|
||||
f" output {_cell(container.get('output'))}"
|
||||
f" workspace {_cell(container.get('workspace'))}"
|
||||
f" mode {render_mode(container.get('mode'))}"
|
||||
)
|
||||
lines.append(
|
||||
f" state {_cell(container.get('state'))}"
|
||||
f" created by {_cell(container.get('created_by'))}"
|
||||
)
|
||||
lines.extend(render_diff(reply.get("diff") or []))
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def render_diff(diff: list[dict[str, Any]]) -> list[str]:
|
||||
"""Where the record and the compositor disagreed, with both values.
|
||||
|
||||
An empty diff is printed, not omitted: "the record matches the compositor"
|
||||
is the useful answer to ``reconcile``, and silence would be read as a verb
|
||||
that did nothing.
|
||||
"""
|
||||
|
||||
if not diff:
|
||||
return [" drift none (the record matches the compositor)"]
|
||||
lines = [" drift"]
|
||||
for item in diff:
|
||||
if item.get("error"):
|
||||
lines.append(f" {item.get('id')}: {item['field']} — {item['error']}")
|
||||
continue
|
||||
lines.append(
|
||||
f" {item.get('id')}: {item.get('field')} "
|
||||
f"recorded {item.get('recorded')!r}, compositor says {item.get('observed')!r}"
|
||||
)
|
||||
return lines
|
||||
|
||||
|
||||
def render_reconcile(reply: dict[str, Any]) -> str:
|
||||
"""``session reconcile``, with or without an id."""
|
||||
|
||||
if reply.get("id"):
|
||||
return render_container(reply)
|
||||
scan = reply.get("scan") or {}
|
||||
lines = [
|
||||
f"compositor: {'reachable' if scan.get('available') else 'unreachable'}"
|
||||
+ (f" (signature {scan['signature']})" if scan.get("signature") else ""),
|
||||
]
|
||||
if scan.get("error"):
|
||||
lines.append(f" {scan['error']}")
|
||||
lines.append(f"quarantine: {_cell(scan.get('quarantine'))}")
|
||||
# The scan's four lists carry different shapes -- `removed` is a list of
|
||||
# output names, the others are records -- so each is rendered rather than
|
||||
# printed, and `failed` is last and loudest because it is the only one that
|
||||
# means the compositor and the registry are still out of step.
|
||||
for item in scan.get("adopted") or []:
|
||||
lines.append(f" adopted {_scan_item(item)}")
|
||||
for output in scan.get("removed") or []:
|
||||
lines.append(f" removed {output} (no live session claimed it)")
|
||||
for item in scan.get("orphaned") or []:
|
||||
lines.append(f" orphan {_scan_item(item)}")
|
||||
for item in scan.get("failed") or []:
|
||||
lines.append(f" FAILED {_scan_item(item)}")
|
||||
lines.extend(render_diff(reply.get("diff") or []))
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def _scan_item(item: Any) -> str:
|
||||
"""One entry of a reconcile scan list, whatever shape it has."""
|
||||
|
||||
if not isinstance(item, dict):
|
||||
return str(item)
|
||||
return " ".join(f"{key} {value}" for key, value in item.items())
|
||||
|
||||
|
||||
def render_mode(mode: dict[str, Any] | None) -> str:
|
||||
"""``WIDTHxHEIGHT``, or the gap marker for a container that has no mode.
|
||||
|
||||
A degraded container records ``None`` here rather than a size it never set,
|
||||
so this has to be able to say so.
|
||||
"""
|
||||
|
||||
if not mode:
|
||||
return DASH
|
||||
return f"{mode.get('width')}x{mode.get('height')}"
|
||||
|
||||
|
||||
def render_bookmark(bookmark: dict[str, Any] | None) -> str:
|
||||
"""Where the cursor is, in the words the wire uses (PLAN §6.3)."""
|
||||
|
||||
if not isinstance(bookmark, dict):
|
||||
return DASH
|
||||
x, y = bookmark.get("x"), bookmark.get("y")
|
||||
if not isinstance(x, (int, float)) or not isinstance(y, (int, float)):
|
||||
return DASH
|
||||
return f"{x:.4f},{y:.4f} on {bookmark.get('output')} at {bookmark.get('at')}"
|
||||
|
||||
|
||||
def render_pointer_state(reply: dict[str, Any]) -> str:
|
||||
holder = reply.get("holder")
|
||||
buttons = reply.get("buttons") or []
|
||||
lines = [
|
||||
f"holder {holder if holder else 'free'}",
|
||||
f"lease {_cell(reply.get('lease_id'))}",
|
||||
# Loud, because a button left down is the one pointer failure that keeps
|
||||
# hurting after the lease is gone.
|
||||
f"buttons {', '.join(buttons) if buttons else 'none down'}",
|
||||
f"bookmark {render_bookmark(reply.get('bookmark'))}",
|
||||
f"driver {_cell(reply.get('driver'))}",
|
||||
]
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def render_status(session: dict[str, Any]) -> str:
|
||||
@@ -148,8 +358,51 @@ def render_gc(result: dict[str, Any]) -> str:
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
#: Error names whose failure is on the *compositor* side (exit 10), annotated
|
||||
#: with what that means for the session. CONTRACT-sessions.md §4 makes the
|
||||
#: distinction load-bearing — "the session is not lost, it keeps running in
|
||||
#: degraded mode" — and a message that only said "error" would leave a caller
|
||||
#: deciding whether to restart an application that is perfectly alive.
|
||||
COMPOSITOR_ERRORS = {
|
||||
"compositor": "the compositor or the output operation failed",
|
||||
"compositor_unavailable": "the compositor's IPC socket could not be reached",
|
||||
"no_container": "this session has no container output to aim at",
|
||||
"driver_unavailable": "the pointer driver is not reachable",
|
||||
"driver_refused": "the pointer driver refused the operation",
|
||||
}
|
||||
|
||||
|
||||
def render_error(reply: dict[str, Any]) -> str:
|
||||
parts = [f"error: {reply.get('reason') or reply.get('error')}"]
|
||||
"""The human error, saying which side of the system failed.
|
||||
|
||||
Three classes get a named prefix because an agent (and a person) acts
|
||||
differently on each: a compositor failure leaves the application running, a
|
||||
missing lease is fixed by acquiring one, and anything else is about the
|
||||
session itself.
|
||||
"""
|
||||
|
||||
error = reply.get("error") or ""
|
||||
reason = reply.get("reason") or error
|
||||
if error in COMPOSITOR_ERRORS:
|
||||
parts = [
|
||||
f"compositor error: {reason}",
|
||||
f" {COMPOSITOR_ERRORS[error]}; the session itself is unaffected "
|
||||
"and keeps running (exit 10, not a session failure)",
|
||||
]
|
||||
elif error == "no_lease":
|
||||
parts = [
|
||||
f"no pointer lease: {reason}",
|
||||
" this session does not hold the one cursor (exit 9); acquire it "
|
||||
"first with 'pointer acquire'",
|
||||
]
|
||||
elif error == "pointer_busy":
|
||||
parts = [
|
||||
f"pointer busy: {reason}",
|
||||
" another session holds the one cursor (exit 8); wait for it to "
|
||||
"release or for its lease to time out",
|
||||
]
|
||||
else:
|
||||
parts = [f"error: {reason}"]
|
||||
if reply.get("hint"):
|
||||
parts.append(f"hint: {reply['hint']}")
|
||||
return "\n".join(parts)
|
||||
Reference in new issue
Block a user