integrate the session broker: one CLI, a module unit, and a VM check
M0 of the sessions design, wired into the flake and gated by a real check. What is here now: - `src/hhstreamd/` — the broker: session registry, lifecycle verbs, process-group teardown, app allowlist, audit log, idle reaper on CLOCK_BOOTTIME. - `src/hhstream_session/` — the CLI handlers, registered into the one front door. - `src/hhstream/cli.py` — `hhstream status|shot|run|record|session …`, so the frame verbs and the session namespace are one binary. - `nix/module.nix` — `sessions.*` options and the `hhstream-sessions.service` unit: the operator's own account (never a service account, because launched applications should see that account's home), the compositor's group as a supplementary group (without it a launched GUI client cannot open the Wayland socket), the generated app allowlist, and `--compositor-runtime-dir` so applications are handed the compositor's session rather than the broker's. - `checks/vm-sessions.nix` — 18 subtests on a real compositor in a VM. Two bugs found by driving it, both fixed: - BUG-01: launched applications could not reach the compositor at all — the broker spawned them with its own inherited environment, which names the login session. `hhstreamd/compositor.py` discovers the socket and builds the child environment; a directory with no usable socket is a startup refusal, not a warning. - BUG-02: `kill` refused to signal a live application and said nothing was wrong. The identity gate hashed `/proc/<pid>/cmdline`, which every `execve` replaces — and on NixOS applications are reached through wrapper scripts that do exactly that. The gate now rests on `starttime` (+ boot id, + session id where it is immutable) and records command-line drift as evidence of nothing. KillMode=process is set on the unit on purpose: the default control-group kill would take the applications down with the broker, which would make adoption and a broker restart pointless.
This commit is contained in:
1 parent
9dc9e0da9a
commit
30f456c07e
37 files changed
+9118
-1
No files matched your search
@@ -0,0 +1,508 @@
|
||||
"""``hhstream session …`` — the CLI handlers, as a drop-in for someone else's CLI.
|
||||
|
||||
The integration contract is one function::
|
||||
|
||||
from hhstream_session import register
|
||||
register(subparsers) # subparsers from argparse's add_subparsers()
|
||||
...
|
||||
args = parser.parse_args()
|
||||
raise SystemExit(args.func(args))
|
||||
|
||||
``register`` adds a single ``session`` subcommand with its own verb tree, sets
|
||||
``func`` (and ``hhstream_session_handler``, for hosts that dispatch on their own
|
||||
attribute) to a callable taking the parsed namespace and returning an **exit
|
||||
code from the frozen table** in ``DESIGN.md`` §1.6. The registrant needs to
|
||||
know nothing about the daemon beyond the socket path, which comes from
|
||||
``--socket`` or ``$HHSTREAM_SOCKET``.
|
||||
|
||||
Nothing here is imported until a ``session`` verb actually runs: the module
|
||||
imports only :mod:`hhstreamd.protocol` (framing and exit codes) and the
|
||||
standard library, so a host CLI pays no startup cost and gains no new failure
|
||||
mode by registering it.
|
||||
|
||||
**The one thing to read before using this:** ``touch`` is the only mark of
|
||||
activity that exists. ``list``, ``status``, ``logs`` and ``gc`` deliberately do
|
||||
not reset a session's idle clock, so an agent watching a long-running app must
|
||||
call ``touch`` or the session will be reaped on schedule.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import sys
|
||||
import time
|
||||
from typing import Any, Callable
|
||||
|
||||
from hhstreamd.clock import format_duration, parse_duration
|
||||
from hhstreamd.protocol import ExitCode
|
||||
|
||||
from . import format as fmt
|
||||
from .client import DEFAULT_SOCKET, ENV_SOCKET, ClientError, call, reply_exit_code
|
||||
|
||||
__all__ = ["register", "build_parser", "dispatch", "main", "ExitCode"]
|
||||
|
||||
#: Printed under `session --help` and under `start --help`. It is here, in two
|
||||
#: places, because it is the single fact an agent gets wrong.
|
||||
ACTIVITY_NOTE = (
|
||||
"ACTIVITY: 'touch' is the ONLY thing that resets a session's idle clock. "
|
||||
"'list', 'status', 'logs' and 'gc' do NOT count — if polling kept sessions "
|
||||
"alive, an abandoned session would never be reaped. An agent that leaves an "
|
||||
"app running must call 'hhstream session touch <id>' before the idle timeout "
|
||||
"expires."
|
||||
)
|
||||
|
||||
_FOLLOW_INTERVAL_S = 0.5
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# registration
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def register(subparsers: Any, *, name: str = "session") -> argparse.ArgumentParser:
|
||||
"""Add the ``session`` namespace to an existing argparse subparser set.
|
||||
|
||||
Returns the namespace's parser, so a host that wants to add to it can.
|
||||
"""
|
||||
|
||||
parser = subparsers.add_parser(
|
||||
name,
|
||||
help="manage tracked application sessions (needs the hhstream session daemon)",
|
||||
description="Start, inspect, keep alive and kill tracked application sessions.",
|
||||
epilog=ACTIVITY_NOTE,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
)
|
||||
_build_namespace(parser)
|
||||
return parser
|
||||
|
||||
|
||||
def _socket_parent() -> argparse.ArgumentParser:
|
||||
"""Shared ``--socket`` so it may be given before *or* after the verb.
|
||||
|
||||
``SUPPRESS`` matters: without it the verb-level default would overwrite a
|
||||
value given at the namespace level.
|
||||
"""
|
||||
|
||||
common = argparse.ArgumentParser(add_help=False)
|
||||
common.add_argument(
|
||||
"--socket",
|
||||
default=argparse.SUPPRESS,
|
||||
metavar="PATH",
|
||||
help=f"control socket (default: ${ENV_SOCKET} or {DEFAULT_SOCKET})",
|
||||
)
|
||||
return common
|
||||
|
||||
|
||||
def _build_namespace(parser: argparse.ArgumentParser) -> None:
|
||||
common = _socket_parent()
|
||||
parser.add_argument(
|
||||
"--socket",
|
||||
default=None,
|
||||
metavar="PATH",
|
||||
help=f"control socket (default: ${ENV_SOCKET} or {DEFAULT_SOCKET})",
|
||||
)
|
||||
# `hhstream session` with no verb lists, because that is what everyone
|
||||
# types first.
|
||||
parser.set_defaults(func=_cmd_list, hhstream_session_handler=_cmd_list, all=False, json=False)
|
||||
|
||||
verbs = parser.add_subparsers(dest="session_verb", metavar="VERB")
|
||||
|
||||
def add(name: str, handler: Callable[[argparse.Namespace], int], **kwargs: Any):
|
||||
sub = verbs.add_parser(name, parents=[common], **kwargs)
|
||||
sub.set_defaults(func=handler, hhstream_session_handler=handler)
|
||||
sub.add_argument("--json", action="store_true", help="emit the protocol object on stdout")
|
||||
return sub
|
||||
|
||||
# ---- start -------------------------------------------------------
|
||||
start = add(
|
||||
"start",
|
||||
_cmd_start,
|
||||
help="launch an allowlisted application as a tracked session",
|
||||
description=(
|
||||
"Launch an allowlisted application. Prints the bare session id on "
|
||||
"stdout and human-readable detail on stderr, so $(hhstream session "
|
||||
"start foo) is the id and nothing else.\n\n"
|
||||
"Everything after a literal -- is passed to the application as an "
|
||||
"argv list: 'session start chromium -- --new-window URL'."
|
||||
),
|
||||
epilog=ACTIVITY_NOTE,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
)
|
||||
start.add_argument("app", help="an app name from the daemon's allowlist, never a path")
|
||||
start.add_argument(
|
||||
"argv",
|
||||
nargs="*",
|
||||
metavar="-- ARGV...",
|
||||
help="arguments for the application, after a literal --. Passed as an "
|
||||
"argv list; there is never a shell.",
|
||||
)
|
||||
start.add_argument(
|
||||
"--idle-timeout",
|
||||
type=_duration,
|
||||
metavar="DURATION",
|
||||
help="reap the session after this long with no 'touch' (e.g. 30s, 5m, 3h)",
|
||||
)
|
||||
start.add_argument(
|
||||
"--wait-ready",
|
||||
type=_duration,
|
||||
metavar="DURATION",
|
||||
help="how long to wait for the app to signal readiness",
|
||||
)
|
||||
home = start.add_mutually_exclusive_group()
|
||||
home.add_argument(
|
||||
"--home", metavar="PATH", help="run the app with this HOME instead of the inherited one"
|
||||
)
|
||||
home.add_argument(
|
||||
"--ephemeral-home",
|
||||
action="store_true",
|
||||
help="give the session a private HOME and delete it when the session ends "
|
||||
"(opt-in; by default the app inherits the real home directory)",
|
||||
)
|
||||
start.add_argument(
|
||||
"--request-id",
|
||||
metavar="ID",
|
||||
help="deduplication token: retrying a start with the same id returns the "
|
||||
"original reply instead of launching a second application",
|
||||
)
|
||||
|
||||
# ---- list --------------------------------------------------------
|
||||
lst = add("list", _cmd_list, help="list sessions (does NOT count as activity)")
|
||||
lst.add_argument("--all", action="store_true", help="include tombstones of ended sessions")
|
||||
|
||||
# ---- status ------------------------------------------------------
|
||||
status = add("status", _cmd_status, help="show one session (does NOT count as activity)")
|
||||
status.add_argument("id", help="session id")
|
||||
status.add_argument(
|
||||
"--events", type=int, default=20, metavar="N", help="recent audit events to include"
|
||||
)
|
||||
|
||||
# ---- touch -------------------------------------------------------
|
||||
add(
|
||||
"touch",
|
||||
_cmd_touch,
|
||||
help="reset the idle clock — THE ONLY MARK OF ACTIVITY",
|
||||
description=(
|
||||
"Reset the session's idle clock. Injects nothing, changes nothing "
|
||||
"else, and is the only verb that counts as activity: an agent "
|
||||
"observing a long-running application has no other way to say "
|
||||
"'still working'."
|
||||
),
|
||||
epilog=ACTIVITY_NOTE,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
).add_argument("id", help="session id")
|
||||
|
||||
# ---- kill --------------------------------------------------------
|
||||
kill = add("kill", _cmd_kill, help="terminate a session and everything it spawned")
|
||||
kill.add_argument("id", help="session id")
|
||||
kill.add_argument(
|
||||
"--grace",
|
||||
type=_duration,
|
||||
metavar="DURATION",
|
||||
help="how long to wait after the first signal before SIGKILL (default: the daemon's)",
|
||||
)
|
||||
kill.add_argument(
|
||||
"--signal", default="TERM", metavar="SIG", help="first signal to send (default: TERM)"
|
||||
)
|
||||
kill.add_argument("--request-id", metavar="ID", help="deduplication token")
|
||||
|
||||
# ---- gc ----------------------------------------------------------
|
||||
add(
|
||||
"gc",
|
||||
_cmd_gc,
|
||||
help="prune tombstones and reconcile the registry with /proc "
|
||||
"(does NOT count as activity)",
|
||||
).add_argument("--request-id", metavar="ID", help="deduplication token")
|
||||
|
||||
# ---- adopt -------------------------------------------------------
|
||||
adopt = add("adopt", _cmd_adopt, help="bring an already-running process under management")
|
||||
adopt.add_argument("--pid", type=int, required=True, help="pid to adopt")
|
||||
adopt.add_argument("--app", help="name to record (default: the executable's basename)")
|
||||
adopt.add_argument("--idle-timeout", type=_duration, metavar="DURATION")
|
||||
adopt.add_argument("--request-id", metavar="ID", help="deduplication token")
|
||||
|
||||
# ---- logs --------------------------------------------------------
|
||||
logs = add(
|
||||
"logs",
|
||||
_cmd_logs,
|
||||
help="the application's captured stdout/stderr (does NOT count as activity)",
|
||||
)
|
||||
logs.add_argument("id", help="session id")
|
||||
logs.add_argument("--lines", type=int, default=100, metavar="N", help="tail this many lines")
|
||||
logs.add_argument(
|
||||
"--follow", "-f", action="store_true", help="keep printing new output until interrupted"
|
||||
)
|
||||
|
||||
|
||||
def _duration(text: str) -> float:
|
||||
try:
|
||||
return parse_duration(text)
|
||||
except ValueError as exc:
|
||||
raise argparse.ArgumentTypeError(str(exc)) from exc
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# handlers
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _socket_of(args: argparse.Namespace) -> str | None:
|
||||
return getattr(args, "socket", None)
|
||||
|
||||
|
||||
def _request(args: argparse.Namespace, op: str, **fields: Any) -> dict[str, Any]:
|
||||
return call(op, socket_path=_socket_of(args), **fields)
|
||||
|
||||
|
||||
def _finish(args: argparse.Namespace, reply: dict[str, Any], render) -> int:
|
||||
"""Print a reply and return its exit code.
|
||||
|
||||
Errors always go to stderr and always carry the machine field, whatever the
|
||||
output mode, because that is what an agent branches on.
|
||||
"""
|
||||
|
||||
code = reply_exit_code(reply)
|
||||
if getattr(args, "json", False):
|
||||
fmt.dump_json(reply, stream=sys.stdout if reply.get("ok") else sys.stderr)
|
||||
elif reply.get("ok"):
|
||||
text = render(reply)
|
||||
if text:
|
||||
print(text)
|
||||
else:
|
||||
print(fmt.render_error(reply), file=sys.stderr)
|
||||
return int(code)
|
||||
|
||||
|
||||
def _guard(handler: Callable[[argparse.Namespace], int]) -> Callable[[argparse.Namespace], int]:
|
||||
def wrapper(args: argparse.Namespace) -> int:
|
||||
try:
|
||||
return handler(args)
|
||||
except ClientError as exc:
|
||||
if getattr(args, "json", False):
|
||||
fmt.dump_json(
|
||||
{"ok": False, "error": exc.error, "reason": exc.reason, "hint": exc.hint},
|
||||
stream=sys.stderr,
|
||||
)
|
||||
else:
|
||||
print(f"error: {exc.reason}", file=sys.stderr)
|
||||
if exc.hint:
|
||||
print(f"hint: {exc.hint}", file=sys.stderr)
|
||||
return int(exc.exit_code)
|
||||
except KeyboardInterrupt:
|
||||
return int(ExitCode.USAGE)
|
||||
|
||||
wrapper.__name__ = handler.__name__
|
||||
wrapper.__doc__ = handler.__doc__
|
||||
return wrapper
|
||||
|
||||
|
||||
@_guard
|
||||
def _cmd_start(args: argparse.Namespace) -> int:
|
||||
# argparse has already removed the separating `--`, so what is left is the
|
||||
# application's own argv, as a list. It is never joined into a string.
|
||||
argv = list(args.argv or [])
|
||||
reply = _request(
|
||||
args,
|
||||
"start",
|
||||
app=args.app,
|
||||
argv=argv,
|
||||
idle_timeout_s=args.idle_timeout,
|
||||
wait_ready_s=args.wait_ready,
|
||||
home=args.home,
|
||||
ephemeral_home=args.ephemeral_home or None,
|
||||
request_id=args.request_id,
|
||||
)
|
||||
if not reply.get("ok"):
|
||||
# A failed start may still have created a session (it exited at once, or
|
||||
# it is slow to become ready). Print the id so it can be inspected.
|
||||
if reply.get("id") and not args.json:
|
||||
print(reply["id"])
|
||||
return _finish(args, reply, lambda r: "")
|
||||
session = reply.get("session") or {}
|
||||
if args.json:
|
||||
fmt.dump_json(session)
|
||||
return int(ExitCode.OK)
|
||||
session_id = reply.get("id") or session.get("id") or ""
|
||||
# stdout is the bare id and nothing else; detail goes to stderr.
|
||||
print(session_id)
|
||||
print(
|
||||
f"started {session.get('app')} → {session_id} "
|
||||
f"(pid {session.get('pid')}, pgid {session.get('pgid')}, sid {session.get('sid')})",
|
||||
file=sys.stderr,
|
||||
)
|
||||
print(
|
||||
f"state {session.get('state')} via {session.get('ready_signal')}; "
|
||||
f"idle timeout {_fmt_timeout(session.get('idle_timeout_s'))}",
|
||||
file=sys.stderr,
|
||||
)
|
||||
print(
|
||||
f"keep it alive with: hhstream session touch {session_id} "
|
||||
"(the only mark of activity; list/status/logs/gc do not count)",
|
||||
file=sys.stderr,
|
||||
)
|
||||
return int(ExitCode.OK)
|
||||
|
||||
|
||||
def _fmt_timeout(seconds: Any) -> str:
|
||||
return "disabled" if not seconds else format_duration(seconds)
|
||||
|
||||
|
||||
@_guard
|
||||
def _cmd_list(args: argparse.Namespace) -> int:
|
||||
reply = _request(args, "list", all=bool(getattr(args, "all", False)) or None)
|
||||
return _finish(args, reply, lambda r: fmt.render_list(r.get("sessions") or []))
|
||||
|
||||
|
||||
@_guard
|
||||
def _cmd_status(args: argparse.Namespace) -> int:
|
||||
reply = _request(args, "status", id=args.id, events=args.events)
|
||||
return _finish(args, reply, lambda r: fmt.render_status(r.get("session") or {}))
|
||||
|
||||
|
||||
@_guard
|
||||
def _cmd_touch(args: argparse.Namespace) -> int:
|
||||
reply = _request(args, "touch", id=args.id)
|
||||
|
||||
def render(r: dict[str, Any]) -> str:
|
||||
session = r.get("session") or {}
|
||||
return (
|
||||
f"{session.get('id')}: idle clock reset; "
|
||||
f"expires in {format_duration(session.get('expires_in_s'))}"
|
||||
)
|
||||
|
||||
return _finish(args, reply, render)
|
||||
|
||||
|
||||
@_guard
|
||||
def _cmd_kill(args: argparse.Namespace) -> int:
|
||||
reply = _request(
|
||||
args,
|
||||
"kill",
|
||||
id=args.id,
|
||||
grace_s=args.grace,
|
||||
signal=args.signal,
|
||||
request_id=args.request_id,
|
||||
)
|
||||
|
||||
def render(r: dict[str, Any]) -> str:
|
||||
"""Say what the daemon actually did, not merely that it finished.
|
||||
|
||||
The old rendering could only distinguish "signalled" from "not
|
||||
signalled", and printed *the process was already gone* for both the
|
||||
routine case and the case where the daemon refused to signal a live
|
||||
application (BUG-02). A refusal is now an error reply and never reaches
|
||||
here; what is left is reported with the signal and the process group it
|
||||
went to, so "killed" cannot be read as more than it says.
|
||||
"""
|
||||
|
||||
session = r.get("session") or {}
|
||||
bits = [f"{session.get('id')}: {session.get('state')}"]
|
||||
sent = session.get("signal_sent")
|
||||
if sent:
|
||||
bits.append(f"sent {sent} to process group {session.get('pgid')}")
|
||||
if session.get("escalated_to_sigkill"):
|
||||
bits.append("escalated to SIGKILL")
|
||||
stragglers = session.get("stragglers") or 0
|
||||
if stragglers:
|
||||
bits.append(f"{stragglers} straggler(s) swept by session id")
|
||||
if session.get("signalled") is False and not sent:
|
||||
bits.append("nothing signalled (the process was already gone)")
|
||||
survivors = session.get("survivors") or []
|
||||
if survivors:
|
||||
# The loudest thing this command can say: the kill did not work.
|
||||
bits.append(
|
||||
f"WARNING: {len(survivors)} process(es) SURVIVED "
|
||||
f"({', '.join(str(p) for p in survivors)})"
|
||||
)
|
||||
return "; ".join(bits)
|
||||
|
||||
return _finish(args, reply, render)
|
||||
|
||||
|
||||
@_guard
|
||||
def _cmd_gc(args: argparse.Namespace) -> int:
|
||||
reply = _request(args, "gc", request_id=args.request_id)
|
||||
return _finish(args, reply, fmt.render_gc)
|
||||
|
||||
|
||||
@_guard
|
||||
def _cmd_adopt(args: argparse.Namespace) -> int:
|
||||
reply = _request(
|
||||
args,
|
||||
"adopt",
|
||||
pid=args.pid,
|
||||
app=args.app,
|
||||
idle_timeout_s=args.idle_timeout,
|
||||
request_id=args.request_id,
|
||||
)
|
||||
if reply.get("ok") and not args.json:
|
||||
print(reply.get("id", ""))
|
||||
session = reply.get("session") or {}
|
||||
print(
|
||||
f"adopted pid {session.get('pid')} as {reply['id']}; "
|
||||
"exit code will be unavailable (not a child of the daemon)",
|
||||
file=sys.stderr,
|
||||
)
|
||||
return int(ExitCode.OK)
|
||||
return _finish(args, reply, lambda r: "")
|
||||
|
||||
|
||||
@_guard
|
||||
def _cmd_logs(args: argparse.Namespace) -> int:
|
||||
reply = _request(args, "logs", id=args.id, lines=args.lines)
|
||||
if not reply.get("ok") or not args.follow:
|
||||
return _finish(args, reply, lambda r: "\n".join(r.get("lines") or []))
|
||||
# --follow polls from the returned offset. The daemon holds no streaming
|
||||
# connection open, so a follower that dies costs the daemon nothing.
|
||||
for line in reply.get("lines") or []:
|
||||
print(line)
|
||||
offset = reply.get("offset", 0)
|
||||
try:
|
||||
while True:
|
||||
if reply.get("eof"):
|
||||
break
|
||||
time.sleep(_FOLLOW_INTERVAL_S)
|
||||
reply = _request(args, "logs", id=args.id, offset=offset)
|
||||
if not reply.get("ok"):
|
||||
return _finish(args, reply, lambda r: "")
|
||||
for line in reply.get("lines") or []:
|
||||
print(line)
|
||||
offset = reply.get("offset", offset)
|
||||
except KeyboardInterrupt:
|
||||
pass
|
||||
return int(ExitCode.OK)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# standalone use
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def build_parser(prog: str = "hhstream") -> argparse.ArgumentParser:
|
||||
"""A host CLI stand-in, so the handlers can be driven without one."""
|
||||
|
||||
parser = argparse.ArgumentParser(prog=prog)
|
||||
subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
|
||||
register(subparsers)
|
||||
return parser
|
||||
|
||||
|
||||
def dispatch(args: argparse.Namespace) -> int:
|
||||
"""Run the handler argparse selected. The host may call this or ``args.func``."""
|
||||
|
||||
handler = getattr(args, "func", None)
|
||||
if handler is None:
|
||||
return int(ExitCode.USAGE)
|
||||
return int(handler(args))
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
parser = build_parser()
|
||||
args = parser.parse_args(argv)
|
||||
if getattr(args, "command", None) is None:
|
||||
parser.print_help(sys.stderr)
|
||||
return int(ExitCode.USAGE)
|
||||
return dispatch(args)
|
||||
|
||||
|
||||
if __name__ == "__main__": # pragma: no cover
|
||||
raise SystemExit(main())
|
||||
Reference in new issue
Block a user