Compare commits
26
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ca5dbfb2ea | ||
|
|
850f9caa1d | ||
|
|
7d8ca6191b | ||
|
|
8c99518a62 | ||
|
|
0f2810afaa | ||
|
|
e636472106 | ||
|
|
56493721f0 | ||
|
|
0a63c9b7fc | ||
|
|
6a40c7e2e4 | ||
|
|
fea55eecde | ||
|
|
549c73e8ae | ||
|
|
ca5e309e51 | ||
|
|
f3ac9ada27 | ||
|
|
443efd8da8 | ||
|
|
5f94833a76 | ||
|
|
c6cfd02bf3 | ||
|
|
4461660c6d | ||
|
|
4fefb448ac | ||
|
|
7141900070 | ||
|
|
934774f15e | ||
|
|
db7aaf8276 | ||
|
|
bd3ca2e644 | ||
|
|
a9299682d2 | ||
|
|
19338af17c | ||
|
|
52e3786bfb | ||
|
|
9744d35945 |
No files matched your search
+52
-10
@@ -7,8 +7,8 @@ decides, and if the document is wrong it gets a version bump, not an edit.
|
||||
## Prerequisites
|
||||
|
||||
- Nix with flakes enabled.
|
||||
- `/dev/kvm` readable, for the six VM checks. They are `nixosTest`s; without
|
||||
KVM they still run, just slowly enough that the timeouts below get tight.
|
||||
- `/dev/kvm` readable, for the VM checks. They are `nixosTest`s; without KVM
|
||||
they still run, just slowly enough that the timeouts below get tight.
|
||||
- No GPU. Nothing in the test suite needs one — the compositor runs on
|
||||
Hyprland's headless backend over software rendering.
|
||||
|
||||
@@ -21,21 +21,39 @@ socket outside the build sandbox or the test VM.
|
||||
nix develop
|
||||
```
|
||||
|
||||
Puts `python3`, `pytest`, `hyprland`, `grim`, `ffmpeg`, `jq` and `tmux` on PATH
|
||||
and sets `PYTHONPATH=$PWD/src`, so `import hhstream` picks up the working tree
|
||||
rather than an installed copy.
|
||||
Puts `python3`, `pytest`, `hyprland`, `grim`, `ffmpeg`, `jq` and `tmux` on PATH,
|
||||
plus both packages (`hhstream` and `hhstream-mcp`) and the `mcp` SDK, and sets
|
||||
`PYTHONPATH=$PWD/src`, so `import hhstream` and `import hhstream_mcp` both pick
|
||||
up the working tree rather than an installed copy.
|
||||
|
||||
## Build
|
||||
|
||||
```bash
|
||||
nix build .#hhstream # the package
|
||||
ls result/bin # hhstream-server, hhstream-client, hhstream,
|
||||
# hhstreamd, hhstream-pointer
|
||||
# hhstreamd, hhstream-pointer, hhstream-live
|
||||
|
||||
nix build .#hhstream-mcp # the MCP server, a SEPARATE derivation
|
||||
ls result/bin # hhstream-mcp
|
||||
```
|
||||
|
||||
Five entry points: the frame server and a reference reader for it, the `hhstream`
|
||||
front-door CLI (frames, `run`, and the `session` namespace), the session broker,
|
||||
and the pointer driver.
|
||||
The first package's entry points: the frame server and a reference reader for
|
||||
it, the `hhstream` front-door CLI (frames, `run`, and the `session` namespace),
|
||||
the session broker, the pointer driver and the session-stream web app.
|
||||
|
||||
`hhstream-mcp` is its own derivation on purpose. It is the CLI as Model Context
|
||||
Protocol tools (`docs/CONTRACT-mcp.md`), it depends on the third-party `mcp`
|
||||
SDK, and `packages.hhstream` is stdlib-only by policy — see the header of
|
||||
`nix/mcp.nix`. It depends on the `hhstream` package as a *library*: the tools
|
||||
call `hhstream.cli`'s handlers in process rather than spawning the CLI. The dev
|
||||
shell has both, plus `python3.pkgs.mcp` so `tests/unit/test_mcp_server.py` can
|
||||
import the SDK:
|
||||
|
||||
```bash
|
||||
nix develop
|
||||
hhstream-mcp --list-tools # the 21 acting verbs
|
||||
hhstream-mcp --list-resources # the 8 read-only URIs
|
||||
```
|
||||
|
||||
## The checks
|
||||
|
||||
@@ -48,6 +66,10 @@ and the pointer driver.
|
||||
| `vm-ipc` | the **compositor's IPC**: both sockets exist at the names `docs/CONTRACT-sessions.md` §5 freezes and fit inside `sun_path`, `hyprctl` answers, the broker's own `HyprlandIPC` reaches it, and a subscriber on the **event** socket receives an `openwindow` for a window the test creates | yes |
|
||||
| `vm-containers` | one `hh-*` output per session at the container mode, the application's window on it, a second window of the same application beside it, an unmatched window **quarantined**, `grim -o` capturing that container alone, and teardown removing the output and freeing its workspace slot | yes |
|
||||
| `vm-pointer` | the **lease and the driver**: a version-2 virtual pointer, a warp that lands where it was aimed *as the application reports it*, a click delivered as one press and one release, a contended acquire refused with BUSY, 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 | yes |
|
||||
| `vm-keyboard` | the **keymap, the focus and a decoded symbol**: the keymap the driver uploads reaching a real compositor, `pointer acquire` leaving the aimed window holding the *keyboard* and not merely the cursor, and `hhs-keyboard-target` decoding `hello` from the keymap it was **forwarded** — so a driver that stopped uploading one arrives as `sym=?` and goes red | yes |
|
||||
| `vm-keyboard-de` | the same file with `sessions.keyboard.layout = "de"`, because that option reaches the uploaded keymap through exactly one path — `--xkb-layout` on the driver unit — and a single-layout check cannot tell that path from a hardcoded `us`: keysym `y`'s evdev code swaps (21 against 44), the forwarded `symbols=` name with it, and `ü` goes from exit 2 to `udiaeresis` | yes |
|
||||
| `vm-stream-firewall` | the stream's **port**: the guest's own running firewall accepts the configured port and not the module's default, a peer outside the guest reaches it, and is refused on a port beside it that was never opened | yes |
|
||||
| `vm-mcp` | the **MCP server over stdio**: `mcp.enable` puts the binary on PATH and starts no unit, the `initialize` handshake completes over a real pipe, all 21 tools and 8 resources are listed with their annotations and their two rules, both a tool call and a resource read reach the live broker and return its own protocol object, two reads of a session do **not** move its idle deadline while `session_touch` does, a frame arrives as a blob at exactly its output's configured size, the pointer lease is granted/used/returned against the real driver, `--toolsets` narrows the tools and leaves the resources alone, and a refusal arrives as a tool error (or, for a read, a protocol error) carrying the frozen exit code | yes |
|
||||
|
||||
All of them at once:
|
||||
|
||||
@@ -69,6 +91,10 @@ nix build -L .#checks.x86_64-linux.vm-sessions
|
||||
nix build -L .#checks.x86_64-linux.vm-ipc
|
||||
nix build -L .#checks.x86_64-linux.vm-containers
|
||||
nix build -L .#checks.x86_64-linux.vm-pointer
|
||||
nix build -L .#checks.x86_64-linux.vm-keyboard
|
||||
nix build -L .#checks.x86_64-linux.vm-keyboard-de
|
||||
nix build -L .#checks.x86_64-linux.vm-stream-firewall
|
||||
nix build -L .#checks.x86_64-linux.vm-mcp
|
||||
```
|
||||
|
||||
`-L` is not optional in practice: without it, Nix hides the build log, and the
|
||||
@@ -91,7 +117,17 @@ warning.
|
||||
|
||||
pytest over `tests/unit/`, run in the build sandbox with `PYTHONPATH` pointing at
|
||||
what `nix/package.nix` installed (`nix/package.nix` sets `doCheck = false` on
|
||||
purpose, so this is the only place the suite runs in a build).
|
||||
purpose, so this is the only place the suite runs in a build). `nix/mcp.nix`'s
|
||||
output is on that path beside it, and `mcp` is in the test environment, because
|
||||
`tests/unit/test_mcp_*.py` import `hhstream_mcp` and one of them imports the SDK
|
||||
— not optionally: a file that skipped when the SDK was absent would be green in
|
||||
exactly the build where a malformed tool schema mattered.
|
||||
|
||||
The MCP suite is four files, split along what each can be tested without:
|
||||
`test_mcp_invoke.py` (the in-process CLI call and the exit-code mapping),
|
||||
`test_mcp_tools.py` (the argv each tool builds, and the toolsets),
|
||||
`test_mcp_resources.py` (URI routing, query parameters, and that a read never
|
||||
writes) and `test_mcp_server.py` (the SDK wiring, over its memory transport).
|
||||
|
||||
The check fails if the suite is **empty**, not just if it is red. `pytest` exits
|
||||
5 on "collected nothing", but it exits 0 when every test was skipped or
|
||||
@@ -223,6 +259,12 @@ checks/
|
||||
symbol a client decoded. Exposed TWICE -- `vm-keyboard`
|
||||
(layout us) and `vm-keyboard-de` -- because the layout
|
||||
reaches the keymap only through the driver unit's argv
|
||||
vm-stream-firewall.nix nixosTest, the stream's port in the guest's firewall
|
||||
vm-mcp.nix nixosTest, hhstream-mcp driven over stdio by a raw
|
||||
JSON-RPC client against the live broker
|
||||
lib/mcp_client.py that client: hhs-mcp-call, stdlib only and deliberately
|
||||
NOT the MCP SDK's -- the SDK on both ends would agree
|
||||
with itself about a framing neither side had to get right
|
||||
lib/test-tools.nix packages the tests/ helpers for the guest
|
||||
lib/session-tools.nix packages the two guest programs below
|
||||
lib/session-machine.nix the guest the three session checks share
|
||||
|
||||
@@ -35,9 +35,93 @@ hhstream-client --socket /run/hypr-stream/stream.sock --count 1 --out frame.png
|
||||
The socket is a plain file descriptor: the server serves every client that
|
||||
connects, and keeps running when one disconnects.
|
||||
|
||||
## Driving it from an agent: the MCP server
|
||||
|
||||
`hhstream-mcp` is the `hhstream` CLI behind a [Model Context
|
||||
Protocol](https://modelcontextprotocol.io) surface, so an agent can look at this
|
||||
desktop, put an application on it, and aim its one pointer and keyboard at that
|
||||
application without writing command lines. The interface is frozen in
|
||||
`docs/CONTRACT-mcp.md`.
|
||||
|
||||
It is split the way the protocol splits things:
|
||||
|
||||
- **Resources are the state** — eight of them, read by URI, and reading one
|
||||
changes nothing. `hhstream://status` is whether the desktop is up,
|
||||
`hhstream://sessions` is what is running, `hhstream://sessions/<id>/logs` is
|
||||
an application's own output, `hhstream://pointer` is who holds the input
|
||||
lease, `hhstream://screen` is a frame of the screen.
|
||||
- **Tools are the acts** — twenty-one, one per CLI verb that does something.
|
||||
`session_start` puts an application on the screen, `pointer_acquire` takes the
|
||||
input lease, `keyboard_type` types, `session_kill` ends a session.
|
||||
|
||||
A host decides what state to put in front of its model; the model decides what
|
||||
to do. That is the whole of the split, and it is why `shot` is still a tool
|
||||
(capturing is an act at a moment) while `hhstream://screen` exists beside it.
|
||||
|
||||
It is a thin wrapper and nothing more: every tool and every resource builds the
|
||||
argv list the CLI's own parser takes, runs the CLI's own handler, and maps what
|
||||
came back. The idle clock, the pointer lease, the allowlist and the exit-code
|
||||
table all stay where they were.
|
||||
|
||||
Install it with the module — off by default, because it is the surface through
|
||||
which a language model starts processes on this machine:
|
||||
|
||||
```nix
|
||||
services.hyprland-headless-stream = {
|
||||
enable = true;
|
||||
sessions.enable = true; # the session, pointer and keyboard tools need the broker
|
||||
mcp.enable = true; # puts `hhstream-mcp` on the system PATH
|
||||
};
|
||||
```
|
||||
|
||||
Then register it with a client. The transport is **stdio** — one process per
|
||||
client, spawned by the client, no port and no daemon — so the whole
|
||||
configuration is a command and an environment:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"hhstream": {
|
||||
"command": "hhstream-mcp",
|
||||
"env": {
|
||||
"HHSTREAM_SOCKET": "/run/hhstream/control.sock",
|
||||
"HHSTREAM_FRAME_SOCKET": "/run/hypr-stream/stream.sock"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Both variables are the CLI's own and both are shown at their defaults, so they
|
||||
can be left out unless this machine moved a socket. The account the client runs
|
||||
as needs what the CLI needs: membership of the compositor's group (`hhstream`)
|
||||
to read the frame socket, and of the broker's to reach the control socket. The
|
||||
server cannot recover that for itself the way the CLI does — see
|
||||
`docs/CONTRACT-mcp.md` §5 — so if `shot` reports it cannot read the socket, the
|
||||
answer is `"command": "sg", "args": ["hhstream", "-c", "hhstream-mcp"]` or an
|
||||
account in the group.
|
||||
|
||||
`hhstream-mcp --list-tools` and `--list-resources` print the two tables and
|
||||
exit, which is the quickest way to check an install.
|
||||
|
||||
If twenty-one tools is more than a client has room for, `--toolsets` narrows
|
||||
what is offered to whichever families are wanted — `frames`, `sessions`,
|
||||
`pointer`, `keyboard`:
|
||||
|
||||
```json
|
||||
{ "command": "hhstream-mcp", "args": ["--toolsets", "frames,pointer,keyboard"] }
|
||||
```
|
||||
|
||||
Resources are deliberately *not* narrowed by it: they are the host's context,
|
||||
not the model's tool budget. Nothing else about the server is configurable — it
|
||||
holds no state and caches no lease, and the pointer lease is an explicit
|
||||
argument on every gesture tool for exactly that reason.
|
||||
|
||||
| Document | What it is |
|
||||
|---|---|
|
||||
| `docs/CONTRACT.md` | the wire protocol and the module surface — the interface other people build against |
|
||||
| `docs/CONTRACT-sessions.md` | the broker, the containers and the input lease |
|
||||
| `docs/CONTRACT-mcp.md` | the MCP surface: the resource URIs, the tool names, their arguments and the error mapping |
|
||||
| `docs/ARCHITECTURE.md` | how the pieces fit: compositor, capture, server, client |
|
||||
| `README.dev.md` | how to build, test and hack on it |
|
||||
| `examples/README.md` | the demo that films the screen: `agent-eyes-demo.py` |
|
||||
|
||||
+15
-1
@@ -1,6 +1,7 @@
|
||||
# The flake's `checks` output. One file per check; this is only the wiring.
|
||||
#
|
||||
# unit -- pytest over tests/, against the nix/package.nix build
|
||||
# vm-mcp -- the MCP server over stdio, against a live broker
|
||||
# vm-basic -- nixosTest with a fake capture backend: module + wire contract
|
||||
# vm-hyprland -- nixosTest with the real compositor and grim
|
||||
# vm-sessions -- nixosTest with the real compositor and the session broker
|
||||
@@ -9,6 +10,7 @@
|
||||
# vm-pointer -- the lease, the driver, and a click the application saw
|
||||
# vm-keyboard -- the uploaded keymap, keyboard focus, and a decoded symbol
|
||||
# vm-keyboard-de -- the same check with sessions.keyboard.layout = "de"
|
||||
# vm-stream-firewall -- the stream's port in the guest's own running firewall
|
||||
#
|
||||
# What the guests need lives in checks/lib: `test-tools.nix` for the fake
|
||||
# capture and the contract asserter, `session-tools.nix` for the event
|
||||
@@ -31,6 +33,7 @@
|
||||
}:
|
||||
let
|
||||
hhstream = self.packages.${system}.hhstream;
|
||||
hhstream-mcp = self.packages.${system}.hhstream-mcp;
|
||||
hhsModule = self.nixosModules.default;
|
||||
testTools = pkgs.callPackage ./lib/test-tools.nix { };
|
||||
# The session checks take the same arguments; naming them once keeps a new
|
||||
@@ -41,7 +44,7 @@ let
|
||||
};
|
||||
in
|
||||
{
|
||||
unit = pkgs.callPackage ./unit.nix { inherit hhstream; };
|
||||
unit = pkgs.callPackage ./unit.nix { inherit hhstream hhstream-mcp; };
|
||||
|
||||
vm-basic = pkgs.callPackage ./vm-basic.nix {
|
||||
inherit hhstream hhsModule testTools;
|
||||
@@ -66,4 +69,15 @@ in
|
||||
vm-keyboard-de = pkgs.callPackage ./vm-keyboard.nix (
|
||||
sessionArgs // { keyboardLayout = "de"; }
|
||||
);
|
||||
|
||||
# Not a `sessionArgs` consumer: this one is about the module's own options,
|
||||
# not about the broker or the compositor (see the file's header).
|
||||
vm-stream-firewall = pkgs.callPackage ./vm-stream-firewall.nix {
|
||||
inherit hhstream hhsModule testTools;
|
||||
};
|
||||
|
||||
# The session machine again, plus `mcp.enable`, driven over stdio by a
|
||||
# JSON-RPC client the check writes itself. `sessionArgs` plus the one package
|
||||
# the others have no reason to carry.
|
||||
vm-mcp = pkgs.callPackage ./vm-mcp.nix (sessionArgs // { inherit hhstream-mcp; });
|
||||
}
|
||||
Executable
+223
@@ -0,0 +1,223 @@
|
||||
#!/usr/bin/env python3
|
||||
"""``hhs-mcp-call`` -- drive an MCP server over stdio from a shell.
|
||||
|
||||
What `checks/vm-mcp.nix` uses to talk to `hhstream-mcp` in the guest, and
|
||||
deliberately **not** the MCP SDK's own client: the SDK on both ends would agree
|
||||
with itself about a framing neither side had to get right. This is raw
|
||||
JSON-RPC, newline-delimited, written against the specification -- the same
|
||||
choice, and for the same reason, as `tests/assert_stream.py` being a second
|
||||
implementation of the frame contract.
|
||||
|
||||
One server process per invocation, which means every call re-does the
|
||||
`initialize` handshake. That is a feature here: the handshake is one of the
|
||||
things under test, and a client that did it once would prove it once.
|
||||
|
||||
hhs-mcp-call --initialize the handshake's own result
|
||||
hhs-mcp-call --list every tool, as JSON
|
||||
hhs-mcp-call --resources every resource and template
|
||||
hhs-mcp-call --read hhstream://sessions one resources/read
|
||||
hhs-mcp-call session_gc one call, no arguments
|
||||
hhs-mcp-call session_touch '{"id": "s-1"}' one call, arguments as JSON
|
||||
|
||||
``--server-arg`` is passed through to the server, which is how a check drives
|
||||
``--toolsets`` without a second program.
|
||||
|
||||
Always exits 0 when the server answered, whatever the answer was: a refusal is
|
||||
a result the test asserts on, not this program's failure. Exit 2 is "the
|
||||
server did not answer" -- it died, it timed out, or it sent something that is
|
||||
not JSON-RPC -- which is the one outcome no assertion should be able to mistake
|
||||
for a reply.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import signal
|
||||
import subprocess
|
||||
import sys
|
||||
from typing import Any
|
||||
|
||||
#: The protocol version this client speaks. Named rather than negotiated: a
|
||||
#: server that answers a different one is a thing the test should see.
|
||||
PROTOCOL_VERSION = "2025-06-18"
|
||||
|
||||
|
||||
def fail(message: str) -> None:
|
||||
print(f"hhs-mcp-call: {message}", file=sys.stderr)
|
||||
raise SystemExit(2)
|
||||
|
||||
|
||||
class Server:
|
||||
"""One ``hhstream-mcp`` process, spoken to over its stdin and stdout."""
|
||||
|
||||
def __init__(self, command: list[str], timeout: int) -> None:
|
||||
self.timeout = timeout
|
||||
# stderr is left alone on purpose: the server logs there, and in a
|
||||
# nixosTest that ends up in the build log beside the assertion that
|
||||
# failed, which is where it is wanted.
|
||||
self.process = subprocess.Popen(
|
||||
command,
|
||||
stdin=subprocess.PIPE,
|
||||
stdout=subprocess.PIPE,
|
||||
text=True,
|
||||
bufsize=1,
|
||||
)
|
||||
self.next_id = 0
|
||||
|
||||
def send(self, message: dict[str, Any]) -> None:
|
||||
assert self.process.stdin is not None
|
||||
self.process.stdin.write(json.dumps(message) + "\n")
|
||||
self.process.stdin.flush()
|
||||
|
||||
def read(self) -> dict[str, Any]:
|
||||
assert self.process.stdout is not None
|
||||
# An alarm rather than a poll loop: a server that never answers must
|
||||
# fail the check, not hang the test driver until its global timeout.
|
||||
signal.alarm(self.timeout)
|
||||
try:
|
||||
line = self.process.stdout.readline()
|
||||
except KeyboardInterrupt: # pragma: no cover -- the alarm handler
|
||||
fail(f"no answer within {self.timeout}s")
|
||||
raise
|
||||
finally:
|
||||
signal.alarm(0)
|
||||
if not line:
|
||||
fail(f"the server closed its stream (exit {self.process.poll()})")
|
||||
try:
|
||||
return json.loads(line)
|
||||
except json.JSONDecodeError:
|
||||
# The failure a stray `print` on stdout produces, named as such:
|
||||
# the tools run the CLI in process, and this is what it looks like
|
||||
# when something it printed reached the transport.
|
||||
fail(f"not JSON-RPC on the server's stdout: {line!r}")
|
||||
raise AssertionError("unreachable")
|
||||
|
||||
def request(self, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
|
||||
self.next_id += 1
|
||||
wanted = self.next_id
|
||||
self.send(
|
||||
{"jsonrpc": "2.0", "id": wanted, "method": method, "params": params or {}}
|
||||
)
|
||||
answer = self.read()
|
||||
if answer.get("id") != wanted:
|
||||
fail(f"answer for id {answer.get('id')!r}, expected {wanted}")
|
||||
if "error" in answer:
|
||||
# Printed as the result and exited 3, not `fail`ed: a resource read
|
||||
# has no `isError`, so a refusal arrives here -- and the checks
|
||||
# assert on *which* refusal. Exit 3 keeps it distinguishable from
|
||||
# exit 2, which is "the server did not answer at all".
|
||||
print(json.dumps({"error": answer["error"]}, indent=2, sort_keys=True))
|
||||
raise SystemExit(3)
|
||||
return answer["result"]
|
||||
|
||||
def initialize(self) -> dict[str, Any]:
|
||||
result = self.request(
|
||||
"initialize",
|
||||
{
|
||||
"protocolVersion": PROTOCOL_VERSION,
|
||||
"capabilities": {},
|
||||
"clientInfo": {"name": "hhs-mcp-call", "version": "0"},
|
||||
},
|
||||
)
|
||||
self.send({"jsonrpc": "2.0", "method": "notifications/initialized"})
|
||||
return result
|
||||
|
||||
def close(self) -> int:
|
||||
assert self.process.stdin is not None
|
||||
self.process.stdin.close()
|
||||
try:
|
||||
return self.process.wait(timeout=self.timeout)
|
||||
except subprocess.TimeoutExpired: # pragma: no cover
|
||||
self.process.kill()
|
||||
return -1
|
||||
|
||||
|
||||
def _alarm(signum, frame): # pragma: no cover -- raises into read()
|
||||
raise KeyboardInterrupt
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
parser = argparse.ArgumentParser(prog="hhs-mcp-call", description=__doc__)
|
||||
parser.add_argument(
|
||||
"--server",
|
||||
default="hhstream-mcp",
|
||||
help="the MCP server to spawn (default: %(default)s, from PATH)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--server-arg",
|
||||
action="append",
|
||||
default=[],
|
||||
metavar="ARG",
|
||||
help="an argument for the server itself; repeatable",
|
||||
)
|
||||
parser.add_argument("--timeout", type=int, default=120, metavar="SECONDS")
|
||||
parser.add_argument("--initialize", action="store_true", help="print the handshake result")
|
||||
parser.add_argument("--list", action="store_true", help="print the tool listing")
|
||||
parser.add_argument(
|
||||
"--resources",
|
||||
action="store_true",
|
||||
help="print the resource listing and the templates, as one object",
|
||||
)
|
||||
parser.add_argument("--read", metavar="URI", help="read one resource")
|
||||
parser.add_argument("tool", nargs="?", help="the tool to call")
|
||||
parser.add_argument("arguments", nargs="?", default="{}", help="its arguments, as JSON")
|
||||
args = parser.parse_args(argv)
|
||||
|
||||
signal.signal(signal.SIGALRM, _alarm)
|
||||
|
||||
try:
|
||||
arguments = json.loads(args.arguments)
|
||||
except json.JSONDecodeError as exc:
|
||||
fail(f"arguments are not JSON: {exc}")
|
||||
return 2
|
||||
if not isinstance(arguments, dict):
|
||||
fail("arguments must be a JSON object")
|
||||
|
||||
server = Server([args.server, *args.server_arg], args.timeout)
|
||||
try:
|
||||
handshake = server.initialize()
|
||||
if args.initialize:
|
||||
print(json.dumps(handshake, indent=2, sort_keys=True))
|
||||
return 0
|
||||
if args.list:
|
||||
print(json.dumps(server.request("tools/list"), indent=2, sort_keys=True))
|
||||
return 0
|
||||
if args.resources:
|
||||
# Both listings as one object, because they are two halves of one
|
||||
# question and a check that asked twice would pay two handshakes.
|
||||
print(
|
||||
json.dumps(
|
||||
{
|
||||
"resources": server.request("resources/list")["resources"],
|
||||
"resourceTemplates": server.request(
|
||||
"resources/templates/list"
|
||||
)["resourceTemplates"],
|
||||
},
|
||||
indent=2,
|
||||
sort_keys=True,
|
||||
)
|
||||
)
|
||||
return 0
|
||||
if args.read:
|
||||
print(
|
||||
json.dumps(
|
||||
server.request("resources/read", {"uri": args.read}),
|
||||
indent=2,
|
||||
sort_keys=True,
|
||||
)
|
||||
)
|
||||
return 0
|
||||
if not args.tool:
|
||||
fail("name a tool, or pass --list, --resources, --read or --initialize")
|
||||
result = server.request(
|
||||
"tools/call", {"name": args.tool, "arguments": arguments}
|
||||
)
|
||||
print(json.dumps(result, indent=2, sort_keys=True))
|
||||
return 0
|
||||
finally:
|
||||
server.close()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
+20
-2
@@ -16,6 +16,7 @@
|
||||
runCommand,
|
||||
python3,
|
||||
hhstream,
|
||||
hhstream-mcp,
|
||||
}:
|
||||
let
|
||||
# `xkbcommon` beside `pywayland`, and it is not optional: `tests/pointer/
|
||||
@@ -24,7 +25,19 @@ let
|
||||
# needs a level-three mask rather than Shift. A suite that could skip those
|
||||
# would let the unmappable-character path rot, which is the path that decides
|
||||
# whether a bad string types a prefix.
|
||||
pytestEnv = python3.withPackages (ps: [ ps.pytest ps.pywayland ps.xkbcommon ]);
|
||||
#
|
||||
# `mcp` beside them, for `tests/unit/test_mcp_server.py`. That file imports
|
||||
# the SDK on purpose and is not allowed to skip: the tool table itself is
|
||||
# stdlib-only and tested without it, but the step that turns the table into
|
||||
# `mcp.types.Tool` objects is where a malformed schema or a name the spec
|
||||
# refuses would show up, and a file that skipped when the SDK was absent
|
||||
# would be green in exactly the build where that mattered.
|
||||
pytestEnv = python3.withPackages (ps: [
|
||||
ps.pytest
|
||||
ps.pywayland
|
||||
ps.xkbcommon
|
||||
ps.mcp
|
||||
]);
|
||||
|
||||
# Only the suite itself, so an editor's droppings or a local .pytest_cache
|
||||
# cannot change the derivation's hash.
|
||||
@@ -61,11 +74,16 @@ runCommand "hhstream-unit"
|
||||
# point PYTHONPATH at what nix/package.nix installed. Importing it here rather
|
||||
# than letting pytest do it makes a packaging problem distinguishable from a
|
||||
# test failure.
|
||||
export PYTHONPATH=${hhstream}/${python3.sitePackages}
|
||||
export PYTHONPATH=${hhstream}/${python3.sitePackages}:${hhstream-mcp}/${python3.sitePackages}
|
||||
export PYTHONDONTWRITEBYTECODE=1
|
||||
export HOME=$PWD
|
||||
python3 -c 'import hhstream; print("testing hhstream", hhstream.__version__, "from", hhstream.__file__)'
|
||||
python3 -c 'import hhstreamd.ipc, hhstream_pointer; print("broker ipc client + pointer driver import")'
|
||||
# The second distribution, on the path beside the first. `tests/unit`'s
|
||||
# conftest adds `../src` to sys.path, which does not exist in this sandbox --
|
||||
# so here, as for `hhstream`, the import comes from what Nix installed, and a
|
||||
# packaging mistake is distinguishable from a test failure.
|
||||
python3 -c 'import hhstream_mcp.tools as t; print("mcp tool table:", len(t.TOOLS), "tools")'
|
||||
|
||||
set +e
|
||||
pytest suite \
|
||||
|
||||
@@ -0,0 +1,537 @@
|
||||
# checks.<system>.vm-mcp -- the MCP server over stdio, in a guest, against a
|
||||
# live broker and a real compositor.
|
||||
#
|
||||
# The same machine the other session checks use (`lib/session-machine.nix`),
|
||||
# plus `services.hyprland-headless-stream.mcp.enable = true` -- which is also
|
||||
# the first thing asserted, because "installing it" is the whole of that
|
||||
# option. Then `hhs-mcp-call` (`lib/mcp_client.py`) spawns `hhstream-mcp` as the
|
||||
# operator account and talks raw JSON-RPC to it: initialize, tools/list,
|
||||
# tools/call.
|
||||
#
|
||||
# WHAT THIS PROVES, AND WHAT IT DOES NOT.
|
||||
#
|
||||
# It proves the *surface*, both halves of it: the handshake completes over a
|
||||
# real pipe, all twenty-one tools and all eight resources are listed, a tool
|
||||
# call reaches the broker and comes back with the broker's own protocol object,
|
||||
# a resource read reaches it the same way, an image arrives as a blob with the
|
||||
# geometry the module configured, `--toolsets` actually narrows what is
|
||||
# offered, and a refusal arrives as a tool error (or, for a resource, a
|
||||
# protocol error) carrying the frozen exit code rather than as a success.
|
||||
#
|
||||
# It does not prove the compositor behaviour the other checks own, and it must
|
||||
# not be read as doing so. `vm-pointer` is where a click is shown to land in the
|
||||
# window it was aimed at; `vm-keyboard` is where a typed symbol is shown to be
|
||||
# decoded by a client from the keymap the driver uploaded. Here the victim is
|
||||
# `foot`, which ignores `$HHSTREAM_APP_ID` and so matches no container rule
|
||||
# (README.dev.md, known gap 4) -- so what the pointer and keyboard subtests
|
||||
# below assert is that the lease was granted and the driver accepted the
|
||||
# injection, which is the part the MCP layer is responsible for.
|
||||
#
|
||||
# The client is not the MCP SDK's, deliberately: the SDK on both ends would
|
||||
# agree with itself about a framing neither side had to get right. Same choice
|
||||
# as `tests/assert_stream.py` being a second implementation of the frame
|
||||
# contract, and for the same reason.
|
||||
#
|
||||
# Habits copied from the other session checks: every wait is bounded, each
|
||||
# subtest asserts once, and a failure dumps the compositor's diagnostics and
|
||||
# the broker's journal before it propagates.
|
||||
{
|
||||
testers,
|
||||
hhstream,
|
||||
hhstream-mcp,
|
||||
hhsModule,
|
||||
testTools,
|
||||
hyprland,
|
||||
foot,
|
||||
jq,
|
||||
grim,
|
||||
procps,
|
||||
coreutils,
|
||||
dejavu_fonts,
|
||||
width ? 1280,
|
||||
height ? 720,
|
||||
sessionUser ? "hermes",
|
||||
}:
|
||||
testers.runNixOSTest (
|
||||
{ pkgs, ... }:
|
||||
let
|
||||
tools = pkgs.callPackage ./lib/session-tools.nix { inherit hhstream; };
|
||||
guest = import ./lib/session-machine.nix {
|
||||
inherit
|
||||
hhsModule
|
||||
hhstream
|
||||
hyprland
|
||||
testTools
|
||||
foot
|
||||
jq
|
||||
procps
|
||||
grim
|
||||
coreutils
|
||||
dejavu_fonts
|
||||
;
|
||||
sessionTools = tools;
|
||||
};
|
||||
prelude = import ./lib/session-prelude.nix {
|
||||
inherit hhstream coreutils sessionUser;
|
||||
};
|
||||
|
||||
# The client, with a plain python3: it speaks JSON-RPC over a pipe and
|
||||
# imports nothing but the standard library, which is what makes it a second
|
||||
# implementation rather than the SDK talking to itself.
|
||||
client = pkgs.runCommandLocal "hhs-mcp-call" { } ''
|
||||
install -Dm755 ${./lib/mcp_client.py} $out/bin/hhs-mcp-call
|
||||
sed -i '1s|.*|#!${pkgs.python3}/bin/python3|' $out/bin/hhs-mcp-call
|
||||
$out/bin/hhs-mcp-call --help > /dev/null
|
||||
# It must refuse to invent a request rather than printing nothing: a
|
||||
# client that exits 0 having done nothing would make every subtest below
|
||||
# vacuous.
|
||||
if $out/bin/hhs-mcp-call --server ${coreutils}/bin/true; then
|
||||
echo "hhs-mcp-call succeeded against a server that says nothing" >&2
|
||||
exit 1
|
||||
fi
|
||||
'';
|
||||
in
|
||||
{
|
||||
name = "hhstream-vm-mcp";
|
||||
|
||||
globalTimeout = 1800;
|
||||
|
||||
nodes.machine = {
|
||||
imports = [
|
||||
(guest {
|
||||
inherit width height sessionUser;
|
||||
pointer = true;
|
||||
apps.foot = {
|
||||
exec = "${foot}/bin/foot";
|
||||
# The broker refuses unlisted arguments and this check passes none:
|
||||
# `foot` with no argv opens a window, which is all the victim has
|
||||
# to do.
|
||||
argsAllow = [ ];
|
||||
};
|
||||
})
|
||||
];
|
||||
|
||||
# The option under test. Installing the package IS the option, so the
|
||||
# first subtest asserts the binary is on PATH and nothing else had to
|
||||
# happen.
|
||||
services.hyprland-headless-stream.mcp = {
|
||||
enable = true;
|
||||
package = hhstream-mcp;
|
||||
};
|
||||
|
||||
environment.systemPackages = [ client ];
|
||||
};
|
||||
|
||||
testScript =
|
||||
prelude
|
||||
+ ''
|
||||
import base64
|
||||
import shlex
|
||||
|
||||
MCP = "${client}/bin/hhs-mcp-call"
|
||||
WIDTH = ${toString width}
|
||||
HEIGHT = ${toString height}
|
||||
|
||||
|
||||
def mcp(argv, timeout=180):
|
||||
"""`hhs-mcp-call …` as USER, parsed. Fails loudly if it printed no JSON."""
|
||||
|
||||
out = machine.succeed(as_user(f"{MCP} {argv}"), timeout=timeout)
|
||||
try:
|
||||
return json.loads(out)
|
||||
except json.JSONDecodeError:
|
||||
raise AssertionError(f"not JSON from `hhs-mcp-call {argv}`: {out!r}")
|
||||
|
||||
|
||||
def call(tool, arguments=None, timeout=180):
|
||||
"""One tools/call. Returns the CallToolResult as a dict."""
|
||||
|
||||
payload = json.dumps(arguments or {})
|
||||
return mcp(f"{tool} {shlex.quote(payload)}", timeout=timeout)
|
||||
|
||||
|
||||
def read(uri, timeout=180):
|
||||
"""One resources/read that must succeed. Returns its contents list."""
|
||||
|
||||
return mcp(f"--read {shlex.quote(uri)}", timeout=timeout)["contents"]
|
||||
|
||||
|
||||
def read_refused(uri, timeout=180):
|
||||
"""One resources/read that must NOT succeed. Returns the error object.
|
||||
|
||||
A resource read has no `isError`, so a refusal is a protocol error
|
||||
and the client exits 3 for it -- which is deliberately a different
|
||||
status from the 2 it uses for "the server did not answer", so this
|
||||
cannot pass because the server died.
|
||||
"""
|
||||
|
||||
status, out = machine.execute(
|
||||
as_user(f"{MCP} --read {shlex.quote(uri)}"), timeout=timeout
|
||||
)
|
||||
assert status == 3, f"expected a refusal (3) for {uri}, got {status}: {out}"
|
||||
return json.loads(out)["error"]
|
||||
|
||||
|
||||
def text_of(result):
|
||||
"""The text part of a CallToolResult, which is where the CLI's own
|
||||
output and (on a refusal) the remedy live."""
|
||||
|
||||
for block in result.get("content") or []:
|
||||
if block.get("type") == "text":
|
||||
return block["text"]
|
||||
raise AssertionError(f"no text content in {result!r}")
|
||||
|
||||
|
||||
def succeeded(tool, arguments=None, timeout=180):
|
||||
"""A call that must not be an error, with the reason printed if it is."""
|
||||
|
||||
result = call(tool, arguments, timeout=timeout)
|
||||
if result.get("isError"):
|
||||
print(f"----- {tool} returned an error -----")
|
||||
print(text_of(result))
|
||||
assert not result.get("isError"), f"{tool} failed: {text_of(result)}"
|
||||
return result
|
||||
|
||||
|
||||
start_all()
|
||||
bring_up("the compositor and broker")
|
||||
|
||||
with subtest("the as-user wrapper propagates exit status"):
|
||||
# Every assertion below reads machine.succeed through it, so a
|
||||
# wrapper that swallowed the status would make them all vacuous.
|
||||
machine.succeed(as_user(TRUE), timeout=120)
|
||||
machine.fail(as_user(FALSE), timeout=120)
|
||||
|
||||
with subtest("mcp.enable put the server on the system PATH"):
|
||||
# The whole of the module option: no unit, no socket, no state dir.
|
||||
path = machine.succeed(as_user("/run/current-system/sw/bin/sh -c 'command -v hhstream-mcp'")).strip()
|
||||
print(f"hhstream-mcp resolves to {path}")
|
||||
assert path.startswith("/run/current-system/sw/bin"), path
|
||||
machine.fail("systemctl is-active hhstream-mcp.service")
|
||||
|
||||
with subtest("the stdio handshake completes and names this server"):
|
||||
try:
|
||||
handshake = mcp("--initialize")
|
||||
print(json.dumps(handshake, indent=2)[:600])
|
||||
assert handshake["serverInfo"]["name"] == "hhstream", handshake
|
||||
assert handshake["capabilities"].get("tools") is not None, handshake
|
||||
# The two rules, in the instructions a client is handed once.
|
||||
instructions = handshake["instructions"]
|
||||
assert "`session_touch` is the ONLY" in instructions
|
||||
assert "POINTER lease" in instructions
|
||||
except Exception:
|
||||
dump("the mcp handshake")
|
||||
raise
|
||||
|
||||
with subtest("tools/list carries every acting verb, with its annotations"):
|
||||
listed = mcp("--list")["tools"]
|
||||
names = sorted(tool["name"] for tool in listed)
|
||||
print(f"{len(names)} tools: {', '.join(names)}")
|
||||
assert len(names) == 21, names
|
||||
for expected in (
|
||||
"shot", "record", "run",
|
||||
"session_start", "session_touch", "session_kill",
|
||||
"pointer_acquire", "pointer_click", "keyboard_type",
|
||||
):
|
||||
assert expected in names, f"{expected} is missing from the listing"
|
||||
# The read-only verbs are resources now and must not be here.
|
||||
for moved in ("status", "session_list", "session_status",
|
||||
"session_logs", "pointer_state"):
|
||||
assert moved not in names, f"{moved} is a resource, not a tool"
|
||||
by_name = {tool["name"]: tool for tool in listed}
|
||||
assert by_name["shot"]["annotations"]["readOnlyHint"] is True
|
||||
assert by_name["session_kill"]["annotations"]["destructiveHint"] is True
|
||||
# The rules have to be on the tool, not only in the instructions.
|
||||
assert "session_touch" in by_name["session_gc"]["description"]
|
||||
assert "POINTER lease" in by_name["keyboard_type"]["description"]
|
||||
|
||||
with subtest("resources/list and the templates carry the read-only half"):
|
||||
both = mcp("--resources")
|
||||
uris = sorted(r["uri"] for r in both["resources"])
|
||||
templates = sorted(t["uriTemplate"] for t in both["resourceTemplates"])
|
||||
print(f"resources: {', '.join(uris)}")
|
||||
print(f"templates: {', '.join(templates)}")
|
||||
assert uris == [
|
||||
"hhstream://containers",
|
||||
"hhstream://pointer",
|
||||
"hhstream://screen",
|
||||
"hhstream://sessions",
|
||||
"hhstream://status",
|
||||
], uris
|
||||
assert templates == [
|
||||
"hhstream://outputs/{name}",
|
||||
"hhstream://sessions/{id}/logs{?lines}",
|
||||
"hhstream://sessions/{id}{?events}",
|
||||
], templates
|
||||
by_uri = {r["uri"]: r for r in both["resources"]}
|
||||
assert by_uri["hhstream://status"]["mimeType"] == "text/plain"
|
||||
assert by_uri["hhstream://sessions"]["mimeType"] == "application/json"
|
||||
# The idle-clock rule is on the reads it applies to.
|
||||
assert "does NOT reset" in by_uri["hhstream://sessions"]["description"]
|
||||
|
||||
with subtest("a resource read reaches the broker and returns its object"):
|
||||
try:
|
||||
contents = read("hhstream://sessions")
|
||||
assert len(contents) == 1, contents
|
||||
assert contents[0]["mimeType"] == "application/json"
|
||||
# The body is the CLI's own `--json` output, unmodified.
|
||||
listing = json.loads(contents[0]["text"])
|
||||
assert listing["ok"] is True, listing
|
||||
assert "sessions" in listing, listing
|
||||
except Exception:
|
||||
dump("reading hhstream://sessions")
|
||||
raise
|
||||
|
||||
with subtest("the status resource answers without the broker's help"):
|
||||
# It reads the compositor's units and the frame socket, not the
|
||||
# control socket -- which is why it is the thing to read first.
|
||||
contents = read("hhstream://status")
|
||||
assert contents[0]["mimeType"] == "text/plain"
|
||||
report = contents[0]["text"]
|
||||
print(report)
|
||||
assert "hyprland-headless.service" in report
|
||||
assert "frame:" in report
|
||||
|
||||
with subtest("a session started over mcp is the broker's own session"):
|
||||
try:
|
||||
started = succeeded("session_start", {"app": "foot"}, timeout=300)
|
||||
session_id = started["structuredContent"]["id"]
|
||||
print(f"started {session_id}")
|
||||
assert text_of(started).startswith(f"session id: {session_id}")
|
||||
# The broker is the authority on whether that happened, so it
|
||||
# is asked directly rather than through the server under test.
|
||||
listing = cli_json("list --json")
|
||||
assert session_id in [s["id"] for s in listing["sessions"]], listing
|
||||
except Exception:
|
||||
dump("session_start over mcp")
|
||||
raise
|
||||
|
||||
with subtest("reading a session does not reset its clock; touching it does"):
|
||||
# The rule the whole surface repeats, measured rather than asserted
|
||||
# about: two reads of the resource, then the tool, and the deadline
|
||||
# has to move only for the tool.
|
||||
try:
|
||||
def expires_in():
|
||||
body = json.loads(read(f"hhstream://sessions/{session_id}")[0]["text"])
|
||||
return body["session"]["expires_in_s"]
|
||||
|
||||
first = expires_in()
|
||||
second = expires_in()
|
||||
assert second <= first, (
|
||||
f"reading hhstream://sessions/{session_id} reset the idle "
|
||||
f"clock: {first} -> {second}"
|
||||
)
|
||||
touched = succeeded("session_touch", {"id": session_id})
|
||||
assert (
|
||||
touched["structuredContent"]["session"]["expires_in_s"] >= second
|
||||
), touched
|
||||
except Exception:
|
||||
dump("the idle clock over mcp", session_id)
|
||||
raise
|
||||
|
||||
with subtest("a session's logs read through its template, with a query"):
|
||||
try:
|
||||
contents = read(f"hhstream://sessions/{session_id}/logs?lines=5")
|
||||
body = json.loads(contents[0]["text"])
|
||||
assert body["ok"] is True, body
|
||||
assert "lines" in body, body
|
||||
print(f"{len(body['lines'])} line(s) of {session_id}'s own output")
|
||||
except Exception:
|
||||
dump("reading a session's logs", session_id)
|
||||
raise
|
||||
|
||||
with subtest("shot returns image content, sized as the publisher serves it"):
|
||||
# MEASURED, and not what this check first assumed: the frame is
|
||||
# 2560x720 on a guest configured for 1280x720. The publisher's
|
||||
# default capture is `grim -t png -` with no `-o`, which takes the
|
||||
# whole compositor layout -- and with containers on (the module's
|
||||
# default) a session's own output sits beside the main one, so one
|
||||
# session doubles the width. The geometry the module configures is
|
||||
# the geometry of an *output*, which is what the next subtest
|
||||
# captures by name.
|
||||
try:
|
||||
shot = succeeded("shot", timeout=300)
|
||||
kinds = [block["type"] for block in shot["content"]]
|
||||
assert kinds == ["text", "image"], kinds
|
||||
image = shot["content"][1]
|
||||
frame = base64.b64decode(image["data"])
|
||||
print(f"{image['mimeType']}, {len(frame)} bytes: {text_of(shot)}")
|
||||
assert image["mimeType"] in ("image/png", "image/jpeg")
|
||||
# The media type is read off the bytes, never off the extension
|
||||
# this server asked the CLI for -- so the two must agree.
|
||||
magic = {"image/png": b"\x89PNG", "image/jpeg": b"\xff\xd8\xff"}
|
||||
assert frame.startswith(magic[image["mimeType"]]), frame[:8]
|
||||
reported = shot["structuredContent"]
|
||||
assert reported["height"] == HEIGHT, reported
|
||||
assert reported["width"] >= WIDTH, reported
|
||||
assert reported["bytes"] == len(frame), reported
|
||||
assert len(frame) > 1024, "a frame that small is not a desktop"
|
||||
except Exception:
|
||||
dump("shot over mcp", session_id)
|
||||
raise
|
||||
|
||||
with subtest("the container is listed as a resource and reconciled as a tool"):
|
||||
# The pair that has to stay split: the LIST only reads the record,
|
||||
# so it is a resource; asking where the window is *now* re-reads the
|
||||
# compositor and writes the answer back, so it is a tool. Both are
|
||||
# asked here, and they have to agree about the output's name.
|
||||
try:
|
||||
listed = json.loads(read("hhstream://containers")[0]["text"])
|
||||
assert listed["ok"] is True, listed
|
||||
from_resource = [
|
||||
c["output"] for c in (listed.get("containers") or [])
|
||||
]
|
||||
print(f"containers resource reports: {from_resource}")
|
||||
assert f"hh-{session_id}" in from_resource, listed
|
||||
|
||||
reconciled = succeeded("session_container", {"id": session_id})
|
||||
output = reconciled["structuredContent"]["container"]["output"]
|
||||
assert output == f"hh-{session_id}", reconciled
|
||||
except Exception:
|
||||
dump("the container, both ways", session_id)
|
||||
raise
|
||||
|
||||
with subtest("one output's frame reads as a blob, at exactly its own size"):
|
||||
# The resource that is an image, and the one place the configured
|
||||
# geometry is the geometry: `hhstream://screen` is the whole layout.
|
||||
try:
|
||||
output = f"hh-{session_id}"
|
||||
contents = read(f"hhstream://outputs/{output}", timeout=300)
|
||||
assert len(contents) == 1, contents
|
||||
blob = contents[0]
|
||||
assert blob["mimeType"] in ("image/png", "image/jpeg"), blob
|
||||
assert "text" not in blob, "an image must not arrive as text"
|
||||
frame = base64.b64decode(blob["blob"])
|
||||
print(f"{output}: {blob['mimeType']}, {len(frame)} bytes")
|
||||
assert frame[:4] in (b"\x89PNG", b"\xff\xd8\xff\xe0")
|
||||
assert len(frame) > 1024, "a frame that small is not a desktop"
|
||||
|
||||
# And the tool agrees about the size, which is what makes the
|
||||
# pointer's normalised coordinates meaningful.
|
||||
framed = succeeded("shot", {"output": output}, timeout=300)
|
||||
reported = framed["structuredContent"]
|
||||
print(text_of(framed))
|
||||
assert (reported["width"], reported["height"]) == (WIDTH, HEIGHT), reported
|
||||
except Exception:
|
||||
dump("reading an output's frame", session_id)
|
||||
raise
|
||||
|
||||
with subtest("the pointer lease is granted, used and given back"):
|
||||
try:
|
||||
acquired = succeeded("pointer_acquire", {"id": session_id})
|
||||
lease = acquired["structuredContent"]["lease_id"]
|
||||
print(f"lease {lease}: {text_of(acquired).splitlines()[0]}")
|
||||
assert text_of(acquired).startswith(f"lease_id: {lease}")
|
||||
|
||||
# Every gesture takes the lease as an explicit argument: the
|
||||
# server caches nothing, which is what makes a transcript of
|
||||
# tool calls readable.
|
||||
succeeded("pointer_move", {"id": session_id, "lease": lease, "to": [0.5, 0.5]})
|
||||
succeeded("pointer_click", {"id": session_id, "lease": lease})
|
||||
succeeded("keyboard_type", {"id": session_id, "lease": lease, "text": "hello"})
|
||||
typed = succeeded(
|
||||
"keyboard_key", {"id": session_id, "lease": lease, "name": "Return"}
|
||||
)
|
||||
assert typed["structuredContent"]["ok"] is True, typed
|
||||
|
||||
released = succeeded("pointer_release", {"id": session_id, "lease": lease})
|
||||
assert released["structuredContent"]["ok"] is True, released
|
||||
# And the broker agrees that nobody holds it now.
|
||||
assert cli_json("pointer state --json")["holder"] is None
|
||||
except Exception:
|
||||
dump("the pointer lease over mcp", session_id)
|
||||
raise
|
||||
|
||||
with subtest("a gesture after the release is exit 9 and says to acquire"):
|
||||
# The frozen NO_LEASE code, arriving as a tool error an agent can
|
||||
# act on rather than as a success with a sad message in it.
|
||||
refused = call("pointer_click", {"id": session_id, "lease": lease})
|
||||
assert refused["isError"] is True, refused
|
||||
assert refused["structuredContent"]["exit_code"] == 9, refused
|
||||
said = text_of(refused)
|
||||
print(said.splitlines()[0])
|
||||
assert "exit 9 (NO_LEASE)" in said
|
||||
assert "pointer_acquire" in said
|
||||
|
||||
with subtest("an unknown session is exit 3 from a tool, not a success"):
|
||||
refused = call("session_touch", {"id": "no-such-session"})
|
||||
assert refused["isError"] is True, refused
|
||||
assert refused["structuredContent"]["exit_code"] == 3, refused
|
||||
assert "hhstream://sessions" in text_of(refused)
|
||||
|
||||
with subtest("a refused read is a protocol error carrying the same remedy"):
|
||||
# A resources/read has no `isError`, so this is the one place the
|
||||
# refusal has to travel as an error -- with the exit code intact,
|
||||
# or an agent cannot tell "no such session" from "broker down".
|
||||
error = read_refused("hhstream://sessions/no-such-session")
|
||||
print(error["message"].splitlines()[0])
|
||||
assert error["data"]["exit_code"] == 3, error
|
||||
assert error["data"]["error"] == "no_such_session", error
|
||||
assert "exit 3 (NO_SUCH_SESSION)" in error["message"]
|
||||
|
||||
with subtest("a uri this server does not serve is refused without running anything"):
|
||||
error = read_refused("hhstream://nonsense")
|
||||
assert "no resource at" in error["message"], error
|
||||
# And an undeclared query parameter, which the routing refuses for
|
||||
# the reason every tool schema sets additionalProperties: false.
|
||||
error = read_refused("hhstream://pointer?id=x")
|
||||
assert "accepts: none" in error["message"], error
|
||||
|
||||
with subtest("an argument the schema refuses never reaches the broker"):
|
||||
# No `lease`, so the server's own schema refuses before an argv list
|
||||
# exists. The CLI is not run at all, which is the point.
|
||||
refused = call("keyboard_type", {"id": session_id, "text": "x"})
|
||||
assert refused["isError"] is True, refused
|
||||
assert "lease" in text_of(refused), refused
|
||||
|
||||
with subtest("--toolsets narrows the tools and leaves the resources alone"):
|
||||
# The flag exists because a tool listing is a budget. What it must
|
||||
# not do is take the host's context away with it.
|
||||
narrowed = json.loads(
|
||||
machine.succeed(
|
||||
as_user(f"{MCP} --server-arg=--toolsets=keyboard --list"),
|
||||
timeout=180,
|
||||
)
|
||||
)["tools"]
|
||||
names = sorted(tool["name"] for tool in narrowed)
|
||||
print(f"--toolsets keyboard offers: {', '.join(names)}")
|
||||
assert names == [
|
||||
"keyboard_down", "keyboard_key", "keyboard_type", "keyboard_up",
|
||||
], names
|
||||
|
||||
still_there = json.loads(
|
||||
machine.succeed(
|
||||
as_user(f"{MCP} --server-arg=--toolsets=keyboard --resources"),
|
||||
timeout=180,
|
||||
)
|
||||
)
|
||||
assert len(still_there["resources"]) == 5, still_there
|
||||
assert len(still_there["resourceTemplates"]) == 3, still_there
|
||||
|
||||
# And a tool outside the selection must be unreachable, not merely
|
||||
# unlisted, or the flag is cosmetic.
|
||||
refused = json.loads(
|
||||
machine.succeed(
|
||||
as_user(
|
||||
f"{MCP} --server-arg=--toolsets=keyboard session_kill "
|
||||
+ shlex.quote(json.dumps({"id": session_id}))
|
||||
),
|
||||
timeout=180,
|
||||
)
|
||||
)
|
||||
assert refused["isError"] is True, refused
|
||||
assert "without its toolset" in text_of(refused), refused
|
||||
|
||||
with subtest("kill over mcp ends the session the broker was tracking"):
|
||||
try:
|
||||
killed = succeeded("session_kill", {"id": session_id}, timeout=300)
|
||||
print(text_of(killed))
|
||||
assert killed["structuredContent"]["ok"] is True, killed
|
||||
live = [s["id"] for s in cli_json("list --json")["sessions"]]
|
||||
assert session_id not in live, live
|
||||
except Exception:
|
||||
dump("session_kill over mcp", session_id)
|
||||
raise
|
||||
'';
|
||||
}
|
||||
)
|
||||
@@ -0,0 +1,243 @@
|
||||
# checks.<system>.vm-stream-firewall -- the stream's port, and only that port.
|
||||
#
|
||||
# `sessions.stream.openFirewall` is the one part of the session-stream web app
|
||||
# that a machine declares before the app has a unit (it is the piece of
|
||||
# docs/plans/2026-10-04-session-stream-webapp.md §3 that does not need the
|
||||
# broker), so it is the one part worth gating on its own.
|
||||
#
|
||||
# The option's effect is a firewall rule, and a rule is only a rule once the
|
||||
# firewall has loaded it -- so this boots the module rather than evaluating it
|
||||
# and reading `config.networking.firewall.allowedTCPPorts` back. A test that
|
||||
# reads the option out of the evaluation proves the option is plumbed; this one
|
||||
# asks the running firewall, and then asks it from *outside* the guest, which
|
||||
# is the only place a firewall exists for.
|
||||
#
|
||||
# Four things about the shape are deliberate:
|
||||
#
|
||||
# * **A second machine is the peer.** Nothing outside a guest can reach it
|
||||
# except another guest: the test driver runs on the host and is not on the
|
||||
# test VLAN, so a probe from the driver fails whether the port is open or
|
||||
# not. The peer is a bare machine on the same VLAN with no module on it --
|
||||
# a peer running the module would be testing the machine against itself.
|
||||
# * The configured port is **not** the module's default (9123, with 9988 as
|
||||
# the default it must ignore). The interesting failure is an option that
|
||||
# opens its own default whatever it is set to, and a check that configures
|
||||
# 9988 cannot see it.
|
||||
# * A listener is put on the unopened neighbour too, so "refused" means the
|
||||
# firewall refused rather than nothing being there to connect to. Both
|
||||
# listeners answer on loopback inside the guest first.
|
||||
# * The address the peer probes is read out of the guest instead of assumed,
|
||||
# because a check that guesses an interface name is testing the guess -- and
|
||||
# the guest carries two addresses (the qemu NAT one and the test VLAN's),
|
||||
# only one of which the peer can reach.
|
||||
{
|
||||
testers,
|
||||
hhstream,
|
||||
testTools,
|
||||
hhsModule,
|
||||
python3,
|
||||
curl,
|
||||
# The port the module is told to open; one beside it that it is not; and the
|
||||
# module's own default, which must not appear at all.
|
||||
configuredPort ? 9123,
|
||||
unopenedPort ? 9124,
|
||||
defaultPort ? 9988,
|
||||
}:
|
||||
testers.runNixOSTest {
|
||||
name = "hhstream-vm-stream-firewall";
|
||||
|
||||
# Two guests on a two-core machine is slower than one; cap it so a hang is a
|
||||
# failure rather than a wedged builder.
|
||||
globalTimeout = 1800;
|
||||
|
||||
nodes.machine = {
|
||||
# gpu-session.nix is what makes the compositor able to start at all; this
|
||||
# check is not about the compositor, but `sessions.stream` lives under a
|
||||
# module that boots one, and a machine kept from starting its own units is
|
||||
# not the machine anyone runs.
|
||||
imports = [ hhsModule ./lib/gpu-session.nix ];
|
||||
|
||||
services.hyprland-headless-stream = {
|
||||
enable = true;
|
||||
# The module declares `package` with no default (see README.dev.md), so
|
||||
# the test has to supply the flake's build.
|
||||
package = hhstream;
|
||||
frameRate = 30;
|
||||
outputs = [
|
||||
{
|
||||
width = 1280;
|
||||
height = 720;
|
||||
refresh = 30;
|
||||
}
|
||||
];
|
||||
# The fake capture, as in vm-basic: the compositor's own frames are not
|
||||
# this check's subject, and a real `grim` here would only add minutes of
|
||||
# software rendering to it.
|
||||
captureCommand = [
|
||||
"${testTools}/bin/hhs-fake-capture"
|
||||
"--width"
|
||||
"1280"
|
||||
"--height"
|
||||
"720"
|
||||
];
|
||||
|
||||
sessions.stream = {
|
||||
port = configuredPort;
|
||||
# Not a loopback address, because the module refuses that pairing with
|
||||
# `openFirewall` on: opening a port nothing can reach is a hole with no
|
||||
# service behind it (see the assertion in nix/module.nix).
|
||||
bind = "0.0.0.0";
|
||||
openFirewall = true;
|
||||
};
|
||||
};
|
||||
|
||||
# Two listeners, each bound on every interface: the configured port and a
|
||||
# neighbour the module was never told about. They exist so that a refusal
|
||||
# out here is the firewall's doing rather than an empty port.
|
||||
systemd.services.probe-configured = {
|
||||
wantedBy = [ "multi-user.target" ];
|
||||
serviceConfig.ExecStart = "${python3}/bin/python3 -m http.server ${toString configuredPort}";
|
||||
};
|
||||
|
||||
systemd.services.probe-unopened = {
|
||||
wantedBy = [ "multi-user.target" ];
|
||||
serviceConfig.ExecStart = "${python3}/bin/python3 -m http.server ${toString unopenedPort}";
|
||||
};
|
||||
|
||||
environment.systemPackages = [
|
||||
# `curl` is the loopback probe; python3 is the listeners themselves.
|
||||
python3
|
||||
curl
|
||||
];
|
||||
|
||||
virtualisation = {
|
||||
memorySize = 2048;
|
||||
cores = 2;
|
||||
diskSize = 4096;
|
||||
graphics = false;
|
||||
# The VLAN the peer is on. Without it the two machines share nothing but
|
||||
# the driver's console, and "outside" stops existing.
|
||||
vlans = [ 1 ];
|
||||
};
|
||||
};
|
||||
|
||||
# The peer: a bare machine on the same VLAN, no module, no compositor. Its
|
||||
# whole job is to fail to reach one port and succeed on another.
|
||||
nodes.peer = {
|
||||
environment.systemPackages = [ curl ];
|
||||
|
||||
virtualisation = {
|
||||
memorySize = 1024;
|
||||
cores = 1;
|
||||
vlans = [ 1 ];
|
||||
};
|
||||
};
|
||||
|
||||
testScript = ''
|
||||
CONFIGURED = ${toString configuredPort}
|
||||
UNOPENED = ${toString unopenedPort}
|
||||
DEFAULT = ${toString defaultPort}
|
||||
|
||||
|
||||
def dump(label):
|
||||
print(f"########## diagnostics: {label} ##########")
|
||||
for cmd in (
|
||||
"systemctl --no-pager -l status firewall.service",
|
||||
"systemctl --no-pager -l status probe-configured.service probe-unopened.service",
|
||||
"nixos-firewall-tool show",
|
||||
"ip -4 -o addr show",
|
||||
):
|
||||
status, out = machine.execute(cmd, timeout=60)
|
||||
print(out)
|
||||
print("########## end diagnostics ##########")
|
||||
|
||||
|
||||
def peer_reaches(address, port, timeout=8):
|
||||
"""Ask the peer to open the port: out there, a firewall is a firewall."""
|
||||
status, out = peer.execute(
|
||||
f"curl -sS -f -o /dev/null --max-time {timeout} http://{address}:{port}/",
|
||||
timeout=timeout + 10,
|
||||
)
|
||||
return status == 0
|
||||
|
||||
|
||||
start_all()
|
||||
|
||||
# Every global address the machine has, waited for and then read off the
|
||||
# machine rather than assumed: a bare test machine carries two (the qemu NAT
|
||||
# one and the test VLAN's), and only one of them is a path the peer can
|
||||
# take.
|
||||
#
|
||||
# The wait is not decoration. Addresses appear a moment after `start_all()`
|
||||
# returns, and reading too early yields an empty list -- which reads as "the
|
||||
# peer can reach nothing" rather than as "asked a second too soon".
|
||||
machine.wait_until_succeeds(
|
||||
"ip -4 -o addr show scope global | grep -q ' inet '", timeout=90
|
||||
)
|
||||
addresses = []
|
||||
for line in machine.succeed("ip -4 -o addr show scope global").splitlines():
|
||||
# "2: eth0 inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic ..."
|
||||
fields = line.split()
|
||||
if len(fields) >= 4 and fields[2] == "inet":
|
||||
addresses.append(fields[3].split("/")[0])
|
||||
print(f"the machine's addresses: {addresses}")
|
||||
assert addresses, "the machine reported no global address to probe"
|
||||
|
||||
with subtest("a machine with a stream declared is still a machine that boots"):
|
||||
try:
|
||||
machine.wait_for_unit("hyprland-headless.service", timeout=120)
|
||||
machine.wait_for_unit("hyprland-headless-stream.service", timeout=120)
|
||||
except Exception:
|
||||
dump("the module's own units did not come up")
|
||||
raise
|
||||
|
||||
with subtest("the running firewall accepts the configured port, and not the default"):
|
||||
try:
|
||||
machine.wait_for_unit("firewall.service")
|
||||
rules = machine.succeed("nixos-firewall-tool show")
|
||||
print(rules)
|
||||
except Exception:
|
||||
dump("the firewall did not come up")
|
||||
raise
|
||||
assert f"dpt:{CONFIGURED}" in rules, (
|
||||
f"the firewall does not accept {CONFIGURED}: the option did not reach "
|
||||
f"the rule set"
|
||||
)
|
||||
assert f"dpt:{DEFAULT}" not in rules, (
|
||||
f"the firewall accepts {DEFAULT}: the module opened its own default "
|
||||
f"port instead of the configured one"
|
||||
)
|
||||
|
||||
with subtest("both probe listeners are up and answer inside the guest"):
|
||||
try:
|
||||
machine.wait_for_unit("probe-configured.service", timeout=60)
|
||||
machine.wait_for_unit("probe-unopened.service", timeout=60)
|
||||
for port in (CONFIGURED, UNOPENED):
|
||||
machine.succeed(f"curl -sS -f -o /dev/null http://127.0.0.1:{port}/")
|
||||
except Exception:
|
||||
dump("a probe listener did not come up")
|
||||
raise
|
||||
|
||||
with subtest("the peer reaches the configured port"):
|
||||
reached = [a for a in addresses if peer_reaches(a, CONFIGURED)]
|
||||
print(f"the peer reached {CONFIGURED} on: {reached}")
|
||||
if not reached:
|
||||
dump(f"the peer could not reach {CONFIGURED} on any of {addresses}")
|
||||
raise AssertionError(
|
||||
f"{CONFIGURED} is accepted in the rule set but the peer cannot reach "
|
||||
f"it on any address the machine has ({addresses})"
|
||||
)
|
||||
|
||||
with subtest("and is refused on the port the module never opened"):
|
||||
# On the same addresses that just answered for the configured port, so
|
||||
# the refusal is the firewall's doing and not a missing route.
|
||||
for address in reached:
|
||||
if peer_reaches(address, UNOPENED):
|
||||
dump(f"the peer reached {UNOPENED} on {address}")
|
||||
raise AssertionError(
|
||||
f"the peer reached {UNOPENED} on {address}, a port the module was "
|
||||
f"never told to open: the firewall is letting through more than "
|
||||
f"the option names"
|
||||
)
|
||||
'';
|
||||
}
|
||||
+33
-1
@@ -32,9 +32,18 @@
|
||||
│ AF_UNIX control.sock, mode 0660
|
||||
▼
|
||||
hhstream session ... (the CLI an agent drives)
|
||||
▲
|
||||
│ in-process: argv in, exit code out
|
||||
│
|
||||
┌────────────┴──────────────┐
|
||||
│ hhstream-mcp │ spawned per client, stdio only
|
||||
│ 21 tools (the acts) │◀─── an MCP client's JSON-RPC
|
||||
│ 8 resources (the state)│
|
||||
└───────────────────────────┘
|
||||
```
|
||||
|
||||
Five pieces, deliberately separate:
|
||||
Five pieces, deliberately separate, and a sixth that is deliberately not a
|
||||
piece at all:
|
||||
|
||||
1. **The compositor** (`Hyprland`, unchanged upstream) renders into virtual
|
||||
outputs. It knows nothing about frames on a socket.
|
||||
@@ -53,6 +62,29 @@ Five pieces, deliberately separate:
|
||||
a separate process because a Wayland client needs its own connection and a
|
||||
driver blocked on the compositor must not stall session lifecycle.
|
||||
|
||||
And the sixth, which is a *shim* and not a layer:
|
||||
|
||||
6. **The MCP server** (`hhstream-mcp`, `docs/CONTRACT-mcp.md`) is the CLI with a
|
||||
Model Context Protocol surface on it, so an agent reads state by URI and
|
||||
acts by calling tools instead of writing command lines. It is drawn above
|
||||
the CLI rather than beside the broker because that is where it sits: every
|
||||
tool and every resource builds the argv list the CLI's parser takes and runs
|
||||
the CLI's own handler **in the same process**, and it is the one component
|
||||
here that owns no state at all — not even the pointer lease, which is an
|
||||
explicit argument on every gesture tool. Add it to the diagram's list of
|
||||
things that can go wrong and nothing new appears: every failure it reports
|
||||
is the CLI's or the broker's, carrying their exit code.
|
||||
|
||||
The split between its two halves is *who decides*, not what it costs. A
|
||||
resource is the host's to include (`hhstream://sessions` is state anyone may
|
||||
want in context); a tool is the model's to call (`session_kill` is a
|
||||
decision). That is why `shot` is both — a tool because deciding to look is
|
||||
an act, and `hhstream://screen` because a frame is also just state.
|
||||
|
||||
It is also the only part with a third-party dependency (the `mcp` SDK),
|
||||
which is why it is a separate derivation (`nix/mcp.nix`) and why
|
||||
`packages.hhstream` — the compositor's own units — keeps the closure it had.
|
||||
|
||||
## Why containers are outputs
|
||||
|
||||
A session's container is a headless **output**, not just a workspace, and the
|
||||
|
||||
@@ -0,0 +1,382 @@
|
||||
# CONTRACT — the MCP server (mcp-v2)
|
||||
|
||||
This file is the interface of `hhstream-mcp`: the resource URIs, the tool names,
|
||||
the arguments each takes, what comes back, and which of the CLI's exit codes
|
||||
arrives as which kind of MCP error. It is the sibling of `docs/CONTRACT.md` (the
|
||||
frame socket's wire format) and `docs/CONTRACT-sessions.md` (the broker, the
|
||||
containers and the input lease).
|
||||
|
||||
**Immutable without a version bump.** An agent that has learned these names and
|
||||
these argument shapes is a consumer like any other, and renaming a tool breaks
|
||||
it exactly as renaming a wire verb would.
|
||||
|
||||
Version: mcp-v2 (2026-10-11). v1 was the first freeze and lasted one day.
|
||||
|
||||
**v2 is a breaking change, and the only one: the verbs that merely read are
|
||||
resources now, not tools.**
|
||||
|
||||
| § | Change | Why |
|
||||
| --- | --- | --- |
|
||||
| §3, §4 | `status`, `session_list`, `session_status`, `session_logs` and `pointer_state` are **removed from the tool list** and are `hhstream://…` resources instead. 26 tools became 21. | The protocol's own split. A resource is *application*-controlled context — the host decides what to put in front of the model — and "what is on this machine right now" is the host's question. A tool is *model*-controlled: an act the model chooses. Nothing in those five acts. |
|
||||
| §4 | Eight resources: five fixed, three templates, with query parameters for the arguments the verbs took. | A resource read takes nothing but a URI, so `--lines` becomes `?lines=`. Only declared parameters are accepted. |
|
||||
| §5 | A refused resource read is a **protocol error** carrying the same remedy a tool error would have. | `CallToolResult` has `isError`; `ReadResourceResult` has nothing. Returning the broker's failure object as the body would make "no such session" read as a successful read of a session. |
|
||||
| §3 | `--toolsets` selects which families are listed as tools. | A tool listing is a budget. MCP has no grouping primitive — the `Tool` object has nowhere to put one — so the only lever is which tools the *server* lists, chosen at launch. |
|
||||
|
||||
What did **not** move, and the reasons are the interesting part:
|
||||
|
||||
* **`shot` and `record` are still tools**, though neither changes the desktop.
|
||||
Capturing is an act at a moment: an agent in a loop has to be able to decide
|
||||
to look *now*, and in many clients a resource is something a person attaches
|
||||
rather than something a model can fetch on its own initiative. The same frames
|
||||
are *also* readable as `hhstream://screen` and `hhstream://outputs/{name}`,
|
||||
for a host that wants to put one in context itself.
|
||||
* **`session_container` is still a tool**, for a harder reason: with an id the
|
||||
CLI runs `container.reconcile`, which re-reads the compositor and writes the
|
||||
record back. It is not a read at all. Only the no-id form is a resource
|
||||
(`hhstream://containers`). A resource read must never write.
|
||||
|
||||
## 0. What this is, and what it is not
|
||||
|
||||
It is a **shim**. Each tool and each resource builds the argv list the `hhstream`
|
||||
CLI's own parser takes, hands it to the CLI's own handler **in this process**,
|
||||
and maps what came back. Nothing in it decides anything:
|
||||
|
||||
| Rule | Whose it is |
|
||||
| --- | --- |
|
||||
| the idle clock, and that only `touch` resets it | the broker |
|
||||
| the pointer lease: who holds it, its TTL, what it lifts | the broker |
|
||||
| the allowlist, and which arguments an app may be given | the broker's policy |
|
||||
| the exit-code table | `docs/CONTRACT-sessions.md` §4 |
|
||||
| the refusal messages (`reason`, `hint`) | the CLI and the broker |
|
||||
| coordinate normalisation, the scroll bound, the type cap | the broker and the driver |
|
||||
|
||||
What this layer owns is the argv list, the routing of a URI to one of them, the
|
||||
mapping of a result to MCP content, and one sentence of *remedy* per exit code —
|
||||
the "what to do next" that the CLI says to a human in the words of a command
|
||||
line and an agent needs in the words of tools and resources.
|
||||
|
||||
In process, not as a subprocess: `hhstream.cli` is importable Python whose
|
||||
parser already takes an argv list and whose handlers already return a code from
|
||||
the frozen table. Two of its paths cannot be called here, and both are
|
||||
documented in `hhstream_mcp.invoke`: `cli.main`'s `sg` re-exec, and `cmd_run`'s
|
||||
`execvpe`. Consequences of the first are in §5.
|
||||
|
||||
## 1. Transport
|
||||
|
||||
**stdio, and only stdio.** One process per client, spawned by the client; no
|
||||
port, no daemon, no socket of its own. There is already a daemon in this system
|
||||
and it owns all the state.
|
||||
|
||||
The protocol is **not on file descriptor 1** once the server is running: the
|
||||
tools run the CLI in process, the CLI prints, and `record` spawns an `ffmpeg`
|
||||
whose output the CLI does not capture. The server takes a private duplicate of
|
||||
stdin and stdout at start-up, then points fd 1 at its log and fd 0 at
|
||||
`/dev/null`. A stray write is therefore a log line and never a corrupted
|
||||
stream.
|
||||
|
||||
## 2. Configuration
|
||||
|
||||
There is no `--socket` flag. The sockets are the CLI's own environment, read by
|
||||
the CLI:
|
||||
|
||||
| Variable | What it names | Default |
|
||||
| --- | --- | --- |
|
||||
| `HHSTREAM_SOCKET` | the broker's control socket | `/run/hhstream/control.sock` |
|
||||
| `HHSTREAM_FRAME_SOCKET` | the published frame socket | `/run/hypr-stream/stream.sock` |
|
||||
|
||||
Set them in the MCP client's `env` block. One place to configure them is one
|
||||
place for them to be wrong.
|
||||
|
||||
The server's own command line:
|
||||
|
||||
| flag | what it does |
|
||||
| --- | --- |
|
||||
| `--toolsets NAMES` | comma-separated families to offer as **tools**: `frames`, `sessions`, `pointer`, `keyboard`. Omitted, every tool is offered. An unknown name is argparse's exit 2, never a silently empty server. **Resources are not filtered by it** — they are the host's context, not the model's tool budget, and making `hhstream://sessions` conditional on the session *tools* would couple two decisions that are not the same decision. |
|
||||
| `--list-tools` | print the table and exit. Honours `--toolsets`, so it is also how to see what a selection would offer. |
|
||||
| `--list-resources` | print the resource URIs and templates and exit. |
|
||||
|
||||
`$HHSTREAM_MCP_LOG` sets the log level on stderr. Nothing else affects
|
||||
behaviour; in particular the server holds no state and caches no lease.
|
||||
|
||||
**There is no grouping primitive in MCP**, and `--toolsets` is not pretending to
|
||||
be one. The `Tool` object carries `name`, `title`, `description`,
|
||||
`inputSchema`, `outputSchema`, `icons`, `annotations`, `_meta` and `execution` —
|
||||
nowhere to put a family. Tools are a flat list in the specification too. So the
|
||||
only honest lever is which tools the *server* lists, decided by whoever spawns
|
||||
it, and the families below are the grouping that is left: a prefix in the name
|
||||
and a line in this table.
|
||||
|
||||
## 3. The tool surface
|
||||
|
||||
**One tool per CLI verb that acts**, named after it, with `_` where the CLI has
|
||||
a space. Twenty-one tools, in four families. The granularity rationale — and
|
||||
the alternative that was rejected, one tool per family with an `action` enum —
|
||||
is in `hhstream_mcp.tools`' docstring.
|
||||
|
||||
Every schema sets `additionalProperties: false`, so an argument this server
|
||||
would not pass through is refused by the schema rather than dropped on the way
|
||||
to an argv list.
|
||||
|
||||
| family | tools |
|
||||
| --- | --- |
|
||||
| `frames` | `shot`, `record`, `run` |
|
||||
| `sessions` | `session_start`, `session_touch`, `session_kill`, `session_gc`, `session_adopt`, `session_container`, `session_reconcile` |
|
||||
| `pointer` | `pointer_acquire`, `pointer_move`, `pointer_click`, `pointer_scroll`, `pointer_down`, `pointer_up`, `pointer_release` |
|
||||
| `keyboard` | `keyboard_type`, `keyboard_key`, `keyboard_down`, `keyboard_up` |
|
||||
|
||||
Every tool is in exactly one family — asserted by a unit test, because a tool in
|
||||
none of them would be one `--toolsets` could never offer.
|
||||
|
||||
### Frames
|
||||
|
||||
| Tool | Arguments | Returns |
|
||||
| --- | --- | --- |
|
||||
| `shot` | `output?` | **image content** (PNG or JPEG, by the bytes' own magic) plus text naming the geometry, the media type and the byte count |
|
||||
| `record` | `seconds?`, `out?`, `output?`, `fps?`, `work_dir?`, `keep?` | the artefact's **path** and the *measured* rate — never the video |
|
||||
| `run` | `argv`, `settle_s?` | the application's pid, and that it is unmanaged |
|
||||
|
||||
`shot` captures to a temporary file and reads it back, because that is the CLI's
|
||||
only output shape. The media type comes from the bytes and not from the
|
||||
extension: the publisher serves `image/jpeg` on some machines and `hhstream
|
||||
shot` writes the payload it was given verbatim.
|
||||
|
||||
`record` hands back a path because an mp4 of a 720p desktop is megabytes and a
|
||||
tool reply is a message in a model's context. The rate is the one the capture
|
||||
measured, read off the CLI's own line.
|
||||
|
||||
`run` is spawned with `posix_spawn` into its own session and not waited for.
|
||||
`settle_s` (default 1.5) is how long the server watches it before reporting the
|
||||
pid: a launch that fails — no Wayland socket, no such executable — fails inside
|
||||
that window and comes back as an error, one that survives it comes back as
|
||||
running.
|
||||
|
||||
### Session lifecycle
|
||||
|
||||
| Tool | Arguments |
|
||||
| --- | --- |
|
||||
| `session_start` | `app`, `argv?`, `idle_timeout?`, `wait_ready?`, `home?`, `ephemeral_home?`, `request_id?` |
|
||||
| `session_touch` | `id` |
|
||||
| `session_kill` | `id`, `grace?`, `signal?`, `request_id?` |
|
||||
| `session_gc` | `request_id?` |
|
||||
| `session_adopt` | `pid`, `app?`, `idle_timeout?`, `request_id?` |
|
||||
| `session_container` | `id` |
|
||||
| `session_reconcile` | `id?`, `request_id?` |
|
||||
|
||||
Every one of these runs with `--json`, so what comes back is the broker's own
|
||||
protocol object: in the text part verbatim, and in `structuredContent` parsed.
|
||||
The human rendering is a table for a terminal; scraping it would be inventing a
|
||||
second wire format.
|
||||
|
||||
`home` and `ephemeral_home` are mutually exclusive, and the schema says so —
|
||||
the CLI's argparse group, moved forward to where the refusal is free.
|
||||
|
||||
`session_container` is **not** marked read-only, and that is not an oversight:
|
||||
with an `id` the CLI runs `container.reconcile`, which writes the record back.
|
||||
That is also why it is a tool rather than a resource. The no-id listing, which
|
||||
only reads, is `hhstream://containers`.
|
||||
|
||||
### Input — the pointer lease is an argument, never a cache
|
||||
|
||||
| Tool | Arguments |
|
||||
| --- | --- |
|
||||
| `pointer_acquire` | `id`, `ttl?`, `no_restore?` |
|
||||
| `pointer_move` | `id`, `lease`, exactly one of `to` / `by` (each `[x, y]`) |
|
||||
| `pointer_click` | `id`, `lease`, `button?` |
|
||||
| `pointer_scroll` | `id`, `lease`, `axis?`, `amount?` |
|
||||
| `pointer_down` | `id`, `lease`, `button?` |
|
||||
| `pointer_up` | `id`, `lease`, `button?` |
|
||||
| `pointer_release` | `id`, `lease` |
|
||||
| `keyboard_type` | `id`, `lease`, `text` |
|
||||
| `keyboard_key` | `id`, `lease`, `name` |
|
||||
| `keyboard_down` | `id`, `lease`, `name` |
|
||||
| `keyboard_up` | `id`, `lease`, `name` |
|
||||
|
||||
**`lease` is required on every gesture.** The CLI caches the lease id between
|
||||
invocations (`hhstream_session.lease`) because its surface is flagless and it is
|
||||
one process per verb; this server passes `--lease` explicitly on every call and
|
||||
so never reads that cache. The reason is worth stating in full: a cached lease
|
||||
is a lease an agent cannot see, and the failure it
|
||||
produces — a gesture that went to a lease the agent did not know it held — is
|
||||
not one a transcript can explain.
|
||||
|
||||
`pointer_acquire`'s reply puts `lease_id` on the first line of the text part,
|
||||
because that is what the next call needs.
|
||||
|
||||
Who *holds* the lease is a read, so it is `hhstream://pointer` rather than a
|
||||
tool. That is the resource to read after an exit 8.
|
||||
|
||||
Durations (`ttl`, `idle_timeout`, `wait_ready`, `grace`) are **strings** in the
|
||||
CLI's own vocabulary: `30s`, `5m`, `3h`, `2d`, or a bare number of seconds.
|
||||
They are passed through untouched, so the parsing and the refusal are the CLI's.
|
||||
|
||||
### Flag form
|
||||
|
||||
Every option value is passed as one `--name=value` token, and a literal `--`
|
||||
precedes every positional. Not a style choice: `--by -0.1,0.5` and a `text`
|
||||
beginning with a dash are both values argparse reads as option strings, and one
|
||||
uniform rule is one fewer thing to get wrong per flag.
|
||||
|
||||
## 4. The resource surface
|
||||
|
||||
Five fixed resources and three templates, all under one scheme, because they
|
||||
are all views of one machine's one desktop. Every one of them runs the same CLI
|
||||
verb a tool would have, with `--json` where the verb has it.
|
||||
|
||||
| URI | Body | Query |
|
||||
| --- | --- | --- |
|
||||
| `hhstream://status` | `text/plain` — the CLI's own report: both compositor units, the frame socket's path and whether this server can read it, the Wayland socket, one probe frame. `hhstream status` has no JSON form, so neither does this. | — |
|
||||
| `hhstream://sessions` | `application/json` — the broker's `list` object | `?all=true` includes tombstones |
|
||||
| `hhstream://pointer` | `application/json` — the holder, since when, and the buttons and **keys** held | — |
|
||||
| `hhstream://containers` | `application/json` — every container plus the orphan `hh-*` outputs. The **listing** only; see §3. | — |
|
||||
| `hhstream://screen` | the published main output as an image blob. With containers on this is the whole compositor layout, so it is **wider than any single output's configured size**. | — |
|
||||
| `hhstream://sessions/{id}` | `application/json` — one session with its recent audit events | `?events=N` |
|
||||
| `hhstream://sessions/{id}/logs` | `application/json` — the application's own captured output | `?lines=N` |
|
||||
| `hhstream://outputs/{name}` | one output captured alone, as an image blob. Exactly that output's configured size, which is the coordinate space the pointer tools aim in. | — |
|
||||
|
||||
Rules this surface keeps:
|
||||
|
||||
* **A read never writes.** That is what excludes `session container <id>`.
|
||||
* **Only declared query parameters are accepted.** An unknown one is refused,
|
||||
for the reason every tool schema sets `additionalProperties: false`: a
|
||||
parameter silently ignored is a read that answered a different question from
|
||||
the one asked. A parameter given twice is refused too.
|
||||
* **A literal route beats a template.** `hhstream://sessions` is the listing,
|
||||
not a session whose id happened to be empty.
|
||||
* **The media type of a frame is read off the bytes**, never off the extension
|
||||
the server asked the CLI for. The entry's declared `mimeType` is a hint; the
|
||||
`ReadResourceContents` carries the answer.
|
||||
* **No subscriptions.** `Server.get_capabilities` in the pinned SDK hardcodes
|
||||
`ResourcesCapability(subscribe=False, …)` — it never advertises `subscribe`
|
||||
even if a handler is registered. So resource subscription is *not* available
|
||||
as the answer to the missing `logs --follow`, which is a shame, because it
|
||||
would have been the right one. Read it again instead.
|
||||
|
||||
## 5. What is deliberately absent
|
||||
|
||||
| Not exposed | Why |
|
||||
| --- | --- |
|
||||
| `session logs --follow` | it polls until interrupted, and a tool call that never returns hangs the client that made it. Read `hhstream://sessions/{id}/logs` again. Resource *subscriptions* would have been the principled fix; see §4. |
|
||||
| `session start --no-container` | the CLI's flag exists in order to *refuse*: the broker's `start` verb carries no such field (`docs/CONTRACT-sessions.md` §4), so the CLI exits 2 and names the disagreement. A tool argument whose only possible outcome is a refusal is a trap. |
|
||||
| `hhstream --frame-socket` / `session --socket` | §2: the environment configures them, in one place. |
|
||||
| a per-call timeout | §6. |
|
||||
| `session keyboard` with no verb | it prints help and exits 2. There is nothing for a tool to do with that. |
|
||||
|
||||
## 6. Error mapping
|
||||
|
||||
Every refusal the CLI produces on a **tool call** comes back as a tool error —
|
||||
`CallToolResult` with `isError: true` — carrying:
|
||||
|
||||
- the remedy sentence, first, naming the code: `exit 9 (NO_LEASE): …`;
|
||||
- the CLI's own `error`, `reason` and `hint` when it printed a protocol object;
|
||||
- everything it said, verbatim, under `hhstream said:`;
|
||||
- `structuredContent` with `ok: false`, `exit_code`, `remedy`, and the
|
||||
protocol object's own fields.
|
||||
|
||||
`isError` and not a JSON-RPC error, for tools, throughout. A JSON-RPC error
|
||||
reaches the client's log; "another session holds the lease" is something the
|
||||
calling agent has to read and act on. (The SDK's `call_tool` handler also
|
||||
converts anything raised into `isError`, so this is the only channel there is in
|
||||
practice.)
|
||||
|
||||
On a **resource read** it is the other way round, and not by preference:
|
||||
`ReadResourceResult` has no `isError`, so a refusal is raised as a JSON-RPC
|
||||
error with code `-32602` (`INVALID_PARAMS`), its `message` carrying the same
|
||||
remedy-then-the-CLI's-own-words text and its `data` carrying the same
|
||||
`{ok, exit_code, error, reason, hint, remedy}` object. Returning the broker's
|
||||
failure object as the resource's *body* would make "no such session" read as a
|
||||
successful read of a session, which is the one outcome a contract has to
|
||||
forbid. The same error is raised for a URI that names nothing and for an
|
||||
undeclared query parameter — in both cases before the CLI is reached at all.
|
||||
|
||||
"Arrives as" below is for a tool call; on a resource read every one of them is
|
||||
the protocol error above, with the same remedy.
|
||||
|
||||
| Exit | Name | Arrives as | The remedy an agent is given |
|
||||
| --- | --- | --- | --- |
|
||||
| 0 | OK | a result | — |
|
||||
| 1 | *not in the frozen table* | tool error | the frame verbs' own failure: no frame published, or `grim`/`ffmpeg` missing from the server's PATH. Also what an uncaught exception in a handler becomes, with its traceback — which is what a CLI process would have done. |
|
||||
| 2 | USAGE | tool error | fix the arguments; a retry fails identically |
|
||||
| 3 | NO_SUCH_SESSION | tool error | read `hhstream://sessions` to see which ids exist |
|
||||
| 4 | BAD_STATE | tool error | read `hhstream://sessions/<id>` to see which state |
|
||||
| 5 | DAEMON_UNREACHABLE | tool error | an operator problem; the three frame tools and `hhstream://status` may still work |
|
||||
| 7 | TIMEOUT | tool error | read the state back, then retry with the same `request_id` |
|
||||
| 6 | POLICY | tool error | a configuration decision; no retry changes it |
|
||||
| 8 | BUSY | tool error | read `hhstream://pointer` for the holder; wait. **Never** "acquire one" |
|
||||
| 9 | NO_LEASE | tool error | `pointer_acquire`, then pass the new `lease_id` |
|
||||
| 10 | COMPOSITOR | tool error | the session is **not** lost; it is degraded |
|
||||
|
||||
8 and 9 must never read alike, and a unit test holds them apart: an agent that
|
||||
sees 8 must wait, one that sees 9 must acquire.
|
||||
|
||||
Two failures are not the CLI's verdict and are reported in the same channel
|
||||
anyway, because the agent holding the tool is the one who has to say so:
|
||||
|
||||
- a tool name that does not exist — the reply names the ones that do;
|
||||
- an argument the schema rejects — the SDK refuses before an argv list exists,
|
||||
so the CLI is never reached.
|
||||
|
||||
**The `sg` re-exec is not available here.** `hhstream` recovers from an
|
||||
unreadable frame socket by re-executing itself through the setuid `sg` wrapper
|
||||
to join the compositor's group. That is an `exec`, and performing it would
|
||||
replace this server and drop the client's connection. So a frame verb that
|
||||
cannot reach the socket fails with the CLI's own message plus a sentence saying
|
||||
what the CLI would have done and how to avoid needing it: run the server as a
|
||||
member of that group (`sg hhstream -c hhstream-mcp` in the client's spawn
|
||||
command, or add the account to the group). The hint is added only when the
|
||||
condition is actually true, asked of the CLI's own predicate, and only for the
|
||||
verbs it could be true of.
|
||||
|
||||
**There is no per-call timeout.** In process there is nothing to kill: a thread
|
||||
cannot be interrupted. The deadlines are therefore the ones that already exist
|
||||
— the session client's 60 s socket timeout, the broker's per-verb deadline, and
|
||||
the frame socket's own `--timeout` — and a call that outlives all of them
|
||||
outlives this server too. A subprocess design could have killed it; that is the
|
||||
one thing given up by calling the CLI in process.
|
||||
|
||||
## 7. Concurrency
|
||||
|
||||
Tool calls are **serialised**. The CLI prints to a process-global `sys.stdout`,
|
||||
so two concurrent calls would interleave their output into each other's reply.
|
||||
One lock around the whole call is the honest fix, and costs nothing a caller
|
||||
would notice: the broker already serialises every mutation, and the CLI was one
|
||||
process per verb anyway. The event loop stays free, so a `ping` is answered
|
||||
while a `record` runs.
|
||||
|
||||
## 8. The two rules, which every relevant tool and resource repeats
|
||||
|
||||
These are `hhstream_session.ACTIVITY_NOTE` and `KEYBOARD_LEASE_NOTE` restated
|
||||
in terms of this surface. They are on the individual tools and resources and
|
||||
not only in the server instructions, because a client shows a thing's own
|
||||
description at the point of use:
|
||||
|
||||
1. **`session_touch` is the only thing that resets a session's idle clock.**
|
||||
Reading `hhstream://sessions`, `hhstream://sessions/{id}` or its logs does
|
||||
not, `session_gc` does not, and neither does any pointer or keyboard tool. A
|
||||
session being driven is still a session nobody has said they want kept. The
|
||||
three resources it applies to say so in their own descriptions, because a
|
||||
description is what a host shows beside the thing it describes.
|
||||
|
||||
2. **Every keyboard tool needs the pointer lease, and holds only while it
|
||||
holds.** There is no keyboard lease: one compositor seat means one keyboard
|
||||
focus. A held non-modifier key floods the window until it is lifted or the
|
||||
lease expires, because the *application* does the repeating — measured at 25
|
||||
a second after 600 ms — and this server cannot rate-limit what it does not
|
||||
generate.
|
||||
|
||||
`tests/unit/test_mcp_tools.py` asserts both notes are present on every tool they
|
||||
apply to and holds the CLI's own constants as a tripwire against drift;
|
||||
`tests/unit/test_mcp_resources.py` does the same for the five reads the first
|
||||
rule applies to.
|
||||
|
||||
## 9. Packaging
|
||||
|
||||
`packages.hhstream-mcp` (`nix/mcp.nix`), a separate derivation from
|
||||
`packages.hhstream` because `mcp` is a third-party dependency and the frame
|
||||
socket, the CLI and the broker are stdlib-only by policy. `packages.hhstream`
|
||||
must not grow that dependency; the root `pyproject.toml` excludes
|
||||
`hhstream_mcp*` from its package discovery so it cannot acquire it by accident.
|
||||
|
||||
`services.hyprland-headless-stream.mcp.enable` (default `false`) puts the
|
||||
binary on the system PATH. That is the whole of the option: there is no unit, no
|
||||
socket and no state directory, because the server is spawned per client over
|
||||
stdio.
|
||||
+162
-11
@@ -1,4 +1,4 @@
|
||||
# CONTRACT — sessions build (sessions-v3)
|
||||
# CONTRACT — sessions build (sessions-v4)
|
||||
|
||||
This file is the interface for the **session** work: the broker, containers,
|
||||
compositor IPC and pointer **and keyboard** input. It is the sibling of `docs/CONTRACT.md`, which
|
||||
@@ -9,11 +9,31 @@ 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-v3 (2026-10-04). v1 was the freeze the four slices built
|
||||
Version: sessions-v4 (2026-10-11). v1 was the freeze the four slices built
|
||||
against; v2 recorded the decisions their reports asked for; v3 adds the
|
||||
keyboard. Every change in both has been an addition or a clarification — **no
|
||||
v1 or v2 signature changed meaning** — so earlier code stays valid except where
|
||||
noted.
|
||||
keyboard; v4 adds the **per-session live stream**. Every change in all of them
|
||||
has been an addition or a clarification — **no v1, v2 or v3 signature changed
|
||||
meaning** — so earlier code stays valid except where noted.
|
||||
|
||||
v4 changes, all of them the stream
|
||||
(`docs/plans/2026-10-04-session-stream-webapp.md`, Stage 2):
|
||||
|
||||
| § | Change | Why |
|
||||
| --- | --- | --- |
|
||||
| §3.5 | New: `hhstreamd/live.py`, the broker's end of `/run/hhstream/live.sock`, and that socket's wire format. | The stream is captured by `hhstream-live`, a third executor beside the pointer driver. `grim` blocks tens to hundreds of milliseconds, so it must not run in the broker, and a LAN-facing HTTP parser must not run in the frame server whose one-socket contract cannot grow one. The broker therefore *tells* a process what to publish, exactly as it tells the driver where to warp. |
|
||||
| §4 | Verbs `stream.enable`, `stream.disable`, `stream.list`, `stream.status`. `enable` and `disable` are in the mutation set; `list` and `status` are not. | `enable` mints or rotates a phrase and opens a capture — a retried `enable` that minted a second phrase would invalidate the URL somebody is already holding. |
|
||||
| §4 | `start` gains `stream?`, `stream_phrase?` and `stream_fps?`. | A stream needs the session's container output, which `start` creates; sequencing "start, then enable" in a *caller* means every caller repeats the ordering and the failure handling. One request, one answer, and the phrase comes back with the session. |
|
||||
| §4 | **A connected viewer is activity.** The broker asks the daemon for viewer counts about once a minute and stamps `touch` when any is non-zero. | The one new way the idle clock moves, and the only exception to "`touch` is the only mark of activity" since that rule was written. A session an operator is watching on his phone must not be reaped at three hours *because* watching is all he is doing. An enabled stream with **no** viewer runs no `grim` and keeps nothing alive, so this cannot hold a session open by itself. |
|
||||
| §4 | Error names `stream_unavailable` (exit 10), `stream_busy` (exit 8), `stream_budget` (exit 6). **No new exit numbers.** | The failures are the ones the table already has: no container is a compositor-side failure, a phrase collision is a busy, a viewer cap is a policy budget. |
|
||||
| §5 | `/run/hhstream/live.sock`, the unit `hhstream-live`, and the stream port 9988. | Named here with the other frozen paths, because two processes have to agree on them. |
|
||||
| §6 | Registry **schema 3 → 4**: the record gains `stream`. | A phrase has to survive a broker restart and a re-enable, so it lives in the record. Older records migrate to `stream: null` and are adopted, not refused. |
|
||||
|
||||
v4 deliberately does **not** give the broker the port, the bind address or the
|
||||
capture command. Those are the daemon's, from its own unit's argv, for the
|
||||
reason the keyboard layout is the driver's: the broker's TOML is read by
|
||||
`hhstreamd`, and a setting an operator could change in it while the listener
|
||||
stayed where it was would be worse than no setting at all. The broker learns
|
||||
the URL prefix *from* the daemon, in the `attach` reply.
|
||||
|
||||
v3 changes, all of them keyboard (`docs/plans/2026-10-03-keyboard-input.md` as
|
||||
amended by `docs/plans/2026-10-04-keyboard-verification.md`):
|
||||
@@ -375,6 +395,79 @@ the lease; a real-compositor case is still missing — see
|
||||
lease state** — the broker owns the lease; the driver is an executor that must
|
||||
never be trusted to serialise anything.
|
||||
|
||||
### 3.5 `hhstreamd/live.py` (v4) — the broker's end of the stream daemon
|
||||
|
||||
A third executor beside the pointer driver, and the same shape as §3.4: the
|
||||
broker holds the *decision* (which session streams, under which phrase) and the
|
||||
daemon holds the *capture*. `hhstream-live` owns the port, the bind address and
|
||||
the capture command, from its own unit's argv; the broker never passes them and
|
||||
never reads them from its own TOML.
|
||||
|
||||
```python
|
||||
class LiveUnavailable(Exception):
|
||||
"""The stream daemon could not be reached, or did not answer intelligibly."""
|
||||
|
||||
class LiveRejected(Exception):
|
||||
"""The daemon refused. `kind` maps to an exit code, as the driver's does."""
|
||||
def __init__(self, message: str, *, kind: str | None = None) -> None: ...
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Attachment:
|
||||
phrase: str; output: str; fps: int; session: str | None
|
||||
url: str # the daemon's own prefix, e.g. http://127.0.0.1:9988/<phrase>/
|
||||
viewers: int
|
||||
|
||||
class LiveStreams:
|
||||
def __init__(self, socket_path: Path | str, *, timeout_s: float = 2.0) -> None: ...
|
||||
def attach(self, *, phrase: str, output: str, fps: int,
|
||||
session: str | None = None, label: str = "") -> Attachment: ...
|
||||
def detach(self, phrase: str) -> bool: ... # False if it was not attached
|
||||
def list(self) -> list[Attachment]: ...
|
||||
def viewers(self) -> dict[str, int]: ... # phrase -> connected viewers
|
||||
def close(self) -> None: ...
|
||||
```
|
||||
|
||||
Private socket protocol, newline-delimited JSON, the driver's conventions
|
||||
exactly — `{"ok": true, …}` or `{"ok": false, "error": "…", "kind": "…"}`:
|
||||
|
||||
```json
|
||||
{"op": "attach", "phrase": "amber-otter-lantern-harbor-7k2qp", "output": "hh-x",
|
||||
"session": "x", "label": "chromium", "fps": 5} // fps is OPTIONAL
|
||||
-> {"ok": true, "stream": {"phrase": "…", "output": "hh-x",
|
||||
"fps": 5, "session": "x", "url": "http://…/", "viewers": 0}}
|
||||
{"op": "detach", "phrase": "…"} -> {"ok": true, "detached": true}
|
||||
{"op": "list"} -> {"ok": true, "streams": [ {…}, … ]}
|
||||
{"op": "viewers"} -> {"ok": true, "viewers": {"<phrase>": 2}}
|
||||
```
|
||||
|
||||
Four rules that are not interchangeable:
|
||||
|
||||
- **The daemon holds no session state and no idea of an idle clock.** It
|
||||
publishes what it was told to publish. `viewers` is a *reading*, and what the
|
||||
broker does with it (§4) is the broker's.
|
||||
- **`fps` is optional, and omitting it is the normal case.** The default rate is
|
||||
the daemon's, from its own unit's argv (`sessions.stream.fps`), for the same
|
||||
reason the port is. The broker sends one only when a caller named one, or
|
||||
when re-attaching a stream that already had one. A broker that sent its own
|
||||
default on every attach would make the operator's option a setting that
|
||||
changed nothing — the same failure `--xkb-layout` (§3.4) exists to avoid.
|
||||
- **`attach` is idempotent on the phrase.** Re-attaching the same phrase to the
|
||||
same output returns the existing stream rather than starting a second
|
||||
capture, because a re-`enable` after a broker restart must not double the
|
||||
`grim` rate on one output. The same phrase aimed at a *different* output is
|
||||
`{"kind": "invalid_argument"}`.
|
||||
- **The phrase is never logged by either side.** It is the stream's only
|
||||
credential. The daemon logs the output and the viewer count; the broker's
|
||||
audit log records the session and the output (§4), and neither records the
|
||||
phrase.
|
||||
|
||||
`url` comes back from the daemon rather than being built by the broker, for the
|
||||
reason the port is the daemon's: a URL the broker assembled from a port it was
|
||||
told about once is a URL that silently lies the first time an operator moves
|
||||
the listener.
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## 4. Wire format (broker control socket) — B, C and D do not implement this
|
||||
@@ -395,6 +488,44 @@ code will be called with):
|
||||
| `pointer.state` | — | `holder`, `since`, `lease_id`, `buttons[]`, `keys[]` |
|
||||
| `keyboard.key` (v3) | `id`, `lease_id`, `key`, `state` | `keys[]` |
|
||||
| `keyboard.type` (v3) | `id`, `lease_id`, `text` | `chars`, `keys[]` |
|
||||
| `stream.enable` (v4) | `id`, `phrase?`, `fps?` | `stream` |
|
||||
| `stream.disable` (v4) | `id` | `stream`, `detached` |
|
||||
| `stream.list` (v4) | — | `streams[]`, `available` |
|
||||
| `stream.status` (v4) | `id?` | `stream` \| `streams[]` |
|
||||
|
||||
**v4, the stream.** `stream.enable` and `stream.disable` are in the
|
||||
`request_id` mutation set; `stream.list` and `stream.status` are not.
|
||||
`start` additionally accepts `stream?` (bool), `stream_phrase?` and
|
||||
`stream_fps?`, and when `stream` is true its reply's session carries the same
|
||||
`stream` object `stream.enable` would have returned.
|
||||
|
||||
The `stream` object is the record's, with the daemon's `url` and `viewers`
|
||||
merged in when it could be asked:
|
||||
|
||||
```json
|
||||
{"enabled": true, "phrase": "amber-otter-lantern-harbor-7k2qp",
|
||||
"output": "hh-x", "fps": 5, "port": 9988,
|
||||
"url": "http://127.0.0.1:9988/amber-otter-lantern-harbor-7k2qp/",
|
||||
"viewers": 0, "enabled_at": "2026-10-11T…Z", "attached": true}
|
||||
```
|
||||
|
||||
`attached` is its own field and is **not** folded into `enabled`: a record may
|
||||
say a session is enabled while the daemon is down, and "the operator asked for
|
||||
this stream" and "a capture is running right now" are two different facts. A
|
||||
caller that wants the second one reads `attached`; `url` and `viewers` are
|
||||
absent when it is false, rather than stale.
|
||||
|
||||
**`stream.enable` requires the session's container output.** Without one it is
|
||||
`stream_unavailable` (exit 10). A stream never falls back to the main output:
|
||||
that output carries every other session, and putting it on a phone is the one
|
||||
mistake this feature must not make. Re-enabling an enabled session returns the
|
||||
same phrase; a `phrase` that differs from the stored one is `stream_busy`
|
||||
(exit 8). `disable` then `enable` rotates it.
|
||||
|
||||
**Teardown order is load-bearing.** `kill` detaches the stream *before*
|
||||
`hyprctl output remove`, because a capture aimed at a removed output fails every
|
||||
time and the daemon's own failure budget would close the viewers with
|
||||
"unknown output" instead of "the session ended".
|
||||
|
||||
**v3, the keyboard.** `keyboard.*` verbs take the **pointer** lease: there is
|
||||
no `keyboard.acquire` and no second lease id. One `wl_seat` means one keyboard
|
||||
@@ -417,10 +548,26 @@ explicitly rather than inheriting.
|
||||
| 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.*` **and
|
||||
`keyboard.*`** verb do **not** reset the idle clock. A session being typed into
|
||||
is still a session nobody has said they want kept.
|
||||
**v4 adds error names and no numbers.** `stream_unavailable` → 10 (no
|
||||
container, or the daemon is unreachable — the session itself is fine either
|
||||
way), `stream_busy` → 8 (a `phrase` that is not this session's), `stream_budget`
|
||||
→ 6 (the daemon's viewer or stream cap). A bad `fps` is `invalid_argument` → 2,
|
||||
as every other bad argument is.
|
||||
|
||||
Activity accounting is load-bearing and has **one** exception as of v4:
|
||||
**`touch` is the only mark of activity a caller can make**; `list`, `status`,
|
||||
`logs`, `gc`, every `pointer.*` **and `keyboard.*`** verb, and every
|
||||
`stream.*` verb do **not** reset the idle clock. A session being typed into is
|
||||
still a session nobody has said they want kept.
|
||||
|
||||
The exception is **a connected viewer**. About once a minute the broker asks
|
||||
the daemon for viewer counts and stamps `touch` on every session whose stream
|
||||
has at least one; the audit entry names the session, the output and the count,
|
||||
never the phrase. This is not a caller's verb and cannot be invoked — it is the
|
||||
broker observing that a person is *looking*, which is the one form of "still
|
||||
wanted" that does not come down the control socket. It cannot hold a session
|
||||
open on its own: an enabled stream with no viewer runs no `grim` and stamps
|
||||
nothing.
|
||||
|
||||
The *lease* clock is a different one, and v3 widens it: every `pointer.*` and
|
||||
`keyboard.*` gesture verb refreshes the lease's idle deadline, because they all
|
||||
@@ -438,14 +585,18 @@ go through the same gate. `pointer acquire`'s own stderr says so.
|
||||
| Frame socket (published) | `<runtime dir>/stream.sock` — default `/run/hypr-stream/stream.sock`. Also frozen in `docs/CONTRACT.md`, which v1 of this file left disagreeing with it. |
|
||||
| Broker control socket | `/run/hhstream/control.sock` |
|
||||
| Broker↔driver socket | `/run/hhstream/pointer.sock` |
|
||||
| Broker↔stream socket | `/run/hhstream/live.sock` (v4) |
|
||||
| Stream port | **option default** `9988` (`sessions.stream.port`), fixed and single — no range, no fallback. The daemon owns it; the broker learns the URL from the daemon (§3.5). |
|
||||
| Stream bind | **option default** `127.0.0.1` (`sessions.stream.bind`) |
|
||||
| Broker state dir | **option default** `/var/lib/hhstream`; this machine sets `/var/lib/hermes/hhstream-sessions` (`sessions.stateDir`). v1 listed the deployed value, which read as a contradiction of the module. |
|
||||
| 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` |
|
||||
| Units | `hyprland-headless`, `hyprland-headless-stream`, `hhstream-sessions`, `hhstream-pointer`, `hhstream-live` (v4) |
|
||||
| Keyboard layout | **option default** `us` (`sessions.keyboard.layout`), reaching the driver as `--xkb-layout`. One group: a comma is refused. Hyprland's `input:kb_layout` is not read. |
|
||||
| Binaries | `hhstream`, `hhstreamd`, `hhstream-server`, `hhstream-client`, `hhstream-pointer` |
|
||||
| Binaries | `hhstream`, `hhstreamd`, `hhstream-server`, `hhstream-client`, `hhstream-pointer`, `hhstream-live` |
|
||||
| Registry schema | **4** (v4; 3 → 4 adds `stream`, migrating to `null`) |
|
||||
| Service account | `hermes`, supplementary group `hhstream` |
|
||||
|
||||
---
|
||||
|
||||
@@ -14,6 +14,9 @@ Each file answers three questions and stops:
|
||||
| [scroll-has-no-compositor-proof](scroll-has-no-compositor-proof.md) | medium | works live; unproven in a gate |
|
||||
| [reconcile-while-containers-are-off](reconcile-while-containers-are-off.md) | medium | partly fixed: discovery now survives a restart; teardown still lives inside the feature |
|
||||
| [kill-can-leave-the-app-alive](kill-can-leave-the-app-alive.md) | medium | found by counting windows, not sessions |
|
||||
| [capture-binary-and-the-unit-path](capture-binary-and-the-unit-path.md) | medium | found the first time the app was run as a unit: a unit's `PATH` has no `grim` |
|
||||
| [mcp-in-process-has-no-call-deadline](mcp-in-process-has-no-call-deadline.md) | medium | two costs of running the CLI in process: no killable deadline, and no `sg` recovery |
|
||||
| [mcp-resources-cannot-be-subscribed-to](mcp-resources-cannot-be-subscribed-to.md) | medium | the SDK hardcodes `subscribe=False`, so a log resource can only be re-read |
|
||||
|
||||
Closed since this folder was written:
|
||||
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
# The capture command needs an absolute path under a unit
|
||||
|
||||
## The issue
|
||||
|
||||
`hhstream-live` runs its capture command (`grim -c -t jpeg -q 80 -o <output> -`)
|
||||
by name, from the `PATH` it inherits. Under **systemd** that path is
|
||||
`/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` — the system
|
||||
profile is deliberately not on it — so the capture fails, ten times, and the
|
||||
stream gives up:
|
||||
|
||||
```
|
||||
WARNING hhstream.live: stream on hh-chromium-yhvpms: giving up after 10
|
||||
consecutive capture failures: capture command ['grim', '-c', '-t', 'jpeg',
|
||||
'-q', '80', '-o', 'hh-chromium-yhvpms', '-'] could not be run:
|
||||
[Errno 2] No such file or directory: 'grim'
|
||||
```
|
||||
|
||||
Measured on 2026-10-11 on the deployment machine, the first time the app was
|
||||
run **as a unit** rather than from a login shell. A login shell has
|
||||
`/run/current-system/sw/bin` on its `PATH`, which is why every run before this
|
||||
one — the stage-1 work, the standalone `serve --stream` runs, the whole test
|
||||
suite — never saw it.
|
||||
|
||||
What makes it worth a file rather than a line: the failure is quiet in the
|
||||
worst way. The unit starts, the port opens, the landing page answers, and
|
||||
`status.json` reports a stream that is simply `"stopped": true` with
|
||||
`"failures": 10`. A viewer sees an empty frame area and nothing else says why.
|
||||
Only the unit's log names the reason, one line above the giving-up entry.
|
||||
|
||||
## Ideas
|
||||
|
||||
1. **An absolute binary, as the module already does elsewhere** *(recommended)*.
|
||||
`sessions.apps` requires an absolute store path for exactly this reason —
|
||||
"a unit's default `PATH` does not include the system profile", which is why
|
||||
the allowlist spells `foot` as `${pkgs.foot}/bin/foot`. The stream's unit
|
||||
should not inherit `grim` by name either: pass
|
||||
`${pkgs.grim}/bin/grim` as the capture command from the module (or set
|
||||
`PATH` on the unit, which is what made it work on the deployment machine).
|
||||
The absolute path is also the stronger control: it names one exact binary
|
||||
instead of whatever `PATH` resolves to at the moment the unit starts.
|
||||
2. **Resolve early and fail loudly.** Have the app resolve the binary itself at
|
||||
start-up and refuse to serve with a named error (`capture_binary_missing`)
|
||||
if it is not there. A unit that dies at start is a five-second diagnosis; a
|
||||
unit that serves an empty frame is an afternoon.
|
||||
3. **Both.** The module passes the absolute path *and* the app checks it once
|
||||
at start-up: the first is the fix, the second is what catches the next
|
||||
deployment shape nobody has thought of yet.
|
||||
|
||||
## Why it matters
|
||||
|
||||
Stage 3's unit is the point at which running under systemd stops being an
|
||||
experiment and becomes the only path every deployment takes — and a stream
|
||||
that answers, reports a healthy port, and shows nothing is a worse failure than
|
||||
one that does not start. Whichever idea is taken, the check for it belongs in
|
||||
the same stage as the unit: a `vm-*` check that starts the unit and reads one
|
||||
frame would have caught this on the day it was written.
|
||||
@@ -0,0 +1,67 @@
|
||||
# The MCP server cannot abandon a call, and cannot re-join the compositor's group
|
||||
|
||||
## The issue
|
||||
|
||||
`hhstream-mcp` runs the CLI's handlers **in its own process**: a tool or a
|
||||
resource read builds the argv list `hhstream.cli`'s parser takes, and
|
||||
`hhstream_mcp.invoke.dispatch` runs the handler argparse selected. That is the seam the design asks for — one place
|
||||
decides the argv, nothing re-implements a rule — and it costs two things a
|
||||
subprocess would have given for free. Both are consequences of the same fact, so
|
||||
they are one item.
|
||||
|
||||
**1. There is no per-call deadline.** A subprocess can be killed; a Python
|
||||
thread cannot be interrupted. So the only deadlines are the ones that already
|
||||
exist inside the CLI: `hhstream_session.client`'s 60 s socket timeout, the
|
||||
broker's own per-verb deadline, and the frame socket's `--timeout` (10 s by
|
||||
default, and not currently reachable as a tool argument — it is a *global* CLI
|
||||
flag, before the verb, and the argv builders emit the verb first).
|
||||
|
||||
Measured consequence: nothing in the current surface is known to hang — every
|
||||
path either talks to the broker under its 60 s timeout or to the frame socket
|
||||
under its own — but `record` with a large `seconds`, or a `grim` wedged on a
|
||||
compositor that has stopped answering, would hold the worker thread until it
|
||||
returns. The event loop stays responsive (a `ping` is answered), and the calls
|
||||
are serialised by design, so the visible symptom is every *subsequent* tool call
|
||||
queueing behind one that will not finish.
|
||||
|
||||
**2. The `sg` re-exec is unavailable.** `cli.main` recovers from a frame socket
|
||||
it cannot read by `os.execv`-ing itself through the setuid `sg` wrapper to join
|
||||
the compositor's group. Performing that here would replace the MCP server
|
||||
mid-session and drop the client's connection, so `dispatch` deliberately does
|
||||
not call `cli.main` and the recovery does not happen. `shot` and `record`
|
||||
instead fail with the CLI's own message plus a sentence naming what the CLI
|
||||
would have done (`hhstream_mcp.invoke.access_hint`), and the operator is told to
|
||||
run the server as a member of the group instead.
|
||||
|
||||
## Ideas
|
||||
|
||||
1. **Leave (1) as it is and make the frame-socket timeout reachable.** *(recommended
|
||||
for (1))* The honest small fix: let `shot` and `record` take a `timeout`
|
||||
argument, and `hhstream://status` and the frame resources a `?timeout=`,
|
||||
emitted as a global flag *before* the verb — which `hhstream_mcp.tools.argv`
|
||||
cannot express today. That hands the one knob the CLI already has to the
|
||||
caller, and does not pretend this layer can enforce a deadline it cannot.
|
||||
2. **Run each call in a forked child after all.** Restores a killable deadline,
|
||||
at the cost of a process per tool call and of re-introducing the two `exec`
|
||||
paths this design avoids. Worth it only if a hang is observed in practice.
|
||||
3. **For (2): a `--sg-group` flag on the server** that re-execs itself through
|
||||
`sg` *once, before claiming the transport*, so the group is joined while
|
||||
there is still no client to drop. *(recommended for (2))* It keeps the
|
||||
recovery the CLI has, in the one moment it is safe, and is strictly better
|
||||
than asking every client's configuration to spell `sg hhstream -c
|
||||
hhstream-mcp`.
|
||||
4. **For (2): accept it and document only.** What ships today. Correct, and the
|
||||
message says what to do — but it makes a working CLI and a failing tool out
|
||||
of the same machine, which is exactly the kind of difference an agent cannot
|
||||
diagnose.
|
||||
|
||||
## Why it matters
|
||||
|
||||
(2) is the one an operator meets first: the CLI works from their shell, the
|
||||
`shot` tool does not, and the two differ only in a recovery that is invisible
|
||||
from either side. The message carries the answer, which is why this is medium
|
||||
and not high.
|
||||
|
||||
(1) is latent. It becomes real the first time a compositor stops answering while
|
||||
an agent is driving it: the agent's next tool call waits behind the stuck one
|
||||
with no way to give up, where a CLI user would have pressed ctrl-C.
|
||||
@@ -0,0 +1,65 @@
|
||||
# A resource cannot be followed, because the SDK will not advertise subscriptions
|
||||
|
||||
## The issue
|
||||
|
||||
`hhstream://sessions/{id}/logs` is the right shape for watching an application:
|
||||
a URI whose content changes, which is exactly what MCP resource
|
||||
**subscriptions** are for (`resources/subscribe`, then
|
||||
`notifications/resources/updated`). An agent waiting for a build to finish, or
|
||||
for a page to load, would subscribe once instead of reading in a loop.
|
||||
|
||||
It is not available. `mcp.server.lowlevel.Server.get_capabilities` computes the
|
||||
resource capability like this (mcp 1.29.0, `server/lowlevel/server.py`):
|
||||
|
||||
```python
|
||||
if types.ListResourcesRequest in self.request_handlers:
|
||||
resources_capability = types.ResourcesCapability(
|
||||
subscribe=False, listChanged=notification_options.resources_changed
|
||||
)
|
||||
```
|
||||
|
||||
`subscribe=False` is hardcoded. Registering a `@server.subscribe_resource()`
|
||||
handler does not change it, so a client is told the server cannot be subscribed
|
||||
to and correctly never tries. The handlers exist on the `Server` class and are
|
||||
unreachable through the advertised capability.
|
||||
|
||||
This is why `docs/CONTRACT-mcp.md` §4 says there is no following, and why the
|
||||
`session-logs` resource's own description tells the reader to read it again. It
|
||||
is also the reason the CLI's `session logs --follow` has no equivalent anywhere
|
||||
in this surface: the tool form would hang the client, and the resource form is
|
||||
switched off upstream.
|
||||
|
||||
## Ideas
|
||||
|
||||
1. **Set the capability after construction.** *(recommended)*
|
||||
`create_initialization_options()` returns the computed capabilities, and the
|
||||
server is handed them by `serve()` -- so one line in
|
||||
`hhstream_mcp.server.serve` could set `capabilities.resources.subscribe =
|
||||
True` before `server.run`, with `subscribe_resource`/`unsubscribe_resource`
|
||||
handlers behind it. Small, local, and reversible when the SDK grows the
|
||||
knob. The cost is that it reaches past the SDK's own computation, which is
|
||||
the kind of thing that breaks on an upgrade without saying so -- so it wants
|
||||
a unit test asserting the advertised capability, not just the handler.
|
||||
2. **Poll on the server's side and notify.** Keep `subscribe=False`, and have
|
||||
the server itself re-read and send `notifications/resources/updated`. Does
|
||||
not work: a client that was told `subscribe=False` has no reason to have
|
||||
subscribed, so there is nobody to notify.
|
||||
3. **Upstream it.** The hardcoded `False` looks like an oversight rather than a
|
||||
decision; a patch that derives it from whether a `subscribe_resource`
|
||||
handler was registered would match how every other capability on that method
|
||||
is computed. Slowest, and the right long-term answer.
|
||||
4. **Leave it, and say so.** What ships today, in the contract and in the
|
||||
resource's own description.
|
||||
|
||||
## Why it matters
|
||||
|
||||
It is the difference between an agent that waits and an agent that polls. Every
|
||||
read is a CLI call in process, so a loop that reads a session's logs every
|
||||
second is a `hhstream session logs` every second, serialised against every other
|
||||
call this server makes -- which is exactly the contention the other TODO in this
|
||||
folder describes. Subscriptions would remove the loop rather than make it
|
||||
cheaper.
|
||||
|
||||
Medium rather than high because reading again *works*, and because the one
|
||||
caller who really needs to follow output can run `hhstream session logs
|
||||
--follow` in a terminal, which is what it is for.
|
||||
@@ -85,14 +85,20 @@ session record so it survives a broker restart and a re-enable.
|
||||
|
||||
- Shape: `<word>-<word>-<word>-<word>-<xxxxx>`, e.g.
|
||||
`amber-otter-lantern-harbor-7k2qp`.
|
||||
- Words come from a **vendored EFF large wordlist** (7776 words, ~70 KB, in the
|
||||
- Words come from a **vendored EFF large wordlist** (7776 lines, ~70 KB, in the
|
||||
repo — no network at runtime, no dependency) and the tail is five characters
|
||||
of `[a-z0-9]`. Four words is `4 · log2(7776) ≈ 51.7` bits and the tail adds
|
||||
`5 · log2(36) ≈ 25.8`, for **≈ 77.5 bits** — comfortably past anything a LAN
|
||||
request rate can enumerate, and the operator's stated shape ("5 with a random
|
||||
5 character string for the last word").
|
||||
- `--phrase` on enable sets your own (checked against the shape); `disable`
|
||||
then `enable` **rotates** it. A rotation is one record write.
|
||||
of `[a-z0-9]`. Four of those lines are hyphenated (`drop-down`, `felt-tip`,
|
||||
`t-shirt`, `yo-yo`) and are dropped on load, because a hyphen is the phrase's
|
||||
own separator and such a word would make a six-token phrase nobody could hear
|
||||
the shape of; **7772 words** are usable. Four words is `4 · log2(7772) ≈ 51.7`
|
||||
bits and the tail adds `5 · log2(36) ≈ 25.8`, for **≈ 77.5 bits** —
|
||||
comfortably past anything a LAN request rate can enumerate, and the operator's
|
||||
stated shape ("5 with a random 5 character string for the last word").
|
||||
- `--phrase` on enable sets your own, and it is held to **exactly the generated
|
||||
shape** (four `[a-z]{3,}` words plus a five-character `[a-z0-9]` tail): the
|
||||
phrase is the stream's only credential, so anything a `--phrase` may be is a
|
||||
password an operator can choose, and a looser check would accept `a-b-c`.
|
||||
`disable` then `enable` **rotates** it. A rotation is one record write.
|
||||
- The phrase is the only credential. It is in the URL, in cleartext on the LAN
|
||||
when the LAN is opted into — the threat model is "another device on the LAN
|
||||
can watch if it can guess the phrase", not "the phrase is hidden from the
|
||||
@@ -150,7 +156,7 @@ capture without one.
|
||||
| 0 | Contract text: `docs/CONTRACT-sessions.md` → **sessions-v3** (the four verbs, `/run/hhstream/live.sock`, `hhstream-live`, the single port, the viewer-touch exception, schema 4, error names). | S | Freezing the wrong default. This plan is the review. |
|
||||
| 1 | `hhstream-live`: the HTTP server, the router, the phrase (wordlist + generator), one output, injected capture, **unit tests**. No broker. | M | A phone that will not paint `multipart/x-mixed-replace`; the index leaking phrases when made public. |
|
||||
| 2 | Broker + CLI: the record field, schema 4, the four verbs, teardown order, viewer heartbeat, integration test on `127.0.0.1`. | L | A second capture on re-enable; `disable` racing `output remove`; a heartbeat that keeps a session alive with zero viewers. |
|
||||
| 3 | Module: the unit, `/run/hhstream/live.sock`, `port` 9988, `bind` loopback, `fps` 5/cap 10, `enable` false, `openFirewall` false, `publicIndex` false. No host firewall edit here. | M | A second `RuntimeDirectory` on `/run/hhstream` deleting `control.sock`. |
|
||||
| 3 | Module: the unit, `/run/hhstream/live.sock`, `port` 9988, `bind` loopback, `fps` 5/cap 10, `enable` false, `openFirewall` false, `publicIndex` false. No host firewall edit here. | M | A second `RuntimeDirectory` on `/run/hhstream` deleting `control.sock`; and the capture binary — a unit's `PATH` has no `grim`, so the stream serves an empty frame area without saying why (`docs/TODO/capture-binary-and-the-unit-path.md`). |
|
||||
| 4 | Host pass: enable a real session, open the URL in the machine's own Chromium, confirm pixels change without a reload; write down what was on screen. | S | An empty container looking like a broken stream. Confirm the window is on `hh-<id>` first. |
|
||||
|
||||
Test layers are v1's: `tests/unit` for the HTTP/router/phrase with a fake
|
||||
@@ -172,4 +178,18 @@ one at a time; no browser in a VM check.
|
||||
**Stage 1 is built** (`src/hhstream_live/`, `tests/live/`, 51 unit tests): the
|
||||
router, the pages, the phrase and the publisher, runnable standalone via
|
||||
`hhstream-live serve --stream PHRASE=OUTPUT`. The broker verbs and
|
||||
`/run/hhstream/live.sock` are Stage 2.
|
||||
`/run/hhstream/live.sock` are Stage 2.
|
||||
|
||||
**Stage 3 has started, out of order and on purpose** (2026-10-11). A machine
|
||||
had to be able to *reach* a stream before the rest of the app is settled: the
|
||||
operator asked for the port to be open on the deployment machine, where the app
|
||||
runs by hand, and a hand-written firewall line in one machine's config is the
|
||||
wrong place for a fact about this flake. So `sessions.stream { port, bind,
|
||||
openFirewall }` and the single rule it stands for are in `nix/module.nix`, with
|
||||
`checks/vm-stream-firewall.nix` asking the *running* firewall — and a peer
|
||||
outside the guest — whether the configured port is the one that opened.
|
||||
|
||||
What that does **not** do: no unit, no phrases, no `session stream
|
||||
enable|disable|list|status`, and nothing in the module turns a stream on. The
|
||||
app is still started by hand, and the option's whole job is to describe where a
|
||||
stream will be reachable from.
|
||||
@@ -15,6 +15,12 @@
|
||||
in {
|
||||
packages = forAllSystems (pkgs: rec {
|
||||
hhstream = pkgs.callPackage ./nix/package.nix {};
|
||||
# The MCP server. Its own derivation, not another entry point on
|
||||
# `hhstream`: it depends on the `mcp` SDK and `hhstream` is stdlib-only by
|
||||
# policy (nix/mcp.nix says why at length). `packages.hhstream` therefore
|
||||
# keeps the closure it had, which is the property `checks.unit` and
|
||||
# `nix build .#hhstream` are expected to hold.
|
||||
hhstream-mcp = pkgs.callPackage ./nix/mcp.nix {inherit hhstream;};
|
||||
default = hhstream;
|
||||
});
|
||||
|
||||
@@ -28,7 +34,9 @@
|
||||
checks = forAllSystems' ({ pkgs, system }:
|
||||
import ./checks { inherit pkgs self system; });
|
||||
|
||||
devShells = forAllSystems (pkgs: {
|
||||
devShells = forAllSystems (pkgs: let
|
||||
hhstream = pkgs.callPackage ./nix/package.nix {};
|
||||
in {
|
||||
default = pkgs.mkShell {
|
||||
packages = with pkgs; [
|
||||
python3
|
||||
@@ -44,7 +52,16 @@
|
||||
# pywayland and xkbcommon, which `tests/pointer` imports directly --
|
||||
# `test_keymap.py` compiles a real `us` keymap rather than stubbing
|
||||
# one, because a stub cannot tell you that `é` is unmappable.
|
||||
(callPackage ./nix/package.nix { })
|
||||
hhstream
|
||||
# The MCP server, so `hhstream-mcp` can be run (and handed to an MCP
|
||||
# client) straight out of `nix develop`.
|
||||
(callPackage ./nix/mcp.nix {inherit hhstream;})
|
||||
# The SDK itself, because `tests/unit/test_mcp_server.py` imports it
|
||||
# directly: the tool table is stdlib-only and testable without it, but
|
||||
# the wiring that turns the table into `mcp.types.Tool` objects is not,
|
||||
# and a suite that could skip that file would stop noticing a schema
|
||||
# the SDK rejects.
|
||||
python3.pkgs.mcp
|
||||
# `websocket-client` drives Chromium over the DevTools protocol, which
|
||||
# is how the demo types into the page and reads the result back.
|
||||
python3.pkgs.websocket-client
|
||||
|
||||
+114
@@ -0,0 +1,114 @@
|
||||
# `hhstream-mcp` -- the MCP server, as its own derivation.
|
||||
#
|
||||
# Separate from `nix/package.nix` on purpose, and the separation is the point:
|
||||
# the frame socket, the CLI and the broker are stdlib-only by policy
|
||||
# (`pyproject.toml`, `docs/CONTRACT-sessions.md` §6 rule 3), the MCP SDK is a
|
||||
# third-party dependency, and `packages.hhstream` runs as the compositor's own
|
||||
# units. So the dependency lives here, in a package nothing else imports, and
|
||||
# `packages.hhstream` keeps the closure it had.
|
||||
#
|
||||
# `hhstream` is a *library* dependency here and not a binary one: the tools call
|
||||
# `hhstream.cli`'s handlers in process (see that module's docstring), so what
|
||||
# this package needs is the import path. `toPythonModule` is what makes an
|
||||
# application's site-packages visible to a dependent, which a bare
|
||||
# `buildPythonApplication` output is not.
|
||||
#
|
||||
# `grim` and `ffmpeg` do go on PATH, because the CLI itself spawns them --
|
||||
# `shot --output` and `record` are two of the twenty-one tools, and the server
|
||||
# is launched by an MCP client whose PATH is not ours to predict. `--prefix`
|
||||
# and not `--set`, so a deployment that wants its own ahead of these puts them
|
||||
# on PATH and wins.
|
||||
{
|
||||
lib,
|
||||
python3,
|
||||
hhstream,
|
||||
grim,
|
||||
ffmpeg,
|
||||
makeWrapper,
|
||||
}:
|
||||
python3.pkgs.buildPythonApplication {
|
||||
pname = "hhstream-mcp";
|
||||
version = "0.1.0";
|
||||
pyproject = true;
|
||||
|
||||
# The package directory is the project root: its own pyproject.toml lives
|
||||
# there and maps the package name onto `.`. See the comment in that file for
|
||||
# why it is not at the repository root.
|
||||
src = ../src/hhstream_mcp;
|
||||
|
||||
build-system = [ python3.pkgs.setuptools ];
|
||||
|
||||
dependencies = [
|
||||
python3.pkgs.mcp
|
||||
python3.pkgs.anyio
|
||||
# An application is not importable by a dependent until this converts it,
|
||||
# and `hhstream_mcp.invoke` imports `hhstream.cli` directly.
|
||||
(python3.pkgs.toPythonModule hhstream)
|
||||
];
|
||||
|
||||
nativeBuildInputs = [ makeWrapper ];
|
||||
|
||||
makeWrapperArgs = [
|
||||
"--prefix"
|
||||
"PATH"
|
||||
":"
|
||||
"${lib.makeBinPath [
|
||||
grim
|
||||
ffmpeg
|
||||
]}"
|
||||
];
|
||||
|
||||
# The suite lives in `tests/` at the repository root and runs in the flake's
|
||||
# `checks.unit`, which is also where `mcp` reaches it. Same choice as
|
||||
# nix/package.nix, for the same reason.
|
||||
doCheck = false;
|
||||
|
||||
# Cheap proof that both tables build and the SDK wiring imports: `tools` and
|
||||
# `resources` construct every entry at import time, and `server` is the only
|
||||
# module that touches `mcp`. A missing SDK, a schema that is not a dict, or a
|
||||
# tool named twice all fail here rather than at an agent's first call.
|
||||
pythonImportsCheck = [
|
||||
"hhstream_mcp.tools"
|
||||
"hhstream_mcp.resources"
|
||||
"hhstream_mcp.server"
|
||||
];
|
||||
|
||||
# `pythonImportsCheck` proves the modules load; it does not prove the script
|
||||
# Nix wrapped can run, and the script is what an MCP client spawns.
|
||||
# `--list-tools` and `--list-resources` are the two code paths that exercise
|
||||
# argument parsing and both whole tables without opening stdio, so together
|
||||
# they are the honest smoke test. `--toolsets` is in it because a selection
|
||||
# that silently served everything would be the failure nobody notices.
|
||||
#
|
||||
# A `postPhases` entry and not `postInstall`, because the script is wrapped in
|
||||
# `fixupPhase`: run any earlier and it has no PYTHONPATH, so `import mcp`
|
||||
# fails and the check tests the wrong thing. `installCheckPhase` is no use
|
||||
# either -- `buildPythonPackage` does not include that phase at all.
|
||||
postPhases = [ "entryPointCheckPhase" ];
|
||||
entryPointCheckPhase = ''
|
||||
echo "checking the wrapped entry point..."
|
||||
tools=$($out/bin/hhstream-mcp --list-tools)
|
||||
echo "$tools"
|
||||
test "$(echo "$tools" | wc -l)" -eq 21
|
||||
|
||||
resources=$($out/bin/hhstream-mcp --list-resources)
|
||||
echo "$resources"
|
||||
test "$(echo "$resources" | wc -l)" -eq 8
|
||||
|
||||
narrowed=$($out/bin/hhstream-mcp --list-tools --toolsets keyboard | wc -l)
|
||||
echo "--toolsets keyboard offers $narrowed tools"
|
||||
test "$narrowed" -eq 4
|
||||
|
||||
# An unknown toolset must be argparse's exit 2, not a server with no tools.
|
||||
if $out/bin/hhstream-mcp --list-tools --toolsets nonsense; then
|
||||
echo "an unknown toolset was accepted" >&2
|
||||
exit 1
|
||||
fi
|
||||
'';
|
||||
|
||||
meta = {
|
||||
description = "Drive a headless Hyprland session over the Model Context Protocol";
|
||||
license = lib.licenses.mit;
|
||||
mainProgram = "hhstream-mcp";
|
||||
};
|
||||
}
|
||||
+318
@@ -46,6 +46,12 @@ let
|
||||
brokerRuntimeDir = "/run/${brokerRuntimeDirName}";
|
||||
controlSocket = "${brokerRuntimeDir}/control.sock";
|
||||
pointerSocket = "${brokerRuntimeDir}/pointer.sock";
|
||||
liveSocket = "${brokerRuntimeDir}/live.sock";
|
||||
|
||||
# Addresses that mean "this listener answers on loopback only". The spelling
|
||||
# `localhost` is included because it is what a person writes; it is not a
|
||||
# resolution the module performs.
|
||||
loopbackBinds = [ "127.0.0.1" "::1" "localhost" ];
|
||||
|
||||
socketDir = builtins.dirOf cfg.socketPath;
|
||||
|
||||
@@ -159,6 +165,35 @@ let
|
||||
done
|
||||
exec ${lib.getExe' cfg.package "hhstream-server"} "$@"
|
||||
'';
|
||||
|
||||
# The same problem, for the stream daemon, one step worse.
|
||||
#
|
||||
# `grim` is an ordinary Wayland client: it needs XDG_RUNTIME_DIR *and* the
|
||||
# name of the socket the compositor actually bound, and that name is only
|
||||
# known once the compositor is up -- so, exactly as above, it cannot be an
|
||||
# `Environment=` line.
|
||||
#
|
||||
# MEASURED, in checks/vm-stream.nix, which is the check that exists to find
|
||||
# this: with the group but without the environment, the unit came up
|
||||
# `active (running)`, the broker attached, `stream status` said
|
||||
# `attached: true`, and every capture failed with
|
||||
#
|
||||
# grim: error: XDG_RUNTIME_DIR is invalid or not set in the environment.
|
||||
#
|
||||
# until the publisher gave up after ten in a row. A viewer with the right
|
||||
# phrase got a page and no frames, and nothing in the session's own state
|
||||
# said why -- the sibling failure to
|
||||
# docs/TODO/capture-binary-and-the-unit-path.md, and the reason this unit
|
||||
# spells out the whole capture command *and* hands it a session.
|
||||
execLive = pkgs.writeShellScript "hhstream-exec-live" ''
|
||||
for candidate in "$XDG_RUNTIME_DIR"/wayland-*; do
|
||||
if [ -S "$candidate" ]; then
|
||||
export WAYLAND_DISPLAY="''${candidate##*/}"
|
||||
break
|
||||
fi
|
||||
done
|
||||
exec ${lib.getExe' cfg.package "hhstream-live"} "$@"
|
||||
'';
|
||||
hyprlandConf = pkgs.writeText "hyprland.conf" (import ./hyprland-conf.nix {
|
||||
inherit lib;
|
||||
inherit (cfg) outputs extraConfig;
|
||||
@@ -694,6 +729,105 @@ in {
|
||||
};
|
||||
};
|
||||
|
||||
# The session-stream web app — `hhstream-live`, the router that serves a
|
||||
# live view of one session per phrase, over one port
|
||||
# (`docs/plans/2026-10-04-session-stream-webapp.md`, Stage 2 and 3).
|
||||
#
|
||||
# `enable` runs the unit and hands the broker `/run/hhstream/live.sock`,
|
||||
# over which `hhstream session stream enable <id>` switches one stream
|
||||
# on. Everything else here is the *reach* of it: the port every stream
|
||||
# shares, the address it binds, and whether that port is opened in the
|
||||
# firewall.
|
||||
#
|
||||
# Running it still turns nothing on. A stream exists only for the
|
||||
# sessions it was enabled on — a stream is switched on per session, never
|
||||
# for all of them — so `enable = true` is a listener serving one form
|
||||
# until somebody asks for a session.
|
||||
stream = {
|
||||
enable = lib.mkOption {
|
||||
type = lib.types.bool;
|
||||
default = false;
|
||||
description = ''
|
||||
Run `hhstream-live`, the web app that publishes one session's
|
||||
screen at a URL whose path is a spoken phrase, and give the broker
|
||||
the socket it switches streams on over
|
||||
(`/run/hhstream/live.sock`).
|
||||
|
||||
Off by default, and running it turns **nothing** on: a stream
|
||||
exists only for the sessions `hhstream session stream enable` was
|
||||
called on, and until then this is a listener serving one form.
|
||||
That is deliberate — a live view of a desktop is readable by
|
||||
anyone who can reach the port and guess the phrase, so switching
|
||||
one on is a per-session act and never a consequence of the service
|
||||
being up.
|
||||
|
||||
Needs {option}`sessions.enable`: the phrase lives in the session
|
||||
record, and there are no sessions without the broker.
|
||||
'';
|
||||
};
|
||||
|
||||
fps = lib.mkOption {
|
||||
type = lib.types.ints.positive;
|
||||
default = 5;
|
||||
description = ''
|
||||
Frames a second a stream captures at when nobody says otherwise.
|
||||
|
||||
Five is one frame per ~200 ms plus a ~46 ms `grim`, measured rather
|
||||
than guessed; the daemon's own hard cap is 10, because this box is
|
||||
also running the compositor and the main frame publisher. Capture
|
||||
happens **only while somebody is connected**, so an enabled stream
|
||||
nobody is watching costs nothing at any rate.
|
||||
|
||||
`hhstream session stream enable --fps N` overrides it per stream.
|
||||
'';
|
||||
};
|
||||
|
||||
port = lib.mkOption {
|
||||
type = lib.types.port;
|
||||
default = 9988;
|
||||
description = ''
|
||||
The single TCP port every stream shares.
|
||||
|
||||
One listener rather than one per session is what makes the phrase
|
||||
speakable: there is one address to give a person, one thing to
|
||||
firewall and one thing to stop. It is also why this is a fixed
|
||||
number with no range to fall back on — a stream at a port nobody
|
||||
was told about is worse than a stream that is down, so a taken port
|
||||
fails loudly instead of moving.
|
||||
'';
|
||||
};
|
||||
|
||||
bind = lib.mkOption {
|
||||
type = lib.types.str;
|
||||
default = "127.0.0.1";
|
||||
description = ''
|
||||
The address the web app will bind.
|
||||
|
||||
Loopback by default, where the reachable path is an ssh tunnel
|
||||
(`ssh -L 9988:127.0.0.1:9988`) and nothing else. Set it to an
|
||||
address a peer can reach (`"0.0.0.0"`) when
|
||||
{option}`sessions.stream.openFirewall` is set: opening the port for
|
||||
a listener that is not on it is a hole with no service behind it,
|
||||
which is why that pairing is refused rather than allowed.
|
||||
'';
|
||||
};
|
||||
|
||||
openFirewall = lib.mkOption {
|
||||
type = lib.types.bool;
|
||||
default = false;
|
||||
description = ''
|
||||
Open {option}`sessions.stream.port` in the firewall.
|
||||
|
||||
Off by default, and deliberately not implied by
|
||||
{option}`sessions.enable`: a live view of this desktop is readable
|
||||
by anyone who can reach the port, and the phrase in the URL is its
|
||||
only credential — no TLS, no second factor
|
||||
(`docs/plans/2026-10-04-…` §4). Opening it is an explicit act, and
|
||||
it opens exactly one port.
|
||||
'';
|
||||
};
|
||||
};
|
||||
|
||||
stateDir = lib.mkOption {
|
||||
type = lib.types.str;
|
||||
default = "/var/lib/hhstream";
|
||||
@@ -710,6 +844,48 @@ in {
|
||||
'';
|
||||
};
|
||||
};
|
||||
|
||||
# The Model Context Protocol server -- `hhstream-mcp`, the `hhstream` CLI
|
||||
# as typed tools, so an agent drives this desktop without shelling out.
|
||||
#
|
||||
# Its own top-level block rather than one under `sessions`, because it is
|
||||
# not the broker's: four of its tools (`status`, `shot`, `record`, `run`)
|
||||
# are frame-socket verbs that work with the broker switched off. It is also
|
||||
# not a unit. The transport is stdio, one process per client, spawned by
|
||||
# whichever client wants it -- so "installing" it means exactly putting the
|
||||
# binary on PATH, and anything that started a daemon here would be
|
||||
# inventing a second thing to supervise.
|
||||
mcp = {
|
||||
enable = lib.mkOption {
|
||||
type = lib.types.bool;
|
||||
default = false;
|
||||
description = ''
|
||||
Put `hhstream-mcp` on the system PATH, so an MCP client on this
|
||||
machine can spawn it.
|
||||
|
||||
Off by default, and deliberately not implied by
|
||||
{option}`sessions.enable`: this is the surface through which a
|
||||
language model starts applications, clicks and types on this desktop,
|
||||
and whether that is wanted is a decision, not a consequence of the
|
||||
broker being up. Installing it starts nothing — the server is stdio
|
||||
and short-lived, spawned per client — and it grants no access the
|
||||
`hhstream` CLI does not already grant to whoever runs it.
|
||||
|
||||
The client configures the sockets through the CLI's own environment,
|
||||
`HHSTREAM_SOCKET` and `HHSTREAM_FRAME_SOCKET`; see the README section
|
||||
on registering it.
|
||||
'';
|
||||
};
|
||||
|
||||
package = lib.mkOption {
|
||||
type = lib.types.package;
|
||||
description = ''
|
||||
The MCP server package. Defaults to this flake's `hhstream-mcp`,
|
||||
built against {option}`package` so the server and the CLI it drives
|
||||
are the same build.
|
||||
'';
|
||||
};
|
||||
};
|
||||
};
|
||||
|
||||
config = lib.mkIf cfg.enable {
|
||||
@@ -769,6 +945,21 @@ in {
|
||||
so without the broker it would bind a socket nothing connects to.
|
||||
'';
|
||||
}
|
||||
{
|
||||
assertion =
|
||||
!cfg.sessions.stream.openFirewall
|
||||
|| !(lib.elem cfg.sessions.stream.bind loopbackBinds);
|
||||
message = ''
|
||||
services.hyprland-headless-stream.sessions.stream.openFirewall is true
|
||||
while sessions.stream.bind is "${cfg.sessions.stream.bind}" — a loopback
|
||||
address. The port would be open in the firewall with nothing answering on
|
||||
it from anywhere but this machine, which is a hole rather than a feature.
|
||||
|
||||
Set sessions.stream.bind to an address a peer can reach ("0.0.0.0"), or
|
||||
leave the firewall closed and reach the stream through a tunnel
|
||||
(`ssh -L 9988:127.0.0.1:9988`).
|
||||
'';
|
||||
}
|
||||
{
|
||||
assertion = !cfg.sessions.enable || lib.hasAttr cfg.sessions.user config.users.users;
|
||||
message = ''
|
||||
@@ -786,6 +977,31 @@ in {
|
||||
services.hyprland-headless-stream.package =
|
||||
lib.mkDefault (pkgs.callPackage ./package.nix {});
|
||||
|
||||
# Built against `cfg.package`, so the server and the CLI it runs are one
|
||||
# build: the tools are argv lists against that CLI's parser, and a server
|
||||
# paired with a different one would refuse flags for reasons no agent could
|
||||
# read. `mkDefault` for the same reason as above.
|
||||
services.hyprland-headless-stream.mcp.package =
|
||||
lib.mkDefault (pkgs.callPackage ./mcp.nix { hhstream = cfg.package; });
|
||||
|
||||
# Installing it IS the whole of `mcp.enable`: the server is spawned by a
|
||||
# client over stdio, so there is no unit, no socket and no state directory
|
||||
# to declare.
|
||||
environment.systemPackages = lib.mkIf cfg.mcp.enable [ cfg.mcp.package ];
|
||||
|
||||
# A warning and not an assertion: eighteen of the twenty-one tools and six
|
||||
# of the eight resources need the broker, and an agent handed them against
|
||||
# a machine where it is off gets exit 5 from every one of them -- which is
|
||||
# a true answer, badly timed. The frame tools are genuinely useful on their
|
||||
# own, so this is a thing worth saying rather than a thing worth refusing.
|
||||
warnings = lib.optional (cfg.mcp.enable && !cfg.sessions.enable) ''
|
||||
services.hyprland-headless-stream.mcp.enable is on while sessions.enable
|
||||
is off: the MCP server's session, pointer and keyboard tools, and every
|
||||
resource but hhstream://status and hhstream://screen, will fail because
|
||||
the broker is unreachable (exit 5). Only shot, record, run and those two
|
||||
resources will work.
|
||||
'';
|
||||
|
||||
# The broker's state directory and the moved socket directory are two
|
||||
# different reasons to write a tmpfiles entry, and this option takes one
|
||||
# definition — so they are merged here rather than assigned twice (which
|
||||
@@ -831,6 +1047,17 @@ in {
|
||||
})
|
||||
];
|
||||
|
||||
# The stream's one port, in the firewall.
|
||||
#
|
||||
# `lib.optional`, not a conditional block: the option is one line and its
|
||||
# effect is one port in the rule set, so there is nothing here that could
|
||||
# open a second one. Everything else about the app — the phrase per
|
||||
# session, the capture, the enable/disable verbs — is later stages of the
|
||||
# plan; this is the only part of the stream that a machine declares before
|
||||
# any of that exists.
|
||||
networking.firewall.allowedTCPPorts =
|
||||
lib.optional cfg.sessions.stream.openFirewall cfg.sessions.stream.port;
|
||||
|
||||
users.users.${cfg.user} = {
|
||||
isSystemUser = true;
|
||||
group = cfg.group;
|
||||
@@ -1081,5 +1308,96 @@ in {
|
||||
];
|
||||
};
|
||||
};
|
||||
|
||||
# The stream daemon. A third executor beside the pointer driver, and the
|
||||
# split is the driver's: `grim` blocks tens to hundreds of milliseconds, so
|
||||
# the capture must not run where `touch` and `kill` are answered, and a
|
||||
# LAN-facing HTTP parser must not run in the frame server whose one-socket
|
||||
# contract cannot grow one (docs/CONTRACT-sessions.md §3.5).
|
||||
systemd.services.hhstream-live = lib.mkIf (cfg.sessions.enable && cfg.sessions.stream.enable) {
|
||||
description = "Per-session live stream for the headless Hyprland desktop";
|
||||
wantedBy = ["multi-user.target"];
|
||||
after = ["hyprland-headless.service"];
|
||||
# `BindsTo` for the pointer driver's reason: this process captures from
|
||||
# that compositor's outputs through `grim`, so when the compositor goes
|
||||
# it has nothing left to capture. The broker reports such a stream as
|
||||
# `attached: false` rather than pretending, and re-enabling re-attaches.
|
||||
bindsTo = ["hyprland-headless.service"];
|
||||
|
||||
environment = {
|
||||
PYTHONUNBUFFERED = "1";
|
||||
# The compositor's session, not this unit's own: `grim` has to find the
|
||||
# Wayland socket in here. `WAYLAND_DISPLAY` is set by `execLive` at
|
||||
# start, because the socket's name is only known once the compositor
|
||||
# has bound it. HOME is deliberately NOT redirected here the way the
|
||||
# frame server's is -- this unit runs as the operator's account, and
|
||||
# the compositor's runtime directory is not writable by it.
|
||||
XDG_RUNTIME_DIR = runtimeDir;
|
||||
};
|
||||
|
||||
serviceConfig = {
|
||||
Type = "simple";
|
||||
User = cfg.sessions.user;
|
||||
# The compositor's runtime directory is 0750 and owned by this group,
|
||||
# and `grim` is a Wayland client of it -- same reason the pointer
|
||||
# driver needs the group, one step further: this one has to *capture*,
|
||||
# not merely find the socket.
|
||||
SupplementaryGroups = [cfg.sessions.group];
|
||||
|
||||
# No `RuntimeDirectory`: /run/hhstream belongs to the broker's unit and
|
||||
# to the tmpfiles entry above, and a second RuntimeDirectory= on the
|
||||
# same path would delete the broker's control socket when this unit
|
||||
# stopped. The plan calls this out by name as the Stage 3 risk.
|
||||
WorkingDirectory = brokerRuntimeDir;
|
||||
UMask = "0007";
|
||||
|
||||
Restart = "on-failure";
|
||||
RestartSec = 1;
|
||||
NoNewPrivileges = true;
|
||||
KillMode = "process";
|
||||
|
||||
# `grim` is NOT on a unit's PATH, and the symptom of leaving it off is
|
||||
# a stream that serves an empty frame area without saying why --
|
||||
# docs/TODO/capture-binary-and-the-unit-path.md, found the first time
|
||||
# the capture ran as a unit rather than from a login shell. So the
|
||||
# whole capture command is spelled out here, with grim's store path.
|
||||
#
|
||||
# `--capture-command=<word>` and not `--capture-command <word>`:
|
||||
# MEASURED, as a unit crash-looping with
|
||||
#
|
||||
# hhstream-live serve: error: argument --capture-command: expected
|
||||
# one argument
|
||||
#
|
||||
# because grim's last word is a bare `-` (its "write to stdout"), and
|
||||
# argparse reads a lone dash as an option prefix rather than a value.
|
||||
# The `=` form is unambiguous for every word, so it is used for every
|
||||
# word rather than only the one that needs it.
|
||||
# Same second line of defence as the frame server's: `BindsTo=` stops
|
||||
# this unit when the compositor goes, but the compositor is only
|
||||
# *ready* once its socket is bound, and `execLive` has to find that
|
||||
# socket to export its name.
|
||||
ExecStartPre = "${findSession} >/dev/null";
|
||||
|
||||
ExecStart = lib.escapeShellArgs (
|
||||
[
|
||||
execLive
|
||||
"serve"
|
||||
"--control-socket=${liveSocket}"
|
||||
"--bind=${cfg.sessions.stream.bind}"
|
||||
"--port=${toString cfg.sessions.stream.port}"
|
||||
"--fps=${toString cfg.sessions.stream.fps}"
|
||||
]
|
||||
++ map (word: "--capture-command=${word}") [
|
||||
(lib.getExe pkgs.grim)
|
||||
"-c" # include the cursor
|
||||
"-t"
|
||||
"jpeg"
|
||||
"-q"
|
||||
"80"
|
||||
"-" # write to stdout
|
||||
]
|
||||
);
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
+26
-3
@@ -35,12 +35,35 @@ python3.pkgs.buildPythonApplication {
|
||||
"hhstream_pointer.keymap"
|
||||
"hhstream_pointer._protocol.wlr_virtual_pointer_unstable_v1"
|
||||
"hhstream_pointer._protocol.virtual_keyboard_unstable_v1"
|
||||
# The web app. Importing the server pulls in the router, the publisher and
|
||||
# the pages; the phrase generator's wordlist is checked by the unit suite,
|
||||
# which reads the *installed* package.
|
||||
# The web app: importing the server pulls in the router, the publisher and
|
||||
# the pages.
|
||||
"hhstream_live.server"
|
||||
# The two halves of `live.sock` (CONTRACT-sessions.md §3.5). Both are
|
||||
# stdlib-only, and they are named here because they are the one pair in
|
||||
# this package that has to agree with each other across two processes --
|
||||
# so an import error in either is worth finding at build time rather than
|
||||
# the first time an operator enables a stream.
|
||||
"hhstream_live.control"
|
||||
"hhstreamd.live"
|
||||
];
|
||||
|
||||
# `pythonImportsCheck` only *imports*, and `hhstream_live.phrase` reads its
|
||||
# wordlist lazily -- so a wheel that dropped `wordlist.txt` would sail past it
|
||||
# and fail at the first `enable` instead. Read the list for real, against the
|
||||
# installed tree, and mint a phrase so the generator and its validator are
|
||||
# proven on the same words. `doCheck = false` (the suite runs in the flake's
|
||||
# `checks`), so this is the only place the packaged data is exercised.
|
||||
postFixup = ''
|
||||
echo "checking the installed wordlist..."
|
||||
PYTHONPATH="$out/${python3.sitePackages}:$PYTHONPATH" ${python3.interpreter} -c '
|
||||
import hhstream_live.phrase as phrase
|
||||
count = len(phrase.words())
|
||||
assert count > 7000, f"wordlist has only {count} words; is wordlist.txt installed?"
|
||||
assert phrase.validate(phrase.generate())
|
||||
print(f"wordlist ok: {count} words, ~{phrase.entropy_bits():.1f} bits a phrase")
|
||||
'
|
||||
'';
|
||||
|
||||
meta = {
|
||||
description = "Publish a headless Hyprland session's frames on a Unix socket";
|
||||
license = lib.licenses.mit;
|
||||
|
||||
@@ -34,6 +34,15 @@ hhstream-live = "hhstream_live.__main__:main"
|
||||
|
||||
[tool.setuptools.packages.find]
|
||||
where = ["src"]
|
||||
# `hhstream_mcp` lives under src/ beside the others -- so the dev shell's
|
||||
# PYTHONPATH reaches it and the tests import it the same way they import
|
||||
# everything else -- but it is a *different distribution*
|
||||
# (src/hhstream_mcp/pyproject.toml, built by nix/mcp.nix) because it depends on
|
||||
# the MCP SDK. Without this exclusion `find` would sweep it into this wheel,
|
||||
# and `packages.hhstream` would ship a module whose first import line fails:
|
||||
# the dependency policy above would be intact and the package would still be
|
||||
# broken.
|
||||
exclude = ["hhstream_mcp*"]
|
||||
|
||||
# The phrase generator reads this at runtime, so it has to be *installed*, not
|
||||
# just present in the checkout: a wheel (and the Nix build) that dropped it
|
||||
|
||||
+132
-21
@@ -17,12 +17,16 @@ from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import logging
|
||||
import signal
|
||||
import sys
|
||||
import threading
|
||||
|
||||
from . import phrase as phrase_mod
|
||||
from .publisher import DEFAULT_FPS, FPS_CAP, StreamRegistry, StreamSpec
|
||||
from .server import DEFAULT_HOST, DEFAULT_PORT, LiveServer
|
||||
|
||||
log = logging.getLogger("hhstream.live")
|
||||
|
||||
#: The session's own capture command, JPEG for the same reason the host config
|
||||
#: spells it out: a 1280x720 JPEG q80 is ~46 ms and the point is a video, not a
|
||||
#: slideshow. `-c` asks grim to include the cursor.
|
||||
@@ -53,13 +57,27 @@ def parse_stream(arg: str) -> tuple[str, str]:
|
||||
raise argparse.ArgumentTypeError(str(exc)) from exc
|
||||
|
||||
|
||||
def _add_log_level(parser: argparse.ArgumentParser, default: str) -> None:
|
||||
"""Put `--log-level` on a parser.
|
||||
|
||||
It is a global option, but it has to exist on the subparsers too: with no
|
||||
subcommand the whole line is parsed as `serve ...`, and `serve` is then the
|
||||
parser that sees it. `SUPPRESS` as the subparser default is what stops
|
||||
`hhstream-live --log-level debug serve` from being reset to `info` -- a
|
||||
subparser argument that defaults to `SUPPRESS` and is not supplied leaves
|
||||
the namespace alone.
|
||||
"""
|
||||
parser.add_argument("--log-level", default=default,
|
||||
choices=["debug", "info", "warning", "error"])
|
||||
|
||||
|
||||
def build_parser() -> argparse.ArgumentParser:
|
||||
parser = argparse.ArgumentParser(prog="hhstream-live", description=__doc__)
|
||||
parser.add_argument("--log-level", default="info",
|
||||
choices=["debug", "info", "warning", "error"])
|
||||
_add_log_level(parser, "info")
|
||||
subs = parser.add_subparsers(dest="command")
|
||||
|
||||
serve = subs.add_parser("serve", help="run the web app (default)")
|
||||
_add_log_level(serve, argparse.SUPPRESS)
|
||||
serve.add_argument("--port", type=int, default=DEFAULT_PORT,
|
||||
help=f"the one port every stream shares (default {DEFAULT_PORT})")
|
||||
serve.add_argument("--bind", default=DEFAULT_HOST,
|
||||
@@ -70,17 +88,49 @@ def build_parser() -> argparse.ArgumentParser:
|
||||
serve.add_argument("--stream", action="append", default=[], type=parse_stream,
|
||||
metavar="PHRASE=OUTPUT",
|
||||
help="enable a stream on this output; repeatable")
|
||||
serve.add_argument(
|
||||
"--control-socket",
|
||||
metavar="PATH",
|
||||
help="serve the broker's control socket here (CONTRACT-sessions.md "
|
||||
"§3.5), so `hhstream session stream enable` can attach a stream. "
|
||||
"Omitted, the app is standalone and only --stream puts anything on it.",
|
||||
)
|
||||
serve.add_argument("--capture-command", action="append", default=None,
|
||||
metavar="WORD",
|
||||
help="capture argv word; repeat (a repeated flag is the "
|
||||
"only shape that survives words starting with '-')")
|
||||
|
||||
gen = subs.add_parser("phrase", help="print a fresh phrase and exit")
|
||||
_add_log_level(gen, argparse.SUPPRESS)
|
||||
gen.add_argument("--count", type=int, default=1)
|
||||
|
||||
return parser
|
||||
|
||||
|
||||
#: The subcommands, named here because the default one is chosen before the
|
||||
#: parser runs. See `parse_args`.
|
||||
COMMANDS = ("serve", "phrase")
|
||||
|
||||
|
||||
def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
|
||||
"""Parse the command line, defaulting to `serve`.
|
||||
|
||||
`serve` is the default, and its options live on its own subparser, so the
|
||||
word has to be *inserted* rather than filled in afterwards: a namespace from
|
||||
the top-level parser has no `capture_command`, no `port` and no `stream`, and
|
||||
`cmd_serve` would die on the first attribute it read. Inserting it has to
|
||||
happen before parsing, too -- `hhstream-live --port 9999` would otherwise be
|
||||
rejected for an unknown `--port` before anything could be defaulted.
|
||||
|
||||
`--help` is left alone so that a bare `hhstream-live --help` still shows the
|
||||
program's own help rather than `serve`'s.
|
||||
"""
|
||||
raw = list(sys.argv[1:] if argv is None else argv)
|
||||
if not any(word in COMMANDS or word in ("-h", "--help") for word in raw):
|
||||
raw = ["serve", *raw]
|
||||
return build_parser().parse_args(raw)
|
||||
|
||||
|
||||
def make_registry(streams: list[tuple[str, str]], capture_base: list[str],
|
||||
fps: int) -> StreamRegistry:
|
||||
from hhstream.capture import CommandCapture
|
||||
@@ -96,43 +146,104 @@ def cmd_serve(args: argparse.Namespace) -> int:
|
||||
capture_base = args.capture_command or DEFAULT_CAPTURE
|
||||
registry = make_registry(args.stream, capture_base, args.fps)
|
||||
server = LiveServer(registry, host=args.bind, port=args.port)
|
||||
control = control_server(args, registry, server, capture_base)
|
||||
|
||||
print(f"landing page: http://{server.address}:{args.port}/", file=sys.stderr)
|
||||
if not args.stream:
|
||||
print("no --stream given; only the landing page will answer", file=sys.stderr)
|
||||
server.start() # raises OSError loudly if the port is taken
|
||||
for phrase in registry.phrases():
|
||||
print(server.url_for(phrase))
|
||||
sys.stdout.flush()
|
||||
# A service is stopped with SIGTERM, not with Ctrl-C: without a handler the
|
||||
# default action kills the process outright and `server.stop` never runs, so
|
||||
# the listener and the capture threads go down with no ordering at all.
|
||||
# Installed *before* the listener exists, so there is no window in which a
|
||||
# supervisor's very first signal is the fatal one.
|
||||
stopping = threading.Event()
|
||||
previous = None
|
||||
|
||||
def _request_stop(signum, frame) -> None: # noqa: ARG001 - handler signature
|
||||
stopping.set()
|
||||
|
||||
try:
|
||||
import time
|
||||
previous = signal.signal(signal.SIGTERM, _request_stop)
|
||||
except ValueError:
|
||||
# Not the main thread: an embedder's problem to solve, not ours.
|
||||
log.debug("SIGTERM handler not installed (not the main thread)")
|
||||
|
||||
while True:
|
||||
time.sleep(3600)
|
||||
try:
|
||||
server.start() # raises OSError loudly if the port is taken
|
||||
if control is not None:
|
||||
# After the listener, because `attach` replies with a URL and the
|
||||
# URL has no answer until the port is bound -- a requested port of
|
||||
# 0 least of all.
|
||||
control.listen()
|
||||
threading.Thread(
|
||||
target=control.serve_forever,
|
||||
name="hhstream-live.control",
|
||||
daemon=True,
|
||||
).start()
|
||||
print(f"control socket: {control.socket_path}", file=sys.stderr)
|
||||
# Printed after `start`, because a requested port of 0 only has an answer
|
||||
# once it is bound. `describe_bind` names the real bind, so `0.0.0.0` is
|
||||
# not reported as loopback just because that is the address you click.
|
||||
print(server.describe_bind(), file=sys.stderr)
|
||||
print(f"landing page: http://{server.address}:{server.port}/", file=sys.stderr)
|
||||
if not args.stream and control is None:
|
||||
print("no --stream and no --control-socket; only the landing page "
|
||||
"will answer", file=sys.stderr)
|
||||
for phrase in registry.phrases():
|
||||
print(server.url_for(phrase))
|
||||
sys.stdout.flush()
|
||||
stopping.wait()
|
||||
print("stopping", file=sys.stderr)
|
||||
except KeyboardInterrupt:
|
||||
print("stopping", file=sys.stderr)
|
||||
finally:
|
||||
if previous is not None:
|
||||
signal.signal(signal.SIGTERM, previous)
|
||||
if control is not None:
|
||||
# Before the HTTP listener: the broker's next `attach` should fail
|
||||
# to connect rather than be accepted by a process on its way out.
|
||||
control.close()
|
||||
server.stop()
|
||||
return 0
|
||||
|
||||
|
||||
def control_server(
|
||||
args: argparse.Namespace,
|
||||
registry: StreamRegistry,
|
||||
server: LiveServer,
|
||||
capture_base: list[str],
|
||||
) -> "ControlServer | None":
|
||||
"""The broker's control socket, or ``None`` for a standalone run.
|
||||
|
||||
The two things only this process knows are injected here and nowhere else:
|
||||
how to build a capture for an output (the capture command, from this unit's
|
||||
argv) and how to name a URL (the bound port). That is the whole reason
|
||||
`attach` replies with a URL instead of letting the broker assemble one.
|
||||
"""
|
||||
|
||||
if not getattr(args, "control_socket", None):
|
||||
return None
|
||||
from .control import Control, ControlServer
|
||||
|
||||
from hhstream.capture import CommandCapture
|
||||
|
||||
control = Control(
|
||||
registry,
|
||||
capture_for=lambda output: CommandCapture(capture_argv(capture_base, output)),
|
||||
url_for=server.url_for,
|
||||
default_fps=args.fps,
|
||||
)
|
||||
return ControlServer(args.control_socket, control)
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
parser = build_parser()
|
||||
args = parser.parse_args(argv)
|
||||
args = parse_args(argv)
|
||||
logging.basicConfig(
|
||||
level=getattr(logging, (args.log_level or "info").upper()),
|
||||
level=getattr(logging, (getattr(args, "log_level", None) or "info").upper()),
|
||||
format="%(asctime)s %(levelname)s %(name)s: %(message)s",
|
||||
)
|
||||
command = args.command or "serve"
|
||||
if command == "phrase":
|
||||
if args.command == "phrase":
|
||||
for _ in range(args.count):
|
||||
print(phrase_mod.generate())
|
||||
return 0
|
||||
if command == "serve":
|
||||
return cmd_serve(args)
|
||||
parser.error(f"unknown command {command!r}") # pragma: no cover
|
||||
return 2
|
||||
return cmd_serve(args)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@@ -0,0 +1,317 @@
|
||||
"""``/run/hhstream/live.sock`` — the broker tells this process what to publish.
|
||||
|
||||
The daemon's end of `docs/CONTRACT-sessions.md` §3.5. Four ops (`attach`,
|
||||
`detach`, `list`, `viewers`) over newline-delimited JSON, in the shape the
|
||||
pointer driver's socket already uses, because a second convention for the same
|
||||
job would be a second thing to remember.
|
||||
|
||||
**This process decides nothing about sessions.** It does not know what an idle
|
||||
clock is, which application a session runs, or whether a stream *should* be on.
|
||||
It is told a phrase, an output and a rate, and it publishes. `viewers` is a
|
||||
counter read; what it means is the broker's business
|
||||
(`docs/CONTRACT-sessions.md` §4).
|
||||
|
||||
**It does own the port, the bind address and the capture command**, from its own
|
||||
unit's argv — which is why `attach` replies with the URL rather than letting the
|
||||
broker assemble one. A URL built from a port somebody was told about once is a
|
||||
URL that lies the first time the listener moves.
|
||||
|
||||
**`attach` is idempotent on the phrase.** The same phrase aimed at the same
|
||||
output returns the running stream instead of starting a second capture: the
|
||||
broker re-attaches after a restart, and doubling the ``grim`` rate on one output
|
||||
because of a reconnect would be a self-inflicted load problem. The same phrase
|
||||
aimed somewhere *else* is refused — a phrase is a credential for one view, and
|
||||
silently re-pointing it would show a person a desktop they were not given.
|
||||
|
||||
**The phrase is never logged**, here or in the broker. Every line below names
|
||||
the output and the session.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
import os
|
||||
import socket
|
||||
import threading
|
||||
from pathlib import Path
|
||||
from typing import Any, Callable
|
||||
|
||||
from . import phrase as phrase_mod
|
||||
from .publisher import DEFAULT_FPS, FPS_CAP, StreamRegistry, StreamSpec
|
||||
|
||||
log = logging.getLogger("hhstream.live.control")
|
||||
|
||||
#: Matches ``hhstreamd.protocol.MAX_LINE_BYTES`` and the pointer driver's.
|
||||
MAX_LINE_BYTES = 1 << 20
|
||||
LISTEN_BACKLOG = 8
|
||||
|
||||
#: A rejection the broker maps to exit 2 rather than exit 10 -- the caller's
|
||||
#: mistake, not a failure of this process. Same vocabulary as the driver's.
|
||||
INVALID = "invalid_argument"
|
||||
|
||||
|
||||
class Control:
|
||||
"""The op handler. Holds the registry and the two things only this process knows.
|
||||
|
||||
``capture_for`` turns an output name into a capture object, and ``url_for``
|
||||
turns a phrase into this listener's URL. Both are injected rather than
|
||||
built here so the tests can drive the whole protocol without a compositor
|
||||
and without binding a port.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
registry: StreamRegistry,
|
||||
*,
|
||||
capture_for: Callable[[str], Any],
|
||||
url_for: Callable[[str], str],
|
||||
default_fps: int = DEFAULT_FPS,
|
||||
) -> None:
|
||||
self.registry = registry
|
||||
self.capture_for = capture_for
|
||||
self.url_for = url_for
|
||||
#: The rate an `attach` with no `fps` gets. This process's, from its
|
||||
#: own argv, because it is the one that has to keep up with it -- and
|
||||
#: so an operator's `sessions.stream.fps` reaches every stream rather
|
||||
#: than only the ones somebody named a rate for.
|
||||
self.default_fps = int(default_fps)
|
||||
self._lock = threading.Lock()
|
||||
|
||||
# -- the ops ----------------------------------------------------------
|
||||
|
||||
def handle(self, request: Any) -> dict[str, Any]:
|
||||
if not isinstance(request, dict):
|
||||
return _no(f"request is not an object: {type(request).__name__}", INVALID)
|
||||
op = request.get("op")
|
||||
handler = {
|
||||
"attach": self._attach,
|
||||
"detach": self._detach,
|
||||
"list": self._list,
|
||||
"viewers": self._viewers,
|
||||
}.get(op if isinstance(op, str) else "")
|
||||
if handler is None:
|
||||
return _no(f"unknown op: {op!r}", INVALID)
|
||||
# One op at a time: `attach` reads the registry and then mutates it, and
|
||||
# two brokers (or a broker and a restart sweep) must not interleave
|
||||
# there and start two captures for one phrase.
|
||||
with self._lock:
|
||||
try:
|
||||
return handler(request)
|
||||
except Rejected as refused:
|
||||
return _no(str(refused), refused.kind)
|
||||
except (ValueError, TypeError) as exc:
|
||||
# The registry's own validation (`fps must be a positive int`,
|
||||
# `phrase ... is already enabled`) surfaces here. It is the
|
||||
# caller's mistake, so it is exit 2 and not a daemon failure.
|
||||
return _no(str(exc), INVALID)
|
||||
|
||||
def _attach(self, request: dict[str, Any]) -> dict[str, Any]:
|
||||
phrase = _phrase_of(request)
|
||||
output = _text(request, "output")
|
||||
fps = _fps(request, self.default_fps)
|
||||
session = request.get("session")
|
||||
session = None if session is None else str(session)
|
||||
label = str(request.get("label") or "")
|
||||
|
||||
existing = self.registry.get(phrase)
|
||||
if existing is not None:
|
||||
if existing.spec.output != output:
|
||||
raise Rejected(
|
||||
f"that phrase is already publishing output "
|
||||
f"{existing.spec.output!r}, not {output!r}; disable it first",
|
||||
INVALID,
|
||||
)
|
||||
# Idempotent: the running stream, with whatever rate it was started
|
||||
# at. A new `fps` is deliberately NOT applied here -- changing the
|
||||
# rate under a connected viewer is a `disable`/`enable`, which is
|
||||
# one record write and one obvious act, rather than a silent
|
||||
# re-rate that no log line would explain.
|
||||
log.info("re-attached output %s for %s", output, session or "a standalone stream")
|
||||
return {"ok": True, "stream": self._describe(existing)}
|
||||
|
||||
spec = StreamSpec(
|
||||
phrase=phrase, output=output, fps=fps, session=session, label=label or output
|
||||
)
|
||||
stream = self.registry.add(spec, self.capture_for(output))
|
||||
log.info(
|
||||
"attached output %s for %s at %s fps",
|
||||
output,
|
||||
session or "a standalone stream",
|
||||
fps,
|
||||
)
|
||||
return {"ok": True, "stream": self._describe(stream)}
|
||||
|
||||
def _detach(self, request: dict[str, Any]) -> dict[str, Any]:
|
||||
phrase = _phrase_of(request)
|
||||
stream = self.registry.remove(phrase)
|
||||
if stream is None:
|
||||
# Not an error. `disable` on a session whose daemon restarted since
|
||||
# `enable` is the ordinary case, and the broker has to clear its
|
||||
# record either way.
|
||||
return {"ok": True, "detached": False}
|
||||
log.info(
|
||||
"detached output %s for %s",
|
||||
stream.spec.output,
|
||||
stream.spec.session or "a standalone stream",
|
||||
)
|
||||
return {"ok": True, "detached": True}
|
||||
|
||||
def _list(self, request: dict[str, Any]) -> dict[str, Any]:
|
||||
return {"ok": True, "streams": [self._describe(s) for s in self.registry.all()]}
|
||||
|
||||
def _viewers(self, request: dict[str, Any]) -> dict[str, Any]:
|
||||
return {
|
||||
"ok": True,
|
||||
# `Stream.viewers` is a property, not a method.
|
||||
"viewers": {s.spec.phrase: s.viewers for s in self.registry.all()},
|
||||
}
|
||||
|
||||
def _describe(self, stream: Any) -> dict[str, Any]:
|
||||
public = dict(stream.spec.public())
|
||||
public["url"] = self.url_for(stream.spec.phrase)
|
||||
public["viewers"] = stream.viewers
|
||||
return public
|
||||
|
||||
|
||||
class Rejected(Exception):
|
||||
"""A refusal with a ``kind`` the broker maps to an exit code."""
|
||||
|
||||
def __init__(self, message: str, kind: str | None = None) -> None:
|
||||
super().__init__(message)
|
||||
self.kind = kind
|
||||
|
||||
|
||||
def _no(error: str, kind: str | None = None) -> dict[str, Any]:
|
||||
reply: dict[str, Any] = {"ok": False, "error": error}
|
||||
if kind:
|
||||
reply["kind"] = kind
|
||||
return reply
|
||||
|
||||
|
||||
def _text(request: dict[str, Any], field: str) -> str:
|
||||
value = request.get(field)
|
||||
if not isinstance(value, str) or not value.strip():
|
||||
raise Rejected(f"{field} must be a non-empty string", INVALID)
|
||||
return value.strip()
|
||||
|
||||
|
||||
def _phrase_of(request: dict[str, Any]) -> str:
|
||||
"""The request's phrase, held to the generated shape.
|
||||
|
||||
``phrase.validate`` and not a looser check, for the reason it exists: the
|
||||
phrase is this stream's only credential, so anything that reaches the
|
||||
registry has to be a password rather than ``a-b-c``. The refusal never
|
||||
echoes the phrase back.
|
||||
"""
|
||||
|
||||
value = request.get("phrase")
|
||||
if not isinstance(value, str):
|
||||
raise Rejected("phrase must be a string", INVALID)
|
||||
try:
|
||||
return phrase_mod.validate(value)
|
||||
except ValueError:
|
||||
# Not `{exc}`: the validator names the value it refused, and this
|
||||
# message travels back over the socket into the broker's log. The
|
||||
# shape, never the phrase.
|
||||
raise Rejected(
|
||||
"the phrase given is not of the expected shape: four words of at "
|
||||
"least three letters plus a five-character tail",
|
||||
INVALID,
|
||||
) from None
|
||||
|
||||
|
||||
def _fps(request: dict[str, Any], default: int) -> int:
|
||||
value = request.get("fps")
|
||||
if value is None:
|
||||
return default
|
||||
if isinstance(value, bool) or not isinstance(value, int):
|
||||
raise Rejected(f"fps must be an int, got {type(value).__name__}", INVALID)
|
||||
if value <= 0 or value > FPS_CAP:
|
||||
raise Rejected(f"fps must be between 1 and {FPS_CAP}, got {value}", INVALID)
|
||||
return value
|
||||
|
||||
|
||||
class ControlServer:
|
||||
"""The accept loop for ``live.sock``. One connection at a time.
|
||||
|
||||
The same shape as ``hhstream_pointer.server.PointerServer``: the broker is
|
||||
the only peer, the ops are one small line each, and an async server would
|
||||
buy nothing but a way to interleave two attaches.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
socket_path: Path | str,
|
||||
control: Control,
|
||||
*,
|
||||
socket_mode: int = 0o660,
|
||||
) -> None:
|
||||
self.socket_path = Path(socket_path)
|
||||
self.control = control
|
||||
self.socket_mode = socket_mode
|
||||
self._sock: socket.socket | None = None
|
||||
self.ready = threading.Event()
|
||||
|
||||
def listen(self) -> None:
|
||||
"""Bind and listen. A stale socket file is replaced, not refused:
|
||||
a crashed daemon leaves one behind and the unit must still start."""
|
||||
|
||||
self.socket_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
if self.socket_path.is_socket():
|
||||
self.socket_path.unlink()
|
||||
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
||||
sock.bind(str(self.socket_path))
|
||||
os.chmod(self.socket_path, self.socket_mode)
|
||||
sock.listen(LISTEN_BACKLOG)
|
||||
self._sock = sock
|
||||
self.ready.set()
|
||||
log.info("control socket listening on %s", self.socket_path)
|
||||
|
||||
def serve_forever(self) -> None:
|
||||
assert self._sock is not None, "listen() first"
|
||||
while True:
|
||||
# Read into a local first. `close()` runs on another thread and
|
||||
# sets `_sock` to None, so reading the attribute twice can find a
|
||||
# socket and then find nothing -- measured, as an AttributeError
|
||||
# out of a daemon thread at shutdown rather than the clean return
|
||||
# this loop is supposed to make.
|
||||
sock = self._sock
|
||||
if sock is None:
|
||||
return
|
||||
try:
|
||||
conn, _ = sock.accept()
|
||||
except OSError:
|
||||
# The other way `close()` shows up: the listener was closed
|
||||
# while this thread was blocked in `accept`.
|
||||
return
|
||||
with conn:
|
||||
self._serve_connection(conn)
|
||||
|
||||
def close(self) -> None:
|
||||
sock, self._sock = self._sock, None
|
||||
if sock is not None:
|
||||
sock.close()
|
||||
self.socket_path.unlink(missing_ok=True)
|
||||
self.ready.clear()
|
||||
|
||||
def _serve_connection(self, conn: socket.socket) -> None:
|
||||
with conn.makefile("rwb") as stream:
|
||||
while True:
|
||||
line = stream.readline(MAX_LINE_BYTES + 1)
|
||||
if not line:
|
||||
return
|
||||
if len(line) > MAX_LINE_BYTES:
|
||||
_write(stream, _no("request line too long", INVALID))
|
||||
return
|
||||
try:
|
||||
request = json.loads(line)
|
||||
except json.JSONDecodeError as exc:
|
||||
_write(stream, _no(f"malformed JSON: {exc}", INVALID))
|
||||
continue
|
||||
_write(stream, self.control.handle(request))
|
||||
|
||||
|
||||
def _write(stream, response: dict[str, Any]) -> None:
|
||||
stream.write(json.dumps(response, separators=(",", ":")).encode() + b"\n")
|
||||
stream.flush()
|
||||
+38
-17
@@ -1,7 +1,7 @@
|
||||
"""The phrase: a stream's only credential, shaped to be said out loud.
|
||||
|
||||
A phrase is ``word-word-word-word-xxxxx``: four words off the EFF large
|
||||
wordlist and a five-character base-36 tail. That is ``4*log2(7776) +
|
||||
wordlist and a five-character base-36 tail. That is ``4*log2(7772) +
|
||||
5*log2(36)`` ~= **77.5 bits** of entropy, against a word set small enough to be
|
||||
a file in the repository and a tail short enough to type on a phone.
|
||||
|
||||
@@ -11,8 +11,13 @@ base64 string is not. The job is identical (it *is* the password to the
|
||||
stream); only the shape is chosen for a human.
|
||||
|
||||
The list is vendored (`wordlist.txt`, 7776 lines) so a stream never needs the
|
||||
network to start. `generate` uses `SystemRandom`/`secrets`, so the phrase is
|
||||
not reproducible from the process seed.
|
||||
network to start. Four of those lines are hyphenated (`drop-down`, `felt-tip`,
|
||||
`t-shirt`, `yo-yo`) and are dropped on load: a hyphen is the phrase's own
|
||||
separator, so a phrase built from one would be six tokens and a listener could
|
||||
not hear where the tail starts. 7772 words costs 0.003 bits.
|
||||
|
||||
`generate` uses `SystemRandom`/`secrets`, so the phrase is not reproducible
|
||||
from the process seed.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -24,18 +29,29 @@ import secrets
|
||||
from pathlib import Path
|
||||
|
||||
#: Four words plus the tail. The plan's answer to "how many"; four is
|
||||
#: `4 * log2(7776)` ~= 51.7 bits on its own, and the tail pushes it past 77.
|
||||
#: `4 * log2(7772)` ~= 51.7 bits on its own, and the tail pushes it past 77.
|
||||
WORD_COUNT = 4
|
||||
SUFFIX_LEN = 5
|
||||
#: Lowercase letters and digits: what a person can retype without a shift key,
|
||||
#: and 36 symbols is still `5 * log2(36)` ~= 25.8 bits.
|
||||
SUFFIX_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789"
|
||||
|
||||
#: A phrase is one or more hyphen-joined tokens of lowercase letters/digits,
|
||||
#: at least three of them (so a caller-supplied phrase cannot be a single word
|
||||
#: or a passcode-free stub). Generated phrases are five tokens; this is the
|
||||
#: looser shape a `--phrase` must satisfy.
|
||||
_SHAPE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+){2,}$")
|
||||
#: The smallest token a word may be. The wordlist's own floor is 3, so this
|
||||
#: rejects nothing `generate` can produce and everything an operator might type
|
||||
#: as a stand-in ("a-b-c-d-12345").
|
||||
MIN_WORD_LEN = 3
|
||||
#: A phrase is exactly what `generate` makes: `WORD_COUNT` alphabetic words of
|
||||
#: at least `MIN_WORD_LEN` characters, then a `SUFFIX_LEN` tail of `[a-z0-9]`.
|
||||
#: An operator-supplied `--phrase` is a password for a LAN-facing stream, so it
|
||||
#: is held to the generated shape rather than to a looser "looks like a phrase"
|
||||
#: pattern -- a looser one accepts `a-b-c`, and nothing stops an operator from
|
||||
#: typing that.
|
||||
_SHAPE = re.compile(
|
||||
rf"^[a-z]{{{MIN_WORD_LEN},}}(?:-[a-z]{{{MIN_WORD_LEN},}}){{{WORD_COUNT - 1}}}"
|
||||
rf"-[a-z0-9]{{{SUFFIX_LEN}}}$"
|
||||
)
|
||||
#: Only the words whose letters are the whole line; see the module docstring.
|
||||
_WORD_SHAPE = re.compile(r"^[a-z]+$")
|
||||
MAX_LENGTH = 96
|
||||
|
||||
_WORDLIST = Path(__file__).with_name("wordlist.txt")
|
||||
@@ -43,7 +59,11 @@ _cache: tuple[str, ...] | None = None
|
||||
|
||||
|
||||
def words() -> tuple[str, ...]:
|
||||
"""The wordlist, read once and remembered.
|
||||
"""The usable wordlist, read once and remembered.
|
||||
|
||||
Only plain `[a-z]+` lines survive: the EFF list contains four hyphenated
|
||||
entries and the hyphen is the phrase's separator, so one of them would make
|
||||
a six-token phrase nobody could read out correctly.
|
||||
|
||||
Raises `RuntimeError` on an empty file rather than returning nothing: a
|
||||
generator that picks from an empty list would raise a confusing `IndexError`
|
||||
@@ -52,9 +72,10 @@ def words() -> tuple[str, ...]:
|
||||
global _cache
|
||||
if _cache is None:
|
||||
text = _WORDLIST.read_text(encoding="utf-8")
|
||||
loaded = tuple(word.strip() for word in text.splitlines() if word.strip())
|
||||
stripped = (line.strip() for line in text.splitlines())
|
||||
loaded = tuple(word for word in stripped if _WORD_SHAPE.match(word))
|
||||
if not loaded:
|
||||
raise RuntimeError(f"wordlist {_WORDLIST} is empty")
|
||||
raise RuntimeError(f"wordlist {_WORDLIST} has no usable words")
|
||||
_cache = loaded
|
||||
return _cache
|
||||
|
||||
@@ -91,12 +112,12 @@ def validate(phrase: str) -> str:
|
||||
raise ValueError(f"phrase is {len(normalized)} characters; the maximum is {MAX_LENGTH}")
|
||||
if not _SHAPE.match(normalized):
|
||||
raise ValueError(
|
||||
"phrase must be lowercase words/digits joined by hyphens, at least "
|
||||
"three tokens (e.g. four-words-and-a-tail), not "
|
||||
f"{phrase!r}"
|
||||
f"phrase must be {WORD_COUNT} lowercase words of at least "
|
||||
f"{MIN_WORD_LEN} letters plus a {SUFFIX_LEN}-character [a-z0-9] "
|
||||
f"tail (e.g. amber-otter-lantern-harbor-7k2qp), not {phrase!r}"
|
||||
)
|
||||
return normalized
|
||||
|
||||
|
||||
__all__ = ["WORD_COUNT", "SUFFIX_LEN", "generate", "normalize", "validate",
|
||||
"entropy_bits", "words", "MAX_LENGTH"]
|
||||
__all__ = ["WORD_COUNT", "SUFFIX_LEN", "MIN_WORD_LEN", "generate", "normalize",
|
||||
"validate", "entropy_bits", "words", "MAX_LENGTH"]
|
||||
@@ -31,9 +31,12 @@ log = logging.getLogger("hhstream.live")
|
||||
#: the box is also running the compositor and the main publisher.
|
||||
DEFAULT_FPS = 5
|
||||
FPS_CAP = 10
|
||||
#: After this many capture failures with no successful frame, a stream gives up
|
||||
#: and closes its viewers. `grim` against a removed output ("unknown output")
|
||||
#: fails every time, and retrying forever would be a busy loop on a dead session.
|
||||
#: After this many *consecutive* capture failures a stream gives up and closes
|
||||
#: its viewers. `grim` against a removed output ("unknown output") fails every
|
||||
#: time, and retrying forever would be a busy loop on a dead session -- which is
|
||||
#: as true after a thousand good frames as it is from a cold start, so the count
|
||||
#: is of failures in a row, not of failures-before-the-first-frame. A successful
|
||||
#: grab resets it; giving up does not reset, because a dead output stays dead.
|
||||
FAILURE_LIMIT = 10
|
||||
|
||||
|
||||
@@ -95,8 +98,11 @@ class Stream:
|
||||
# ---- lifecycle ---------------------------------------------------
|
||||
|
||||
def start(self) -> None:
|
||||
# Named for the output, never the phrase: faulthandler, the default
|
||||
# `threading.excepthook` and any profiler that samples the process all
|
||||
# print thread names, and the phrase is this stream's only credential.
|
||||
self._thread = threading.Thread(
|
||||
target=self._run, name=f"hhstream-live-{self.spec.phrase}", daemon=True
|
||||
target=self._run, name=f"hhstream-live-{self.spec.output}", daemon=True
|
||||
)
|
||||
self._thread.start()
|
||||
|
||||
@@ -129,15 +135,22 @@ class Stream:
|
||||
with self._cond:
|
||||
self._failures += 1
|
||||
self._consecutive_failures += 1
|
||||
give_up = self._consecutive_failures >= FAILURE_LIMIT and self._captured == 0
|
||||
give_up = self._consecutive_failures >= FAILURE_LIMIT
|
||||
if give_up:
|
||||
# Sticky on purpose: a stream that reached the cap is
|
||||
# not re-armed by `add_viewer`, because the case this
|
||||
# guards -- an output that was removed -- does not come
|
||||
# back. Re-enabling the session is how it comes back.
|
||||
self._stopped = True
|
||||
self._cond.notify_all()
|
||||
if give_up:
|
||||
log.warning("stream %s: giving up after %d capture failures: %s",
|
||||
self.spec.phrase, FAILURE_LIMIT, exc)
|
||||
# By output, not by phrase: a log line is the easiest place
|
||||
# for a credential to escape to.
|
||||
log.warning("stream on %s: giving up after %d consecutive "
|
||||
"capture failures: %s",
|
||||
self.spec.output, FAILURE_LIMIT, exc)
|
||||
return
|
||||
log.debug("stream %s: capture failed: %s", self.spec.phrase, exc)
|
||||
log.debug("stream on %s: capture failed: %s", self.spec.output, exc)
|
||||
if self._sleep(0.5):
|
||||
return
|
||||
continue
|
||||
|
||||
+91
-14
@@ -22,6 +22,7 @@ nothing a dependency would make easier.
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import socket
|
||||
import threading
|
||||
import time
|
||||
from collections import deque
|
||||
@@ -43,6 +44,11 @@ DEFAULT_HOST = "127.0.0.1"
|
||||
#: Wrong-phrase lookups allowed per client per window before 429.
|
||||
RATE_LIMIT = 30
|
||||
RATE_WINDOW_S = 60.0
|
||||
#: How long a connection may stay silent before it is dropped. It covers the
|
||||
#: request line and the headers only: a client that connects and says nothing
|
||||
#: would otherwise hold a handler thread in `readline` for ever, and on the
|
||||
#: MJPEG route it would hold a viewer slot -- which keeps `grim` running.
|
||||
HEADER_TIMEOUT_S = 15.0
|
||||
|
||||
|
||||
class RateLimiter:
|
||||
@@ -51,6 +57,10 @@ class RateLimiter:
|
||||
A phrase carries ~77 bits, so guessing is already hopeless; this is here so
|
||||
that a LAN attacker cannot even *try* at line speed, and so the attempt is
|
||||
visible in one place. Only misses are counted.
|
||||
|
||||
The table holds only clients that missed inside the current window: the key
|
||||
is a client address, which on a LAN is the attacker's to choose, so a table
|
||||
that only ever grew would be a slow memory leak driven from the network.
|
||||
"""
|
||||
|
||||
def __init__(self, limit: int = RATE_LIMIT, window: float = RATE_WINDOW_S,
|
||||
@@ -63,16 +73,29 @@ class RateLimiter:
|
||||
|
||||
def allow(self, key: str) -> bool:
|
||||
now = self._clock()
|
||||
cutoff = now - self.window
|
||||
with self._lock:
|
||||
# Prune every key, not just this one. Pruning only `key` would leave
|
||||
# a client that missed once and never came back in the table for the
|
||||
# life of the process; the sweep is over the clients seen in the
|
||||
# last window, which is what the limit already bounds.
|
||||
for seen, hits in list(self._hits.items()):
|
||||
while hits and hits[0] < cutoff:
|
||||
hits.popleft()
|
||||
if not hits:
|
||||
del self._hits[seen]
|
||||
hits = self._hits.setdefault(key, deque())
|
||||
cutoff = now - self.window
|
||||
while hits and hits[0] < cutoff:
|
||||
hits.popleft()
|
||||
if len(hits) >= self.limit:
|
||||
return False
|
||||
hits.append(now)
|
||||
return True
|
||||
|
||||
@property
|
||||
def tracked(self) -> int:
|
||||
"""How many clients the table is holding. For the leak test and status."""
|
||||
with self._lock:
|
||||
return len(self._hits)
|
||||
|
||||
def reset(self) -> None:
|
||||
with self._lock:
|
||||
self._hits.clear()
|
||||
@@ -93,6 +116,9 @@ class _Handler(BaseHTTPRequestHandler):
|
||||
protocol_version = "HTTP/1.1"
|
||||
server_version = "hhstream-live"
|
||||
sys_version = ""
|
||||
#: `StreamRequestHandler.setup` applies this to the socket. Without it a
|
||||
#: client that opens a connection and sends nothing pins a handler thread.
|
||||
timeout = HEADER_TIMEOUT_S
|
||||
|
||||
# ---- plumbing ----------------------------------------------------
|
||||
|
||||
@@ -100,8 +126,31 @@ class _Handler(BaseHTTPRequestHandler):
|
||||
def registry(self) -> StreamRegistry:
|
||||
return self.server.registry # type: ignore[attr-defined]
|
||||
|
||||
def setup(self) -> None:
|
||||
super().setup()
|
||||
# Keepalive is for the other half of the same problem: a viewer whose
|
||||
# network black-holes never closes, so `sendall` blocks and the viewer
|
||||
# count never drops -- which keeps `grim` capturing for nobody. The
|
||||
# kernel's probes end that connection instead.
|
||||
try:
|
||||
self.connection.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
|
||||
except OSError as exc: # a platform without it is not worth failing over
|
||||
log.debug("could not enable TCP keepalive: %s", exc)
|
||||
|
||||
def log_message(self, format: str, *args) -> None: # noqa: A002 - base signature
|
||||
log.debug("%s %s", self.address_string(), format % args)
|
||||
"""Log that something happened, never *what was asked for*.
|
||||
|
||||
The base class formats `self.requestline` into almost every message it
|
||||
emits, and the request line contains the phrase -- the stream's only
|
||||
credential. So the format string and its arguments are dropped here and
|
||||
the method is logged on its own; `log_request` adds the status.
|
||||
"""
|
||||
log.debug("%s %s", self.address_string(), self.command or "-")
|
||||
|
||||
def log_request(self, code="-", size="-") -> None:
|
||||
if isinstance(code, HTTPStatus):
|
||||
code = code.value
|
||||
log.debug("%s %s -> %s", self.address_string(), self.command or "-", code)
|
||||
|
||||
def _send(self, status: HTTPStatus, body: bytes, content_type: str,
|
||||
headers: dict[str, str] | None = None) -> None:
|
||||
@@ -128,7 +177,8 @@ class _Handler(BaseHTTPRequestHandler):
|
||||
except (BrokenPipeError, ConnectionResetError):
|
||||
pass # the viewer went away mid-write; that is not an error
|
||||
except OSError as exc:
|
||||
log.debug("client error on %s: %s", path, exc)
|
||||
# Not the path: it carries the phrase.
|
||||
log.debug("client error from %s: %s", self.address_string(), exc)
|
||||
|
||||
def _route(self, path: str) -> None:
|
||||
if path in ("", "/"):
|
||||
@@ -191,12 +241,19 @@ class _Handler(BaseHTTPRequestHandler):
|
||||
self.send_header("Content-Type", f"multipart/x-mixed-replace; boundary={BOUNDARY}")
|
||||
self.send_header("Cache-Control", "no-store")
|
||||
self.send_header("X-Content-Type-Options", "nosniff")
|
||||
# The connection *is* the stream: it has no `Content-Length` and is not
|
||||
# chunked, so "the response ended" can only mean "the connection ended".
|
||||
# HTTP/1.1 keeps a connection alive by default, and an intermediary that
|
||||
# believed that would be entitled to buffer this response until an EOF
|
||||
# that never comes. Saying so has to happen before `end_headers`, or it
|
||||
# is not a header at all -- `send_header` also sets `close_connection`.
|
||||
self.send_header("Connection", "close")
|
||||
self.end_headers()
|
||||
|
||||
# The header timeout has done its job; from here the handler waits on
|
||||
# frames, not on the client, and a quiet minute is normal.
|
||||
self.connection.settimeout(None)
|
||||
stream.add_viewer()
|
||||
# The connection is the stream: after this handler returns there is no
|
||||
# next request to read, so it must not be kept alive.
|
||||
self.close_connection = True
|
||||
last_seq = 0
|
||||
try:
|
||||
while True:
|
||||
@@ -225,6 +282,9 @@ class _Handler(BaseHTTPRequestHandler):
|
||||
class LiveServer:
|
||||
"""Owns the listener and its lifetime. One instance, many streams."""
|
||||
|
||||
#: Binds that mean "every interface" rather than one address of its own.
|
||||
WILDCARDS = ("", "0.0.0.0", "::")
|
||||
|
||||
def __init__(self, registry: StreamRegistry, *, host: str = DEFAULT_HOST,
|
||||
port: int = DEFAULT_PORT, limiter: RateLimiter | None = None) -> None:
|
||||
self.registry = registry
|
||||
@@ -242,12 +302,28 @@ class LiveServer:
|
||||
return self.requested_port
|
||||
return self._httpd.server_address[1]
|
||||
|
||||
@property
|
||||
def binds_everywhere(self) -> bool:
|
||||
return self.host in self.WILDCARDS
|
||||
|
||||
@property
|
||||
def address(self) -> str:
|
||||
advertised = self.host
|
||||
if advertised in ("0.0.0.0", "::"):
|
||||
advertised = "127.0.0.1"
|
||||
return advertised
|
||||
"""A host a browser can dial. A wildcard bind has none of its own, so
|
||||
the loopback name stands in; `describe_bind` is what tells the truth
|
||||
about the reach."""
|
||||
return "127.0.0.1" if self.binds_everywhere else self.host
|
||||
|
||||
def describe_bind(self) -> str:
|
||||
"""One line naming the real bind, and saying when it is every interface.
|
||||
|
||||
`url_for` has to print something dialable, which for `0.0.0.0` is a lie
|
||||
of omission -- the stream is on the LAN, not on loopback. This is where
|
||||
that is said out loud.
|
||||
"""
|
||||
where = f"{self.host or '0.0.0.0'}:{self.port}"
|
||||
if self.binds_everywhere:
|
||||
return f"bound to {where} -- all interfaces, reachable from the LAN"
|
||||
return f"bound to {where}"
|
||||
|
||||
def url_for(self, phrase: str) -> str:
|
||||
return f"http://{self.address}:{self.port}/{phrase}/"
|
||||
@@ -264,7 +340,7 @@ class LiveServer:
|
||||
name="hhstream-live-http", daemon=True)
|
||||
self._thread.start()
|
||||
self.ready.set()
|
||||
log.info("listening on http://%s:%d", self.host, self.port)
|
||||
log.info("listening, %s", self.describe_bind())
|
||||
|
||||
def stop(self) -> None:
|
||||
if self._httpd is not None:
|
||||
@@ -277,4 +353,5 @@ class LiveServer:
|
||||
self.registry.stop_all()
|
||||
|
||||
|
||||
__all__ = ["LiveServer", "RateLimiter", "DEFAULT_PORT", "DEFAULT_HOST", "BOUNDARY"]
|
||||
__all__ = ["LiveServer", "RateLimiter", "DEFAULT_PORT", "DEFAULT_HOST", "BOUNDARY",
|
||||
"HEADER_TIMEOUT_S"]
|
||||
@@ -0,0 +1,43 @@
|
||||
"""``hhstream-mcp`` -- the ``hhstream`` CLI, as Model Context Protocol tools.
|
||||
|
||||
A **shim**, and deliberately the thinnest one that can be honest: every tool
|
||||
builds the argv list the CLI's own parser takes, hands it to the CLI's own
|
||||
handler *in this process*, and maps what came back. No behavioural rule lives
|
||||
here. The idle clock, the pointer lease, the container policy, the allowlist,
|
||||
the exit-code table and the refusal messages are all the CLI's and the broker's,
|
||||
and this package's one job is to not get between an agent and them.
|
||||
|
||||
In process, and not as a subprocess: ``hhstream.cli`` is importable Python, its
|
||||
``main`` already takes an argv list and returns an exit code from the frozen
|
||||
table, and spawning a Python interpreter per tool call to re-parse arguments
|
||||
this process just built would be paying for an isolation nobody asked for. The
|
||||
seam that matters is the *argv list* -- the thing this layer actually decides --
|
||||
and that is identical either way. :mod:`hhstream_mcp.invoke` says which two of
|
||||
the CLI's paths cannot be called in process, and what is done about them.
|
||||
|
||||
Why a separate distribution from ``hhstream`` rather than one more entry point
|
||||
in ``pyproject.toml``: the frame socket, the CLI and the broker are stdlib-only
|
||||
by policy (``pyproject.toml``, ``docs/CONTRACT-sessions.md`` §6 rule 3), and the
|
||||
MCP SDK is a third-party dependency. Growing ``packages.hhstream`` an ``mcp``
|
||||
dependency to serve a shim would put that dependency on the compositor's own
|
||||
units. So the code lives beside the others under ``src/`` -- the dev shell's
|
||||
``PYTHONPATH`` reaches it for free -- and ``nix/mcp.nix`` builds it as its own
|
||||
derivation, with its own pyproject, that *depends on* the ``hhstream`` package.
|
||||
|
||||
The interface is frozen in ``docs/CONTRACT-mcp.md``: the tool names, their
|
||||
arguments, and which exit code arrives as which MCP error. The modules split
|
||||
along the one line that matters for testing -- :mod:`hhstream_mcp.invoke`,
|
||||
:mod:`hhstream_mcp.media` and :mod:`hhstream_mcp.tools` are standard library
|
||||
only, so the argv each tool builds, the parsing of what the CLI printed and the
|
||||
error mapping are all testable without the SDK and without a live socket. Only
|
||||
:mod:`hhstream_mcp.server` imports ``mcp``.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
__version__ = "0.1.0"
|
||||
|
||||
#: What the server calls itself in the ``initialize`` handshake. The same name
|
||||
#: an MCP client configuration block is expected to use for it, so a log line
|
||||
#: and a config entry can be matched up by eye.
|
||||
SERVER_NAME = "hhstream"
|
||||
@@ -0,0 +1,8 @@
|
||||
"""``python -m hhstream_mcp`` — the same entry point as the ``hhstream-mcp`` script."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from .server import main
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -0,0 +1,499 @@
|
||||
"""Run the CLI's own functions, in this process. Standard library only.
|
||||
|
||||
No subprocess. A tool builds the same argv list the CLI's parser takes, this
|
||||
module hands it to ``hhstream.cli``'s parser, runs the handler argparse
|
||||
selected, and reports what that handler printed and returned. The behavioural
|
||||
rules stay exactly where they were -- the idle clock, the lease, the exit-code
|
||||
table, the allowlist and every refusal message are the CLI's and the broker's --
|
||||
and what is saved is a process spawn per tool call and a ``PATH`` to get wrong.
|
||||
|
||||
**Why not ``hhstream.cli.main``.** Two of its paths end in an ``exec``, and in
|
||||
a CLI that is correct while here it would replace the MCP server mid-session and
|
||||
the client would see its connection die:
|
||||
|
||||
1. ``main`` calls ``ensure_access`` before the four frame verbs, which re-execs
|
||||
the whole process through the setuid ``sg`` wrapper when the frame socket is
|
||||
out of reach.
|
||||
2. ``cmd_run`` ends in ``os.execvpe`` -- that *is* the verb. ``run`` therefore
|
||||
spawns instead; see :meth:`Runner.launch`.
|
||||
|
||||
So the parser is the CLI's (``cli.build_parser``), the handler is the one
|
||||
argparse selected, and the exit code is that handler's own return value. What
|
||||
this module adds is the dispatch line between them, the capture, and the remedy
|
||||
sentence per exit code.
|
||||
|
||||
**The one capability lost with the ``sg`` re-exec**, stated plainly because it
|
||||
is a real difference from running the CLI: a process that cannot read the frame
|
||||
socket does not recover here. ``shot`` and ``record`` fail with the CLI's own
|
||||
message plus a hint, where the CLI would have rejoined the group and succeeded.
|
||||
The remedy is to give the server the group in the first place -- see the README
|
||||
section on registering it.
|
||||
|
||||
**Serialised.** The CLI prints to process-global ``sys.stdout``, so two
|
||||
concurrent calls would interleave their output into each other's reply. One
|
||||
lock around the whole call is the honest fix, and costs nothing a caller would
|
||||
notice: the broker already serialises every mutation, and the CLI was one
|
||||
process per verb anyway.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import contextlib
|
||||
import dataclasses
|
||||
import io
|
||||
import json
|
||||
import os
|
||||
import shutil
|
||||
import sys
|
||||
import tempfile
|
||||
import threading
|
||||
import time
|
||||
import traceback
|
||||
from typing import Any, Callable, Iterator
|
||||
|
||||
from hhstream import cli
|
||||
from hhstreamd.protocol import ExitCode
|
||||
|
||||
#: Exit 1 is not in the frozen table: it is what the *frame* verbs return when
|
||||
#: the publisher sent no frame or a tool they need is missing, and what this
|
||||
#: module reports for an exception no handler caught.
|
||||
GENERIC_FAILURE = 1
|
||||
|
||||
#: The three frame verbs' handlers, by the name the CLI's parser gives them.
|
||||
#: `run` is deliberately absent -- it is the one that execs -- and the session
|
||||
#: namespace needs no entry, because argparse sets `func` for it.
|
||||
FRAME_VERBS: dict[str, Callable[[Any], int]] = {
|
||||
"status": cli.cmd_status,
|
||||
"shot": cli.cmd_shot,
|
||||
"record": cli.cmd_record,
|
||||
}
|
||||
|
||||
#: One CLI call at a time. See the module docstring.
|
||||
_ONE_AT_A_TIME = threading.Lock()
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Outcome:
|
||||
"""One completed CLI call, exactly as it ended."""
|
||||
|
||||
argv: list[str]
|
||||
returncode: int
|
||||
stdout: str
|
||||
stderr: str
|
||||
|
||||
@property
|
||||
def ok(self) -> bool:
|
||||
return self.returncode == 0
|
||||
|
||||
def payload(self) -> dict[str, Any] | None:
|
||||
"""The protocol object a ``--json`` verb printed, wherever it printed it.
|
||||
|
||||
stdout on success and **stderr on failure** -- that is the CLI's own
|
||||
split (``hhstream_session._finish``), not a guess: an error always goes
|
||||
to stderr whatever the output mode, because that is what an agent
|
||||
branches on. Both streams are searched in both cases anyway, because a
|
||||
verb that grows a warning on the happy path should not take the parsing
|
||||
with it.
|
||||
"""
|
||||
|
||||
for text in (self.stdout, self.stderr):
|
||||
found = first_json_object(text)
|
||||
if found is not None:
|
||||
return found
|
||||
return None
|
||||
|
||||
|
||||
def first_json_object(text: str) -> dict[str, Any] | None:
|
||||
"""The first JSON *object* in ``text``, or ``None``.
|
||||
|
||||
A scan rather than ``json.loads`` on the whole stream: ``session start``
|
||||
prints the bare id above its object, and a verb that one day prints a line
|
||||
above one should not stop being parseable.
|
||||
"""
|
||||
|
||||
decoder = json.JSONDecoder()
|
||||
index = text.find("{")
|
||||
while index != -1:
|
||||
try:
|
||||
value, _ = decoder.raw_decode(text, index)
|
||||
except ValueError:
|
||||
index = text.find("{", index + 1)
|
||||
continue
|
||||
if isinstance(value, dict):
|
||||
return value
|
||||
index = text.find("{", index + 1)
|
||||
return None
|
||||
|
||||
|
||||
# ── what each exit code means to an agent ──────────────────────────────────
|
||||
|
||||
#: The sentence a calling agent needs after a refusal: not what went wrong --
|
||||
#: the CLI's own ``reason`` says that better than any table could -- but what to
|
||||
#: do about it. Keyed by the frozen exit codes of
|
||||
#: ``docs/CONTRACT-sessions.md`` §4, so a new code is a missing key here and
|
||||
#: not a silently generic message.
|
||||
REMEDY: dict[int, str] = {
|
||||
ExitCode.USAGE: (
|
||||
"The call was rejected before anything happened: an argument is "
|
||||
"missing, malformed, or names something this build does not support. "
|
||||
"Fix the arguments; retrying the same call will fail the same way."
|
||||
),
|
||||
ExitCode.NO_SUCH_SESSION: (
|
||||
"No session (or process) by that id. Read `hhstream://sessions` to see "
|
||||
"which ids exist; a reaped session is gone and has to be started again."
|
||||
),
|
||||
ExitCode.BAD_STATE: (
|
||||
"The session exists but is not in a state this verb can act on -- it "
|
||||
"is still starting, or it has already exited, been killed or been "
|
||||
"reaped. Read `hhstream://sessions/<id>` to see which."
|
||||
),
|
||||
ExitCode.DAEMON_UNREACHABLE: (
|
||||
"The session broker (`hhstreamd`) could not be reached on its control "
|
||||
"socket. Nothing was done. This is an operator problem, not an "
|
||||
"argument problem: the daemon is down, or $HHSTREAM_SOCKET points "
|
||||
"somewhere else. The frame tools (`shot`, `record`, `run`) and "
|
||||
"`hhstream://status` do not need the broker and may still work."
|
||||
),
|
||||
ExitCode.POLICY: (
|
||||
"Refused by policy. The application is not on the broker's allowlist, "
|
||||
"or an argument is not one the allowlist permits, or a budget (session "
|
||||
"cap, workspace band) is full. No retry will change it; this is a "
|
||||
"configuration decision."
|
||||
),
|
||||
ExitCode.TIMEOUT: (
|
||||
"The broker accepted the request and did not finish in time. Whether "
|
||||
"it took effect is unknown -- read the state back "
|
||||
"(`hhstream://sessions`, `hhstream://sessions/<id>`, "
|
||||
"`hhstream://pointer`) before retrying, and retry with the same "
|
||||
"`request_id` so a mutation cannot happen twice."
|
||||
),
|
||||
ExitCode.BUSY: (
|
||||
"Something else holds what this call needs -- for the pointer and "
|
||||
"keyboard verbs, another session holds the one pointer lease, and the "
|
||||
"refusal names the holder. Nothing was injected. Read "
|
||||
"`hhstream://pointer` to see who holds it, then wait for them to "
|
||||
"release it or for its TTL to expire. Do NOT try to take it from "
|
||||
"them; there is no such verb."
|
||||
),
|
||||
ExitCode.NO_LEASE: (
|
||||
"This verb needs the pointer lease and this session does not hold one "
|
||||
"(never acquired, already released, or expired -- an idle lease is "
|
||||
"force-released by the broker). Call `pointer_acquire` for this "
|
||||
"session and pass the `lease_id` it returns as `lease` on every "
|
||||
"pointer and keyboard call. A lease id that was refused is dead; "
|
||||
"acquire a new one rather than retrying with it."
|
||||
),
|
||||
ExitCode.COMPOSITOR: (
|
||||
"The compositor or the input driver failed. **The session itself is "
|
||||
"not lost** -- it keeps running in degraded mode -- so do not treat "
|
||||
"this as a dead session. The compositor may be down, the container may "
|
||||
"be gone, or the driver refused the request (an unmappable character, "
|
||||
"a keysym this layout does not have)."
|
||||
),
|
||||
GENERIC_FAILURE: (
|
||||
"The command failed without one of the broker's classified codes. For "
|
||||
"the frame tools this is usually the publisher sending no frame (is the "
|
||||
"compositor up? read `hhstream://status`) or `grim`/`ffmpeg` missing "
|
||||
"from the "
|
||||
"server's PATH. The text below is the CLI's own."
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
def remedy_for(returncode: int) -> str:
|
||||
try:
|
||||
name = ExitCode(returncode).name
|
||||
except ValueError:
|
||||
name = "UNCLASSIFIED"
|
||||
advice = REMEDY.get(
|
||||
returncode,
|
||||
"The CLI exited with a code this server does not know. Treat it as a "
|
||||
"failure and read the output below; do not assume anything happened.",
|
||||
)
|
||||
return f"exit {returncode} ({name}): {advice}"
|
||||
|
||||
|
||||
# ── capture ────────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def captured() -> Iterator[tuple[io.StringIO, io.StringIO]]:
|
||||
"""Redirect the CLI's ``print``s into a pair of buffers.
|
||||
|
||||
Python-level only, and that is enough **because the protocol is not on file
|
||||
descriptor 1 any more**: :func:`hhstream_mcp.server.claim_transport` takes a
|
||||
private duplicate of stdout at start-up and points fd 1 at the log. So a
|
||||
stray write from a grandchild (``ffmpeg``, which the CLI does not capture)
|
||||
lands in the server's log rather than in the client's stream, and this
|
||||
context manager only has to collect what the handler itself printed.
|
||||
"""
|
||||
|
||||
out, err = io.StringIO(), io.StringIO()
|
||||
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
|
||||
yield out, err
|
||||
|
||||
|
||||
def dispatch(argv: list[str]) -> int:
|
||||
"""Parse ``argv`` with the CLI's own parser and run the handler it selects.
|
||||
|
||||
The CLI's ``main`` minus its two ``exec`` paths; see the module docstring.
|
||||
"""
|
||||
|
||||
parser = cli.build_parser()
|
||||
args = parser.parse_args(argv)
|
||||
if args.command is None:
|
||||
parser.print_help(sys.stderr)
|
||||
return int(ExitCode.USAGE)
|
||||
handler = FRAME_VERBS.get(args.command)
|
||||
if handler is not None:
|
||||
return int(handler(args))
|
||||
# The session namespace: argparse already chose the handler when it parsed.
|
||||
return int(getattr(args, "func")(args))
|
||||
|
||||
|
||||
def access_hint(argv: list[str]) -> str:
|
||||
"""The sentence the ``sg`` re-exec would otherwise have made unnecessary.
|
||||
|
||||
Added to a failure only when the diagnosis is actually true, and only for
|
||||
the verbs it could be true of. The predicate is the CLI's own, asked about
|
||||
the CLI's own resolved socket path; the verb list is the one ``cli.main``
|
||||
guards, because the frame socket has nothing to do with why a session verb
|
||||
failed and an explanation that does not apply is worse than none.
|
||||
"""
|
||||
|
||||
try:
|
||||
# Inside the capture, because an argv argparse refuses makes it print
|
||||
# usage -- and this runs *after* the call, so that print would reach
|
||||
# the log rather than the reply, saying the same thing twice in the
|
||||
# wrong place.
|
||||
with captured():
|
||||
args = cli.build_parser().parse_args(argv)
|
||||
if args.command not in FRAME_VERBS and args.command != "run":
|
||||
return ""
|
||||
socket_path = getattr(args, "frame_socket", None)
|
||||
if socket_path and not cli.have_access(socket_path):
|
||||
return (
|
||||
f"\n\nThis process cannot read {socket_path}. The hhstream CLI "
|
||||
"would have re-joined the compositor's group through the "
|
||||
"setuid 'sg' wrapper at this point; this server cannot, "
|
||||
"because that is an exec which would replace it and drop the "
|
||||
"client's connection. Run it as a member of that group "
|
||||
"instead -- `sg hhstream -c hhstream-mcp` in the client's "
|
||||
"spawn command, or add the account to the group."
|
||||
)
|
||||
except SystemExit:
|
||||
# A parse that fails here fails identically in the call itself, and
|
||||
# that failure is the one worth reporting.
|
||||
return ""
|
||||
return ""
|
||||
|
||||
|
||||
# ── the runner ─────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Spawned:
|
||||
"""A process that was started and deliberately not waited for."""
|
||||
|
||||
argv: list[str]
|
||||
pid: int
|
||||
exited: bool
|
||||
stdout: str
|
||||
stderr: str
|
||||
|
||||
|
||||
class Runner:
|
||||
"""Calls the CLI. Holds the entry point and nothing else.
|
||||
|
||||
No lease, no session id, no last reply. The server is a shim
|
||||
(``docs/CONTRACT-mcp.md`` §3), and the moment it remembers a lease an agent
|
||||
can no longer see which lease its call used.
|
||||
|
||||
``entry`` exists so the tests can put a recorder where the CLI goes: what
|
||||
this layer decides is the argv list, and a test that cannot see the argv
|
||||
list is testing nothing. There is no second production value for it.
|
||||
"""
|
||||
|
||||
def __init__(self, entry: Callable[[list[str]], int] | None = None) -> None:
|
||||
self.entry = entry or dispatch
|
||||
|
||||
def run(self, argv: list[str]) -> Outcome:
|
||||
"""One call, start to finish. Never raises for a CLI failure."""
|
||||
|
||||
with _ONE_AT_A_TIME:
|
||||
with captured() as (out, err):
|
||||
try:
|
||||
code = int(self.entry(list(argv)))
|
||||
except SystemExit as exc:
|
||||
# argparse's own refusals, and the handlers' `sys.exit` for
|
||||
# an unreachable compositor or a grim that is not there.
|
||||
code = _exit_status(exc)
|
||||
except BaseException: # noqa: BLE001 -- a CLI process would
|
||||
# have died here with a traceback on stderr and status 1;
|
||||
# reproducing that is more honest than letting it reach the
|
||||
# protocol as a transport error.
|
||||
traceback.print_exc(file=sys.stderr)
|
||||
code = GENERIC_FAILURE
|
||||
stdout, stderr = out.getvalue(), err.getvalue()
|
||||
if code != 0:
|
||||
stderr += access_hint(list(argv))
|
||||
return Outcome(argv=list(argv), returncode=code, stdout=stdout, stderr=stderr)
|
||||
|
||||
def launch(self, command: list[str], *, settle: float) -> Spawned:
|
||||
"""``run``: put an application on the screen and do not wait for it.
|
||||
|
||||
``cli.cmd_run`` is two lines -- the environment a Wayland client needs,
|
||||
then ``os.execvpe`` -- and the second of them is why it cannot be
|
||||
called here: it would turn this server into the application. So the
|
||||
environment comes from the CLI's own
|
||||
:func:`hhstream.cli.env_for_session` and the exec is done by
|
||||
``posix_spawn``:
|
||||
|
||||
* ``posix_spawn`` and not ``fork`` because this runs on a worker thread.
|
||||
A ``fork`` from a threaded process can inherit a lock another thread
|
||||
was holding, and Python warns about exactly that; ``posix_spawn``
|
||||
leaves no Python running between the clone and the exec.
|
||||
* ``setsid`` puts the application in its own session, so a client that
|
||||
kills this server's process group does not take the desktop with it.
|
||||
That, plus not waiting, is what "launch and forget" means.
|
||||
* The executable is resolved *here*, so "no such command" is a refusal
|
||||
an agent can read rather than a child exiting 127 into a log.
|
||||
* A reaper thread waits on the pid, so a long-lived application that
|
||||
eventually exits does not sit in this process's table as a zombie.
|
||||
"""
|
||||
|
||||
# The frame socket the CLI would have resolved -- its flag default, or
|
||||
# $HHSTREAM_FRAME_SOCKET -- read out of its own parser rather than
|
||||
# re-derived, because `run` takes the compositor's runtime directory
|
||||
# from it and a second opinion about that path is a second bug.
|
||||
frame_socket = cli.build_parser().parse_args(["status"]).frame_socket
|
||||
runtime_dir = os.path.dirname(frame_socket)
|
||||
try:
|
||||
environment = dict(os.environ)
|
||||
environment.update(cli.env_for_session(runtime_dir))
|
||||
except SystemExit as exc:
|
||||
# `env_for_session` refuses with `sys.exit(message)` when the
|
||||
# compositor has bound no Wayland socket. The message is the CLI's
|
||||
# own and is handed on verbatim.
|
||||
return Spawned(
|
||||
argv=command, pid=0, exited=True, stdout="", stderr=str(exc.code)
|
||||
)
|
||||
resolved = shutil.which(command[0], path=environment.get("PATH"))
|
||||
if resolved is None:
|
||||
return Spawned(
|
||||
argv=command,
|
||||
pid=0,
|
||||
exited=True,
|
||||
stdout="",
|
||||
stderr=f"hhstream-mcp: no executable {command[0]!r} on PATH",
|
||||
)
|
||||
return _spawn_detached(resolved, command, environment, settle)
|
||||
|
||||
|
||||
def _exit_status(exc: SystemExit) -> int:
|
||||
"""``SystemExit`` as a status. A message is status 1, as in a real process."""
|
||||
|
||||
if exc.code is None:
|
||||
return 0
|
||||
if isinstance(exc.code, int):
|
||||
return exc.code
|
||||
return GENERIC_FAILURE
|
||||
|
||||
|
||||
def _spawn_detached(
|
||||
resolved: str, command: list[str], environment: dict[str, str], settle: float
|
||||
) -> Spawned:
|
||||
"""Start the application in its own session and report its pid."""
|
||||
|
||||
with tempfile.TemporaryDirectory(prefix="hhstream-mcp-run-") as scratch:
|
||||
capture = os.path.join(scratch, "output")
|
||||
# Its stdin must not be the protocol stream, and its first complaint is
|
||||
# worth handing back to the agent rather than mixing into the server's
|
||||
# log -- so both of its output descriptors go to one file, which this
|
||||
# directory takes away afterwards. An application that keeps writing
|
||||
# writes to a deleted inode and leaves nothing behind.
|
||||
file_actions = [
|
||||
(os.POSIX_SPAWN_OPEN, 0, os.devnull, os.O_RDONLY, 0o666),
|
||||
(
|
||||
os.POSIX_SPAWN_OPEN,
|
||||
1,
|
||||
capture,
|
||||
os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
|
||||
0o600,
|
||||
),
|
||||
(os.POSIX_SPAWN_DUP2, 1, 2),
|
||||
]
|
||||
pid = os.posix_spawn(
|
||||
resolved, command, environment, file_actions=file_actions, setsid=True
|
||||
)
|
||||
exited = _watch(pid, settle)
|
||||
if not exited:
|
||||
_reap_later(pid)
|
||||
try:
|
||||
with open(capture, encoding="utf-8", errors="replace") as fh:
|
||||
said = fh.read()
|
||||
except OSError: # pragma: no cover -- the spawn created it
|
||||
said = ""
|
||||
return Spawned(
|
||||
argv=command,
|
||||
pid=pid,
|
||||
exited=exited,
|
||||
stdout="" if exited else said,
|
||||
stderr=said if exited else "",
|
||||
)
|
||||
|
||||
|
||||
#: How often to look at a launched process while the settle window runs.
|
||||
_WATCH_INTERVAL_S = 0.05
|
||||
|
||||
|
||||
def _watch(pid: int, settle: float) -> bool:
|
||||
"""``True`` if the process is gone before ``settle`` seconds are up.
|
||||
|
||||
``waitpid`` with ``WNOHANG``, so an application that fails at once is both
|
||||
detected and reaped here.
|
||||
"""
|
||||
|
||||
deadline = time.monotonic() + max(0.0, settle)
|
||||
while True:
|
||||
try:
|
||||
reaped, _ = os.waitpid(pid, os.WNOHANG)
|
||||
except ChildProcessError: # pragma: no cover -- already reaped
|
||||
return True
|
||||
if reaped == pid:
|
||||
return True
|
||||
if time.monotonic() >= deadline:
|
||||
return False
|
||||
time.sleep(_WATCH_INTERVAL_S)
|
||||
|
||||
|
||||
def _reap_later(pid: int) -> None:
|
||||
"""Wait on a surviving application, on a thread that does nothing else.
|
||||
|
||||
Without this the application sits in this process's table as a zombie from
|
||||
the moment it exits until the server does. A thread blocked in ``waitpid``
|
||||
is the cheapest way to not have that, and a daemon one so it never delays
|
||||
shutdown.
|
||||
"""
|
||||
|
||||
def wait() -> None:
|
||||
try:
|
||||
os.waitpid(pid, 0)
|
||||
except (ChildProcessError, OSError): # pragma: no cover
|
||||
pass
|
||||
|
||||
threading.Thread(target=wait, name=f"hhstream-mcp-reap-{pid}", daemon=True).start()
|
||||
|
||||
|
||||
def temp_name(prefix: str, suffix: str) -> str:
|
||||
"""A unique filename for an artefact, in the system temporary directory.
|
||||
|
||||
Used for ``record``'s default destination, which is the one artefact a tool
|
||||
hands back by *path*: it has to outlive the call, so it cannot live in a
|
||||
directory this process cleans up.
|
||||
"""
|
||||
|
||||
directory = os.path.join(tempfile.gettempdir(), "hhstream-mcp")
|
||||
os.makedirs(directory, exist_ok=True)
|
||||
stamp = time.strftime("%Y%m%d-%H%M%S")
|
||||
return os.path.join(directory, f"{prefix}-{stamp}-{os.getpid()}{suffix}")
|
||||
@@ -0,0 +1,115 @@
|
||||
"""Read back what ``shot`` and ``record`` produced. Standard library only.
|
||||
|
||||
Two small readers, and both are deliberately readers rather than deciders.
|
||||
``shot`` writes a file and prints its path; ``record`` writes an mp4 and prints
|
||||
the path with the rate it measured. The geometry and the rate are facts those
|
||||
artefacts already carry, and an agent that gets a picture without its
|
||||
dimensions has to guess at the coordinate space it is about to aim the pointer
|
||||
in -- so they are parsed out and put in the text part of the reply.
|
||||
|
||||
Nothing here re-derives anything the CLI decided. The frame rate is the CLI's
|
||||
own measured number, read off its output; the dimensions come from the image's
|
||||
header, not from the configured output size, because the configured size is
|
||||
what the compositor was *asked* for.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import dataclasses
|
||||
import re
|
||||
import struct
|
||||
|
||||
PNG_MAGIC = b"\x89PNG\r\n\x1a\n"
|
||||
JPEG_MAGIC = b"\xff\xd8"
|
||||
|
||||
#: The SOFn markers that carry a JPEG's dimensions. Everything except DHT
|
||||
#: (c4), DAC (cc) and the RSTn range (d0-d7), which share the 0xffc_ block.
|
||||
_JPEG_SOF = {0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF}
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Image:
|
||||
media_type: str
|
||||
width: int
|
||||
height: int
|
||||
size: int
|
||||
|
||||
|
||||
def sniff(data: bytes) -> Image | None:
|
||||
"""The media type and pixel size of one captured frame, or ``None``.
|
||||
|
||||
By magic bytes and not by the extension this server asked for. The frame
|
||||
socket publishes whatever format the module configured -- ``image/png`` by
|
||||
default, ``image/jpeg`` on the deployment machine -- and ``hhstream shot``
|
||||
writes the payload it was given to the ``--out`` path verbatim, so a file
|
||||
called ``.png`` holds a JPEG whenever the publisher is serving one. An
|
||||
agent told the wrong media type gets an image its client cannot decode.
|
||||
"""
|
||||
|
||||
if data.startswith(PNG_MAGIC):
|
||||
return _png(data)
|
||||
if data.startswith(JPEG_MAGIC):
|
||||
return _jpeg(data)
|
||||
return None
|
||||
|
||||
|
||||
def _png(data: bytes) -> Image | None:
|
||||
# IHDR is required to be the first chunk: 8 bytes of signature, a 4-byte
|
||||
# length, the type, then width and height.
|
||||
if len(data) < 24 or data[12:16] != b"IHDR":
|
||||
return None
|
||||
width, height = struct.unpack(">II", data[16:24])
|
||||
return Image("image/png", width, height, len(data))
|
||||
|
||||
|
||||
def _jpeg(data: bytes) -> Image | None:
|
||||
index = 2
|
||||
end = len(data)
|
||||
while index + 3 < end:
|
||||
if data[index] != 0xFF:
|
||||
index += 1
|
||||
continue
|
||||
marker = data[index + 1]
|
||||
if marker in (0xD8, 0x01) or 0xD0 <= marker <= 0xD7:
|
||||
index += 2
|
||||
continue
|
||||
if marker == 0xD9 or marker == 0xDA: # end of image, or start of scan
|
||||
return None
|
||||
(length,) = struct.unpack(">H", data[index + 2 : index + 4])
|
||||
if marker in _JPEG_SOF:
|
||||
if index + 9 > end:
|
||||
return None
|
||||
height, width = struct.unpack(">HH", data[index + 5 : index + 9])
|
||||
return Image("image/jpeg", width, height, len(data))
|
||||
index += 2 + length
|
||||
return None
|
||||
|
||||
|
||||
#: What ``hhstream record`` prints on success, which is the only place the
|
||||
#: *measured* rate exists: a software-rendered compositor tops out well under
|
||||
#: the advertised fps, so the encoded rate is the one it counted, and an agent
|
||||
#: reading the mp4 later cannot recover how long the capture actually took.
|
||||
RECORD_LINE = re.compile(
|
||||
r"^(?P<path>.+?) \((?P<frames>\d+) frames in (?P<seconds>[\d.]+)s -> (?P<fps>\d+) fps\)\s*$",
|
||||
re.MULTILINE,
|
||||
)
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Recording:
|
||||
path: str
|
||||
frames: int
|
||||
seconds: float
|
||||
fps: int
|
||||
|
||||
|
||||
def recording(stdout: str) -> Recording | None:
|
||||
match = RECORD_LINE.search(stdout)
|
||||
if match is None:
|
||||
return None
|
||||
return Recording(
|
||||
path=match["path"],
|
||||
frames=int(match["frames"]),
|
||||
seconds=float(match["seconds"]),
|
||||
fps=int(match["fps"]),
|
||||
)
|
||||
@@ -0,0 +1,46 @@
|
||||
# The second distribution in this repository, and the only one with a
|
||||
# third-party runtime dependency.
|
||||
#
|
||||
# It sits *inside* the package directory rather than at the repository root
|
||||
# because the root `pyproject.toml` is `hhstream`'s and a project has one. The
|
||||
# alternatives were worse: a second source tree would duplicate nothing but a
|
||||
# directory level, and adding `hhstream-mcp` to the root project would put the
|
||||
# `mcp` dependency on the compositor's own units -- which is the one thing
|
||||
# `docs/CONTRACT-sessions.md` §6 rule 3 and the root pyproject's own comment
|
||||
# forbid. The root project excludes `hhstream_mcp*` from its package discovery
|
||||
# for the same reason; see the note there.
|
||||
#
|
||||
# `package-dir` maps the package name onto this directory, so the layout stays
|
||||
# `src/hhstream_mcp/` -- which is what puts it on the dev shell's
|
||||
# `PYTHONPATH=$PWD/src` beside every other package here, with no second path to
|
||||
# set and no second place for a test to import from.
|
||||
|
||||
[build-system]
|
||||
requires = ["setuptools>=68"]
|
||||
build-backend = "setuptools.build_meta"
|
||||
|
||||
[project]
|
||||
name = "hhstream-mcp"
|
||||
version = "0.1.0"
|
||||
description = "Drive a headless Hyprland session over the Model Context Protocol"
|
||||
requires-python = ">=3.11"
|
||||
# `mcp` is the official Python SDK and the whole reason this is a separate
|
||||
# distribution. `anyio` is declared rather than taken for granted through the
|
||||
# SDK: `server.py` calls `anyio.run` and `anyio.to_thread` directly, and a
|
||||
# dependency used by name belongs in the metadata.
|
||||
#
|
||||
# `hhstream` is NOT listed, and it is not optional either: this package imports
|
||||
# `hhstream.cli`, `hhstreamd.protocol` and `hhstream_session` and does not work
|
||||
# without them. It is absent because `hhstream` is not a wheel anyone installs
|
||||
# from an index -- it is this repository's other derivation, and `nix/mcp.nix`
|
||||
# is where the two are joined. A dependency naming a version nobody can
|
||||
# resolve would be worse than the comment you are reading.
|
||||
dependencies = ["mcp>=1.9", "anyio>=4"]
|
||||
|
||||
[project.scripts]
|
||||
# Stdio only. One process per client, spawned by the client; no port, no daemon.
|
||||
hhstream-mcp = "hhstream_mcp.server:main"
|
||||
|
||||
[tool.setuptools]
|
||||
packages = ["hhstream_mcp"]
|
||||
package-dir = { "hhstream_mcp" = "." }
|
||||
@@ -0,0 +1,436 @@
|
||||
"""The read-only half of the surface: state as resources. Standard library only.
|
||||
|
||||
Every verb of the CLI that only *reads* is addressed by URI here rather than
|
||||
called as a tool, because that is the split the protocol draws. A resource is
|
||||
**application**-controlled context: the host decides what to put in front of
|
||||
the model, and "what is on this machine right now" is the host's business. A
|
||||
tool is **model**-controlled: an act the model chooses to perform, and every one
|
||||
left in :mod:`hhstream_mcp.tools` either changes something or costs something.
|
||||
|
||||
So the line is not "cheap here, expensive there" -- it is *who decides*.
|
||||
``hhstream://sessions`` is state a host may always include; ``session_kill`` is
|
||||
a decision only the model can make.
|
||||
|
||||
Two things this module is careful about:
|
||||
|
||||
* **A resource read must not write.** That rules out ``session container <id>``,
|
||||
which looks like a read and is not: with an id the CLI runs
|
||||
``container.reconcile`` and brings the record up to the compositor's answer.
|
||||
Only the no-id form (``container.list``) is here, as ``hhstream://containers``;
|
||||
the reconciling form stays the ``session_container`` tool.
|
||||
* **A refusal must not arrive as content.** There is no ``isError`` on a
|
||||
resource read, so a CLI refusal is *raised* and carries the same remedy
|
||||
sentence a tool error would have. Returning the broker's failure object as
|
||||
the body would make "this session does not exist" look like a successful read
|
||||
of a session.
|
||||
|
||||
Arguments become query parameters, because a resource read takes nothing but a
|
||||
URI. Only the declared ones are accepted -- an unknown parameter is refused
|
||||
rather than dropped, for the reason every tool schema sets
|
||||
``additionalProperties: false``: an argument silently ignored is a read that
|
||||
answered a different question than the one asked.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import dataclasses
|
||||
import urllib.parse
|
||||
from typing import Any, Callable
|
||||
|
||||
from . import media, tools
|
||||
from .invoke import Outcome, Runner, remedy_for
|
||||
|
||||
#: The scheme every resource here lives under. One, because they are all views
|
||||
#: of one machine's one desktop.
|
||||
SCHEME = "hhstream"
|
||||
|
||||
JSON = "application/json"
|
||||
TEXT = "text/plain"
|
||||
|
||||
|
||||
class ReadRefused(Exception):
|
||||
"""The CLI refused, or the URI names nothing. Raised, never returned.
|
||||
|
||||
Carries what a tool error would have carried, so a host that surfaces the
|
||||
message gives its model the same remedy a tool call would have given it.
|
||||
"""
|
||||
|
||||
def __init__(self, message: str, detail: dict[str, Any] | None = None) -> None:
|
||||
super().__init__(message)
|
||||
self.message = message
|
||||
self.detail = detail or {}
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Reading:
|
||||
"""What one resource read produced. Text or bytes, never both."""
|
||||
|
||||
media_type: str
|
||||
text: str | None = None
|
||||
blob: bytes | None = None
|
||||
|
||||
|
||||
Read = Callable[[Runner, dict[str, str]], Reading]
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Entry:
|
||||
"""One resource, or one family of them.
|
||||
|
||||
``route`` is the URI after the scheme, as segments: a literal matches
|
||||
itself, ``{name}`` captures exactly one segment. An entry with a capture is
|
||||
a *template*; there is no second class for it, because the only thing that
|
||||
differs is whether ``resources/list`` or ``resources/templates/list``
|
||||
mentions it.
|
||||
"""
|
||||
|
||||
route: tuple[str, ...]
|
||||
name: str
|
||||
title: str
|
||||
description: str
|
||||
media_type: str
|
||||
read: Read
|
||||
#: Query parameters this read accepts, by the name an agent puts in the
|
||||
#: URI. What each becomes on the command line is :data:`_FLAGS`' business,
|
||||
#: so that translation lives in one place rather than once per entry.
|
||||
parameters: tuple[str, ...] = ()
|
||||
|
||||
@property
|
||||
def captures(self) -> tuple[str, ...]:
|
||||
return tuple(s[1:-1] for s in self.route if s.startswith("{"))
|
||||
|
||||
@property
|
||||
def is_template(self) -> bool:
|
||||
return bool(self.captures)
|
||||
|
||||
@property
|
||||
def uri(self) -> str:
|
||||
"""The concrete URI. Only meaningful for an entry with no captures."""
|
||||
|
||||
return f"{SCHEME}://" + "/".join(self.route)
|
||||
|
||||
@property
|
||||
def uri_template(self) -> str:
|
||||
"""RFC 6570, including the query parameters it accepts."""
|
||||
|
||||
base = f"{SCHEME}://" + "/".join(self.route)
|
||||
if not self.parameters:
|
||||
return base
|
||||
return base + "{?" + ",".join(sorted(self.parameters)) + "}"
|
||||
|
||||
def match(self, segments: tuple[str, ...]) -> dict[str, str] | None:
|
||||
"""The captured values, or ``None`` if this entry is not the one."""
|
||||
|
||||
if len(segments) != len(self.route):
|
||||
return None
|
||||
captured: dict[str, str] = {}
|
||||
for pattern, value in zip(self.route, segments):
|
||||
if pattern.startswith("{"):
|
||||
if not value:
|
||||
return None
|
||||
captured[pattern[1:-1]] = value
|
||||
elif pattern != value:
|
||||
return None
|
||||
return captured
|
||||
|
||||
|
||||
# ── parsing a URI ──────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def split(uri: str) -> tuple[tuple[str, ...], dict[str, str]]:
|
||||
"""``hhstream://sessions/s-1/logs?lines=5`` -> ``(("sessions","s-1","logs"), {...})``.
|
||||
|
||||
The authority and the path are one route: ``urlsplit`` puts the first
|
||||
segment in ``netloc`` for a ``scheme://a/b`` URI, which is an artefact of
|
||||
the form rather than a distinction worth preserving.
|
||||
"""
|
||||
|
||||
parsed = urllib.parse.urlsplit(uri)
|
||||
if parsed.scheme != SCHEME:
|
||||
raise ReadRefused(
|
||||
f"not a {SCHEME} resource: {uri!r}. Every resource this server "
|
||||
f"serves is {SCHEME}://… — call resources/list for the set."
|
||||
)
|
||||
joined = parsed.netloc + parsed.path
|
||||
segments = tuple(s for s in joined.split("/") if s)
|
||||
if not segments:
|
||||
raise ReadRefused(f"{uri!r} names no resource; call resources/list")
|
||||
query: dict[str, str] = {}
|
||||
for key, value in urllib.parse.parse_qsl(parsed.query, keep_blank_values=True):
|
||||
if key in query:
|
||||
raise ReadRefused(
|
||||
f"{key!r} is given more than once in {uri!r}; each parameter "
|
||||
"takes one value"
|
||||
)
|
||||
query[key] = value
|
||||
return segments, query
|
||||
|
||||
|
||||
def resolve(uri: str) -> tuple[Entry, dict[str, str]]:
|
||||
"""The entry for ``uri``, with its captures and validated query merged.
|
||||
|
||||
Literal routes are tried before templates, so ``hhstream://sessions`` is the
|
||||
listing and not a session whose id happens to be absent.
|
||||
"""
|
||||
|
||||
segments, query = split(uri)
|
||||
for entry in sorted(ENTRIES, key=lambda e: len(e.captures)):
|
||||
captured = entry.match(segments)
|
||||
if captured is None:
|
||||
continue
|
||||
unknown = set(query) - set(entry.parameters)
|
||||
if unknown:
|
||||
accepted = ", ".join(sorted(entry.parameters)) or "none"
|
||||
raise ReadRefused(
|
||||
f"{entry.name} does not accept "
|
||||
f"{', '.join(repr(u) for u in sorted(unknown))}; it accepts: {accepted}"
|
||||
)
|
||||
return entry, {**captured, **query}
|
||||
raise ReadRefused(
|
||||
f"no resource at {uri!r}. Call resources/list for the fixed ones and "
|
||||
"resources/templates/list for the rest."
|
||||
)
|
||||
|
||||
|
||||
# ── turning a CLI call into a reading ──────────────────────────────────────
|
||||
|
||||
|
||||
def _checked(outcome: Outcome, what: str) -> Outcome:
|
||||
"""The outcome, or a refusal carrying the CLI's own words and the remedy."""
|
||||
|
||||
if outcome.ok:
|
||||
return outcome
|
||||
payload = outcome.payload() or {}
|
||||
said = (outcome.stderr or outcome.stdout).strip()
|
||||
raise ReadRefused(
|
||||
f"could not read {what}: {remedy_for(outcome.returncode)}"
|
||||
+ (f"\n\n{said}" if said else ""),
|
||||
{
|
||||
"ok": False,
|
||||
"exit_code": outcome.returncode,
|
||||
"error": payload.get("error"),
|
||||
"reason": payload.get("reason"),
|
||||
"hint": payload.get("hint"),
|
||||
"remedy": remedy_for(outcome.returncode),
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
#: Query parameter -> the flag it becomes on the command line. One table, not
|
||||
#: one entry per resource: the name an agent puts in a URI and the flag the CLI
|
||||
#: takes are allowed to differ, and a per-entry copy would be a per-entry
|
||||
#: chance for them to disagree.
|
||||
_FLAGS = {"all": "all", "events": "events", "lines": "lines"}
|
||||
|
||||
#: Of those, the ones that are switches and not values -- so `?all=true` is
|
||||
#: `--all` and `?all=false` is no flag at all, rather than `--all=false`, which
|
||||
#: the CLI would refuse.
|
||||
_SWITCHES = {"all"}
|
||||
|
||||
_FALSE = {"false", "0", "no", "off", ""}
|
||||
|
||||
|
||||
def _flag_for(name: str, value: str) -> list[str]:
|
||||
flag = _FLAGS[name]
|
||||
if name in _SWITCHES:
|
||||
return [] if value.strip().lower() in _FALSE else [f"--{flag}"]
|
||||
return [tools.flag(flag, value)]
|
||||
|
||||
|
||||
def _json_read(verb: list[str], what: str) -> Read:
|
||||
"""A ``--json`` verb's protocol object, verbatim, as the resource's body.
|
||||
|
||||
Verbatim because that object is what the broker actually said, and a
|
||||
resource that reshaped it would be a second wire format for the same facts.
|
||||
"""
|
||||
|
||||
def read(runner: Runner, arguments: dict[str, str]) -> Reading:
|
||||
options = ["--json"]
|
||||
for name in sorted(arguments):
|
||||
if name in _FLAGS:
|
||||
options.extend(_flag_for(name, arguments[name]))
|
||||
positionals = [arguments["id"]] if "id" in arguments else []
|
||||
outcome = _checked(runner.run(tools.argv(verb, options, positionals)), what)
|
||||
return Reading(media_type=JSON, text=outcome.stdout.strip())
|
||||
|
||||
return read
|
||||
|
||||
|
||||
def _status(runner: Runner, arguments: dict[str, str]) -> Reading:
|
||||
"""``hhstream status``: the one verb with no ``--json``, so it stays text."""
|
||||
|
||||
outcome = _checked(runner.run(["status"]), "the session's status")
|
||||
return Reading(media_type=TEXT, text=outcome.stdout.strip())
|
||||
|
||||
|
||||
def _frame(runner: Runner, arguments: dict[str, str]) -> Reading:
|
||||
"""One captured frame as bytes.
|
||||
|
||||
Serves both the whole screen and one named output: ``hhstream://screen``
|
||||
captures with no ``--output`` and ``hhstream://outputs/{name}`` captures
|
||||
with one, which is the same CLI call with one flag more.
|
||||
|
||||
The media type is read off the bytes, never assumed: the publisher serves
|
||||
`image/jpeg` on some machines and the CLI writes the payload it was given
|
||||
verbatim, so the entry's declared `mimeType` is a hint and this is the
|
||||
answer.
|
||||
"""
|
||||
|
||||
named = arguments.get("name")
|
||||
what = f"output {named!r}" if named else "the screen"
|
||||
outcome, frame = tools.capture(runner, named)
|
||||
_checked(outcome, what)
|
||||
if frame is None:
|
||||
raise ReadRefused(
|
||||
f"hhstream shot reported success but wrote no readable file for {what}"
|
||||
)
|
||||
image = media.sniff(frame)
|
||||
return Reading(
|
||||
media_type=image.media_type if image else "application/octet-stream",
|
||||
blob=frame,
|
||||
)
|
||||
|
||||
|
||||
# ── the table ──────────────────────────────────────────────────────────────
|
||||
|
||||
#: Appended to the three descriptions whose verb the CLI's own note names.
|
||||
_NOT_ACTIVITY = (
|
||||
" Reading this does NOT reset the session's idle clock -- only the "
|
||||
"`session_touch` tool does."
|
||||
)
|
||||
|
||||
ENTRIES: tuple[Entry, ...] = (
|
||||
Entry(
|
||||
route=("status",),
|
||||
name="status",
|
||||
title="Is the desktop up",
|
||||
description=(
|
||||
"Whether the headless Hyprland session is running and reachable: "
|
||||
"each unit's state, the frame socket's path and whether this "
|
||||
"server can read it, the Wayland socket the compositor bound, and "
|
||||
"one probe frame's size. Read this first when something else "
|
||||
"fails in a way that smells like the desktop being down. It says "
|
||||
"nothing about the session broker -- an unreachable broker shows "
|
||||
"up as exit 5 from a session tool or a failed read of "
|
||||
"`hhstream://sessions`."
|
||||
),
|
||||
media_type=TEXT,
|
||||
read=_status,
|
||||
),
|
||||
Entry(
|
||||
route=("sessions",),
|
||||
name="sessions",
|
||||
title="Every tracked session",
|
||||
description=(
|
||||
"The broker's list: every session it is tracking, with its state, "
|
||||
"pid and idle deadline. `?all=true` includes the tombstones of "
|
||||
"ended ones." + _NOT_ACTIVITY
|
||||
),
|
||||
media_type=JSON,
|
||||
read=_json_read(["session", "list"], "the session list"),
|
||||
parameters=("all",),
|
||||
),
|
||||
Entry(
|
||||
route=("pointer",),
|
||||
name="pointer",
|
||||
title="Who holds the pointer",
|
||||
description=(
|
||||
"Who holds the one pointer lease, since when, and which buttons "
|
||||
"and KEYS are held down. This is what to read after a tool "
|
||||
"returns exit 8 (BUSY): it names the holder. There is one cursor, "
|
||||
"so there is one of these." + _NOT_ACTIVITY
|
||||
),
|
||||
media_type=JSON,
|
||||
read=_json_read(["session", "pointer", "state"], "the pointer lease"),
|
||||
),
|
||||
Entry(
|
||||
route=("containers",),
|
||||
name="containers",
|
||||
title="Every container, and the orphans",
|
||||
description=(
|
||||
"Each session's output, workspace and mode, plus the `hh-*` "
|
||||
"outputs no live session claims. The output names here are what "
|
||||
"`hhstream://outputs/{name}` and the `record` tool take.\n\n"
|
||||
"This is the LIST, which only reads the record. Asking where a "
|
||||
"session's window is *now* re-reads the compositor and writes the "
|
||||
"answer back, so it is the `session_container` tool and not a "
|
||||
"resource." + _NOT_ACTIVITY
|
||||
),
|
||||
media_type=JSON,
|
||||
read=_json_read(["session", "container"], "the container list"),
|
||||
),
|
||||
Entry(
|
||||
route=("screen",),
|
||||
name="screen",
|
||||
title="One frame of the screen",
|
||||
description=(
|
||||
"The published main output, as an image. This is the whole "
|
||||
"compositor layout: with containers on, each session's own output "
|
||||
"sits beside the main one, so the frame is wider than any single "
|
||||
"output's configured size. For one container alone, read "
|
||||
"`hhstream://outputs/{name}`."
|
||||
),
|
||||
media_type="image/png",
|
||||
read=_frame,
|
||||
),
|
||||
Entry(
|
||||
route=("sessions", "{id}"),
|
||||
name="session",
|
||||
title="One session, in detail",
|
||||
description=(
|
||||
"One session: its state, pid, container, idle deadline, and the "
|
||||
"most recent entries from the broker's audit trail. `?events=N` "
|
||||
"sets how many of those to include. The audit events are where a "
|
||||
"session that died for a reason its own logs do not show explains "
|
||||
"itself." + _NOT_ACTIVITY
|
||||
),
|
||||
media_type=JSON,
|
||||
read=_json_read(["session", "status"], "that session"),
|
||||
parameters=("events",),
|
||||
),
|
||||
Entry(
|
||||
route=("sessions", "{id}", "logs"),
|
||||
name="session-logs",
|
||||
title="A session's captured output",
|
||||
description=(
|
||||
"The tail of the application's own stdout and stderr, as the "
|
||||
"broker captured it -- the first place to look when an "
|
||||
"application started and then did nothing. `?lines=N` sets how "
|
||||
"much to tail.\n\n"
|
||||
"There is no following here and there cannot be: this SDK does "
|
||||
"not advertise resource subscriptions, and the CLI's `--follow` "
|
||||
"polls until interrupted. Read it again instead." + _NOT_ACTIVITY
|
||||
),
|
||||
media_type=JSON,
|
||||
read=_json_read(["session", "logs"], "that session's logs"),
|
||||
parameters=("lines",),
|
||||
),
|
||||
Entry(
|
||||
route=("outputs", "{name}"),
|
||||
name="output",
|
||||
title="One output's frame",
|
||||
description=(
|
||||
"One output captured in isolation through `grim` -- a session's "
|
||||
"container is `hh-<session-id>`, and `hhstream://containers` "
|
||||
"lists the names. Unlike `hhstream://screen` this is exactly the "
|
||||
"configured size of that output, which is the coordinate space "
|
||||
"the pointer tools aim in."
|
||||
),
|
||||
media_type="image/png",
|
||||
read=_frame,
|
||||
),
|
||||
)
|
||||
|
||||
BY_NAME: dict[str, Entry] = {entry.name: entry for entry in ENTRIES}
|
||||
|
||||
#: The fixed ones, for `resources/list`.
|
||||
FIXED: tuple[Entry, ...] = tuple(e for e in ENTRIES if not e.is_template)
|
||||
#: The rest, for `resources/templates/list`.
|
||||
TEMPLATES: tuple[Entry, ...] = tuple(e for e in ENTRIES if e.is_template)
|
||||
|
||||
|
||||
def read(runner: Runner, uri: str) -> Reading:
|
||||
"""Resolve ``uri`` and read it. Raises :class:`ReadRefused`."""
|
||||
|
||||
entry, arguments = resolve(uri)
|
||||
return entry.read(runner, arguments)
|
||||
@@ -0,0 +1,441 @@
|
||||
"""The MCP wiring. The only module here that imports the SDK.
|
||||
|
||||
Transport is **stdio** and nothing else: one process per client, spawned by the
|
||||
client, no port and no daemon. There is already a daemon in this system
|
||||
(`hhstreamd`) and it owns all the state; a second long-lived process in front of
|
||||
it would be a second place for a lease to be remembered.
|
||||
|
||||
The low-level :class:`mcp.server.Server` rather than FastMCP, for two reasons.
|
||||
The schemas here are written by hand -- ``pointer_move``'s exclusive ``to``/``by``
|
||||
pair, ``additionalProperties: false`` on every tool -- and deriving them from
|
||||
Python type hints would mean writing the signatures that happen to produce them.
|
||||
And ``shot`` returns image content beside its text, which is a content list, not
|
||||
a return value.
|
||||
|
||||
**The transport does not stay on file descriptor 1**, and that is load-bearing
|
||||
rather than tidy: the tools run the CLI's handlers *in this process*
|
||||
(:mod:`hhstream_mcp.invoke`), those handlers ``print``, and ``record`` spawns an
|
||||
``ffmpeg`` whose output the CLI does not capture. Any one of those writing on
|
||||
fd 1 would put a line of prose in the middle of a JSON-RPC stream, which a
|
||||
client reports as a parse failure with no hint of where it came from. So
|
||||
:func:`claim_transport` takes a private duplicate of stdin and stdout before
|
||||
anything else runs and then points fd 1 at the log and fd 0 at ``/dev/null``.
|
||||
After that the protocol is on descriptors nothing else in the process knows
|
||||
about, and a stray write is a log line.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import io
|
||||
import logging
|
||||
import os
|
||||
import sys
|
||||
from typing import Any
|
||||
|
||||
import anyio
|
||||
import mcp.types as types
|
||||
from mcp.server.lowlevel import NotificationOptions, Server
|
||||
from mcp.server.lowlevel.helper_types import ReadResourceContents
|
||||
from mcp.server.stdio import stdio_server
|
||||
from mcp.shared.exceptions import McpError
|
||||
from pydantic import AnyUrl
|
||||
|
||||
from . import SERVER_NAME, __version__, resources, tools
|
||||
from .invoke import Runner
|
||||
|
||||
log = logging.getLogger("hhstream.mcp")
|
||||
|
||||
#: Shown by a client that surfaces server instructions, and the one place the
|
||||
#: whole surface can be introduced at once. The two rules are repeated on the
|
||||
#: individual tools, because a per-tool description is what a client shows at
|
||||
#: the point of use.
|
||||
INSTRUCTIONS = """\
|
||||
Drive this machine's headless Hyprland desktop: look at it, put applications on
|
||||
it, and aim its one pointer and keyboard at them.
|
||||
|
||||
Everything here is one verb of the `hhstream` CLI and does nothing the CLI would
|
||||
not. The surface is split the way the protocol splits it:
|
||||
|
||||
* **Resources are the state.** `hhstream://status` is whether the desktop is up,
|
||||
`hhstream://sessions` is what is running, `hhstream://sessions/<id>` is one of
|
||||
them with its recent audit events, `hhstream://sessions/<id>/logs` is an
|
||||
application's own output, `hhstream://pointer` is who holds the input lease,
|
||||
`hhstream://containers` is each session's output and workspace. Reading any of
|
||||
them changes nothing.
|
||||
* **Tools are the acts.** `session_start` puts an allowlisted application on the
|
||||
screen and returns a session id; `shot` captures the screen now;
|
||||
`pointer_acquire` gives you the lease every pointer and keyboard tool needs;
|
||||
`session_kill` ends a session.
|
||||
|
||||
Two rules this surface will not let you avoid, because they are the two an agent
|
||||
gets wrong:
|
||||
|
||||
1. `session_touch` is the ONLY thing that resets a session's idle clock.
|
||||
Reading any resource deliberately does NOT, nor does `session_gc`, nor does
|
||||
clicking or typing. A session being driven is still a session nobody has said
|
||||
they want kept, and the broker reaps it on schedule.
|
||||
|
||||
2. Every keyboard tool needs the POINTER lease, and holds only while that lease
|
||||
holds. There is no keyboard lease: one compositor seat means one keyboard
|
||||
focus. A held non-modifier key floods the window until you lift it or the
|
||||
lease expires, because the application does the repeating.
|
||||
|
||||
Tool failures come back as tool errors carrying the CLI's own exit code, its
|
||||
machine-readable error name, its reason and what to do next. Exit 8 means
|
||||
another session holds the pointer lease (read `hhstream://pointer` for the
|
||||
holder); exit 9 means you need to acquire one. A resource read that the CLI
|
||||
refuses is raised as an error carrying the same remedy, because a resource has
|
||||
no way to hand back a failure as content.
|
||||
"""
|
||||
|
||||
|
||||
def annotations_for(tool: tools.Tool) -> types.ToolAnnotations:
|
||||
"""Hints, and only honest ones.
|
||||
|
||||
``readOnlyHint`` is set from the verb's own behaviour, which is why
|
||||
``session_container`` does not get it: with a session id that verb runs
|
||||
``container.reconcile`` and writes the record back. ``openWorldHint`` is
|
||||
false throughout -- the world here is one desktop on one machine.
|
||||
"""
|
||||
|
||||
return types.ToolAnnotations(
|
||||
title=tool.title,
|
||||
readOnlyHint=tool.read_only,
|
||||
# Meaningful only when `readOnlyHint` is false, and then stated rather
|
||||
# than left out: the spec's default for it is *true*, so omitting it
|
||||
# would mark `session_touch` and `record` as possibly destructive.
|
||||
destructiveHint=None if tool.read_only else tool.destructive,
|
||||
openWorldHint=False,
|
||||
)
|
||||
|
||||
|
||||
def describe(tool: tools.Tool) -> types.Tool:
|
||||
return types.Tool(
|
||||
name=tool.name,
|
||||
title=tool.title,
|
||||
description=tool.description,
|
||||
inputSchema=tool.schema,
|
||||
annotations=annotations_for(tool),
|
||||
)
|
||||
|
||||
|
||||
def listing() -> list[types.Tool]:
|
||||
return [describe(tool) for tool in tools.TOOLS]
|
||||
|
||||
|
||||
def content_for(result: tools.Result) -> list[types.ContentBlock]:
|
||||
blocks: list[types.ContentBlock] = [types.TextContent(type="text", text=result.text)]
|
||||
if result.image is not None and result.media_type:
|
||||
import base64
|
||||
|
||||
blocks.append(
|
||||
types.ImageContent(
|
||||
type="image",
|
||||
data=base64.b64encode(result.image).decode("ascii"),
|
||||
mimeType=result.media_type,
|
||||
)
|
||||
)
|
||||
return blocks
|
||||
|
||||
|
||||
def call(
|
||||
runner: Runner,
|
||||
name: str,
|
||||
arguments: dict[str, Any],
|
||||
available: Any = None,
|
||||
) -> types.CallToolResult:
|
||||
"""Run one tool. A refusal comes back as a tool error, never as a success.
|
||||
|
||||
``isError`` rather than a JSON-RPC error, throughout. That is not only a
|
||||
preference: the SDK's own ``call_tool`` handler catches whatever this raises
|
||||
and turns it into an ``isError`` result anyway, and for the CLI's refusals
|
||||
it is the right channel regardless -- "another session holds the lease" is
|
||||
something the calling agent has to read and act on, and a JSON-RPC error
|
||||
reaches the client's log rather than the agent. So the error text is
|
||||
written for the agent, including for the two cases that are not the CLI's
|
||||
verdict at all: a tool name that does not exist, and this layer's own bug.
|
||||
"""
|
||||
|
||||
# The *selected* set, not the whole table: a tool `--toolsets` left out is
|
||||
# not listed, so calling it must fail rather than work anyway. The SDK only
|
||||
# validates arguments against what `tools/list` returned, so without this a
|
||||
# client could reach an unlisted tool by name.
|
||||
offered = tools.BY_NAME if available is None else available
|
||||
tool = offered.get(name)
|
||||
if tool is None:
|
||||
known = ", ".join(sorted(offered)) or "nothing (every toolset is disabled)"
|
||||
hint = ""
|
||||
if name in tools.MOVED_TO_RESOURCES:
|
||||
# The v1 name. Say where it went rather than only that it is gone:
|
||||
# a caller asking for `session_list` wants the session list, and the
|
||||
# answer is one `resources/read` away.
|
||||
hint = (
|
||||
f" It is a RESOURCE now, not a tool: read "
|
||||
f"{tools.MOVED_TO_RESOURCES[name]} instead. Reading state is "
|
||||
"the host's to offer, not the model's to call -- call "
|
||||
"resources/list for the whole read-only half of this server."
|
||||
)
|
||||
elif name in tools.BY_NAME:
|
||||
hint = (
|
||||
f" {name!r} exists but this server was started without its "
|
||||
"toolset, so it is not offered."
|
||||
)
|
||||
return types.CallToolResult(
|
||||
content=[
|
||||
types.TextContent(
|
||||
type="text",
|
||||
text=f"no such tool: {name!r}.{hint} This server exposes: {known}",
|
||||
)
|
||||
],
|
||||
structuredContent={"ok": False, "error": "no_such_tool"},
|
||||
isError=True,
|
||||
)
|
||||
try:
|
||||
result = tool.invoke(runner, arguments)
|
||||
except (OSError, ValueError, KeyError) as exc:
|
||||
# `Runner.run` already turns a handler's own exception into exit 1 with
|
||||
# its traceback, so what reaches here is this layer's own fault -- a
|
||||
# schema and an argv builder that disagree about a field name. Reported
|
||||
# to the agent rather than only logged, because an agent that is told
|
||||
# nothing retries forever.
|
||||
log.exception("tool %s failed", name)
|
||||
result = tools.Result(
|
||||
text=f"the {name} tool failed before the CLI was called: {exc!r}",
|
||||
data={"ok": False, "error": "tool_failed"},
|
||||
is_error=True,
|
||||
)
|
||||
return types.CallToolResult(
|
||||
content=content_for(result),
|
||||
structuredContent=result.data,
|
||||
isError=result.is_error,
|
||||
)
|
||||
|
||||
|
||||
# ── resources ──────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def describe_resource(entry: resources.Entry) -> types.Resource:
|
||||
return types.Resource(
|
||||
uri=AnyUrl(entry.uri),
|
||||
name=entry.name,
|
||||
title=entry.title,
|
||||
description=entry.description,
|
||||
mimeType=entry.media_type,
|
||||
)
|
||||
|
||||
|
||||
def describe_template(entry: resources.Entry) -> types.ResourceTemplate:
|
||||
return types.ResourceTemplate(
|
||||
uriTemplate=entry.uri_template,
|
||||
name=entry.name,
|
||||
title=entry.title,
|
||||
description=entry.description,
|
||||
mimeType=entry.media_type,
|
||||
)
|
||||
|
||||
|
||||
def resource_listing() -> list[types.Resource]:
|
||||
return [describe_resource(entry) for entry in resources.FIXED]
|
||||
|
||||
|
||||
def template_listing() -> list[types.ResourceTemplate]:
|
||||
return [describe_template(entry) for entry in resources.TEMPLATES]
|
||||
|
||||
|
||||
def read(runner: Runner, uri: str) -> list[ReadResourceContents]:
|
||||
"""One resource read. A refusal is an error, because there is no other way.
|
||||
|
||||
A ``CallToolResult`` can say ``isError``; ``ReadResourceResult`` cannot. So
|
||||
a URI that names nothing, or a CLI that refused, is raised as a JSON-RPC
|
||||
error carrying the remedy a tool error would have carried. Handing back the
|
||||
broker's failure object as the resource's *body* would make "no such
|
||||
session" read as a successful read of a session.
|
||||
"""
|
||||
|
||||
try:
|
||||
reading = resources.read(runner, uri)
|
||||
except resources.ReadRefused as refused:
|
||||
raise McpError(
|
||||
types.ErrorData(
|
||||
code=types.INVALID_PARAMS,
|
||||
message=refused.message,
|
||||
data=refused.detail or None,
|
||||
)
|
||||
) from refused
|
||||
body = reading.blob if reading.blob is not None else (reading.text or "")
|
||||
return [ReadResourceContents(content=body, mime_type=reading.media_type)]
|
||||
|
||||
|
||||
def build(runner: Runner, toolsets: Any = None) -> Server:
|
||||
server: Server = Server(
|
||||
SERVER_NAME, version=__version__, instructions=INSTRUCTIONS
|
||||
)
|
||||
available = tools.selected(toolsets)
|
||||
by_name = {tool.name: tool for tool in available}
|
||||
|
||||
@server.list_tools()
|
||||
async def _list() -> list[types.Tool]:
|
||||
return [describe(tool) for tool in available]
|
||||
|
||||
@server.list_resources()
|
||||
async def _list_resources() -> list[types.Resource]:
|
||||
return resource_listing()
|
||||
|
||||
@server.list_resource_templates()
|
||||
async def _list_templates() -> list[types.ResourceTemplate]:
|
||||
return template_listing()
|
||||
|
||||
@server.read_resource()
|
||||
async def _read_resource(uri: AnyUrl) -> list[ReadResourceContents]:
|
||||
# Off the event loop for the reason a tool call is: this runs the CLI,
|
||||
# which blocks. `str(uri)` because the route is parsed here, not by
|
||||
# pydantic -- see `resources.split`.
|
||||
return await anyio.to_thread.run_sync(lambda: read(runner, str(uri)))
|
||||
|
||||
# `validate_input` left on: the schemas are the first refusal, and they
|
||||
# refuse before an argv list exists.
|
||||
@server.call_tool()
|
||||
async def _call(name: str, arguments: dict[str, Any]) -> types.CallToolResult:
|
||||
# The CLI call is blocking and can take seconds (`record`, a `start`
|
||||
# with a readiness budget), so it goes to a worker thread: the event
|
||||
# loop stays free to answer a ping and to read the next request. The
|
||||
# calls themselves are serialised inside `Runner.run`, because the CLI
|
||||
# prints to a stdout this process shares.
|
||||
return await anyio.to_thread.run_sync(lambda: call(runner, name, arguments, by_name))
|
||||
|
||||
return server
|
||||
|
||||
|
||||
def claim_transport() -> tuple[Any, Any]:
|
||||
"""Take stdin and stdout for the protocol, then make fd 0 and 1 harmless.
|
||||
|
||||
Returns the pair of streams to hand to ``stdio_server``. After this call
|
||||
the process's own ``sys.stdout`` writes to the log beside ``sys.stderr``,
|
||||
and nothing that reads stdin can eat a request: both are the right answer
|
||||
for a server whose tools run a CLI in-process.
|
||||
"""
|
||||
|
||||
stdin = anyio.wrap_file(
|
||||
io.TextIOWrapper(os.fdopen(os.dup(0), "rb"), encoding="utf-8", errors="replace")
|
||||
)
|
||||
stdout = anyio.wrap_file(
|
||||
io.TextIOWrapper(os.fdopen(os.dup(1), "wb"), encoding="utf-8")
|
||||
)
|
||||
sys.stdout.flush()
|
||||
# The literal descriptor 2, not `sys.stderr.fileno()`: what is wanted is
|
||||
# "whatever the log is at the file-descriptor level", so that a grandchild
|
||||
# which never heard of `sys` writes there too.
|
||||
os.dup2(2, 1)
|
||||
null = os.open(os.devnull, os.O_RDONLY)
|
||||
try:
|
||||
os.dup2(null, 0)
|
||||
finally:
|
||||
os.close(null)
|
||||
return stdin, stdout
|
||||
|
||||
|
||||
async def serve(server: Server, transport: tuple[Any, Any] | None = None) -> None:
|
||||
stdin, stdout = transport if transport is not None else claim_transport()
|
||||
async with stdio_server(stdin, stdout) as (read_stream, write_stream):
|
||||
await server.run(
|
||||
read_stream,
|
||||
write_stream,
|
||||
server.create_initialization_options(NotificationOptions()),
|
||||
)
|
||||
|
||||
|
||||
def build_parser() -> argparse.ArgumentParser:
|
||||
parser = argparse.ArgumentParser(
|
||||
prog="hhstream-mcp",
|
||||
description=(
|
||||
"Serve the hhstream CLI as Model Context Protocol tools over stdio. "
|
||||
"Spawned by an MCP client; it speaks JSON-RPC on stdin/stdout and "
|
||||
"logs to stderr."
|
||||
),
|
||||
epilog=(
|
||||
"There is no --socket flag here, deliberately: the sockets are the "
|
||||
"CLI's own environment -- $HHSTREAM_FRAME_SOCKET for the frame "
|
||||
"socket and $HHSTREAM_SOCKET for the broker's control socket -- and "
|
||||
"a second place to configure them is a second place for them to "
|
||||
"disagree. Set them in the MCP client's `env` block."
|
||||
),
|
||||
)
|
||||
parser.add_argument(
|
||||
"--toolsets",
|
||||
metavar="NAMES",
|
||||
help="comma-separated families to offer as tools: "
|
||||
+ ", ".join(tools.TOOLSETS)
|
||||
+ ". Omitted, every tool is offered. Resources are NOT filtered by "
|
||||
"this -- they are the host's context, not the model's tool budget.",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--list-tools",
|
||||
action="store_true",
|
||||
help="print the tool names and exit, without serving. Honours "
|
||||
"--toolsets, so it is also how to see what a selection would offer.",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--list-resources",
|
||||
action="store_true",
|
||||
help="print the resource URIs and templates and exit, without serving.",
|
||||
)
|
||||
return parser
|
||||
|
||||
|
||||
def chosen_toolsets(raw: str | None) -> list[str] | None:
|
||||
"""``--toolsets`` as a list, or ``None`` for every tool."""
|
||||
|
||||
if raw is None:
|
||||
return None
|
||||
names = [part.strip() for part in raw.split(",") if part.strip()]
|
||||
if not names:
|
||||
raise tools.UnknownToolset(
|
||||
"--toolsets was given no names. Omit the flag for every tool, or "
|
||||
f"name some of: {', '.join(tools.TOOLSETS)}"
|
||||
)
|
||||
return names
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
parser = build_parser()
|
||||
args = parser.parse_args(argv)
|
||||
# stderr, never stdout: stdout is the transport, and one stray print on it
|
||||
# is a protocol error the client reports as a parse failure.
|
||||
logging.basicConfig(
|
||||
level=os.environ.get("HHSTREAM_MCP_LOG", "WARNING").upper(),
|
||||
stream=sys.stderr,
|
||||
format="%(levelname)s %(name)s: %(message)s",
|
||||
)
|
||||
try:
|
||||
toolsets = chosen_toolsets(args.toolsets)
|
||||
offered = tools.selected(toolsets)
|
||||
except tools.UnknownToolset as exc:
|
||||
# argparse's own exit code for a bad argument, because that is what
|
||||
# this is: `choices=` cannot express a comma-separated subset.
|
||||
parser.error(str(exc))
|
||||
return int(2) # pragma: no cover -- parser.error exits
|
||||
if args.list_tools:
|
||||
for tool in offered:
|
||||
print(f"{tool.name}\t{tool.title}")
|
||||
return 0
|
||||
if args.list_resources:
|
||||
for entry in resources.FIXED:
|
||||
print(f"{entry.uri}\t{entry.title}")
|
||||
for entry in resources.TEMPLATES:
|
||||
print(f"{entry.uri_template}\t{entry.title}")
|
||||
return 0
|
||||
log.info(
|
||||
"serving %d tools and %d resources over stdio",
|
||||
len(offered),
|
||||
len(resources.ENTRIES),
|
||||
)
|
||||
# The transport is claimed before the event loop starts, so no coroutine can
|
||||
# have written to fd 1 by the time it moves.
|
||||
transport = claim_transport()
|
||||
anyio.run(serve, build(Runner(), toolsets), transport)
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__": # pragma: no cover
|
||||
raise SystemExit(main())
|
||||
File diff suppressed because it is too large.
Load diff
@@ -38,6 +38,9 @@ The verb tree, beyond the original eight:
|
||||
session keyboard type ID TEXT one argument, raw UTF-8, no escapes
|
||||
session keyboard key ID NAME tap: down then up
|
||||
session keyboard down/up ID NAME
|
||||
session stream enable ID publish ID's screen behind a spoken phrase
|
||||
session stream disable ID stop publishing, and forget the phrase
|
||||
session stream list/status what is being published, and who is watching
|
||||
|
||||
The pointer *and keyboard* verbs share one precondition — the pointer lease —
|
||||
and the lease id lives in :mod:`hhstream_session.lease` between invocations,
|
||||
@@ -187,6 +190,27 @@ def _build_namespace(parser: argparse.ArgumentParser) -> None:
|
||||
help="deduplication token: retrying a start with the same id returns the "
|
||||
"original reply instead of launching a second application",
|
||||
)
|
||||
start.add_argument(
|
||||
"--stream",
|
||||
action="store_true",
|
||||
help="also enable a live stream for this session and print its URL. "
|
||||
"Needs the session's container output, which this creates — which is "
|
||||
"why it is a flag here rather than a second command you have to "
|
||||
"sequence yourself.",
|
||||
)
|
||||
start.add_argument(
|
||||
"--stream-phrase",
|
||||
metavar="PHRASE",
|
||||
help="use this phrase instead of a minted one (four words and a "
|
||||
"five-character tail). It is the stream's only credential, so it is "
|
||||
"held to exactly that shape.",
|
||||
)
|
||||
start.add_argument(
|
||||
"--stream-fps",
|
||||
type=int,
|
||||
metavar="N",
|
||||
help="frames per second for the stream (default: the broker's)",
|
||||
)
|
||||
start.add_argument(
|
||||
"--no-container",
|
||||
action="store_true",
|
||||
@@ -303,6 +327,9 @@ def _build_namespace(parser: argparse.ArgumentParser) -> None:
|
||||
# ---- keyboard ----------------------------------------------------
|
||||
_build_keyboard(verbs, common)
|
||||
|
||||
# ---- stream ------------------------------------------------------
|
||||
_build_stream(verbs, common)
|
||||
|
||||
|
||||
#: Button names the driver knows (``hhstream_pointer.buttons.CODES``), mirrored
|
||||
#: here rather than imported: this module's whole integration promise is that it
|
||||
@@ -627,6 +654,136 @@ def _build_keyboard(verbs: Any, common: argparse.ArgumentParser) -> None:
|
||||
sub.add_argument("name", help="XKB keysym name, e.g. Control_L, Shift_L")
|
||||
|
||||
|
||||
#: Printed under `stream --help` and under `enable`. The two facts an operator
|
||||
#: gets wrong about this group, and they pull in opposite directions: the
|
||||
#: phrase is a password, and *watching* is the one thing besides `touch` that
|
||||
#: keeps a session alive.
|
||||
STREAM_NOTE = (
|
||||
"CREDENTIAL: the phrase in the URL is the stream's only protection — no "
|
||||
"TLS, no second factor. Anyone who can reach the port and guess four "
|
||||
"words can watch. It is never written to the audit log, and it is not "
|
||||
"echoed by 'list' unless you ask for --json.\n\n"
|
||||
"ACTIVITY: 'stream enable|disable|list|status' do NOT reset the idle "
|
||||
"clock, like every pointer and keyboard verb. But A CONNECTED VIEWER "
|
||||
"DOES: about once a minute the broker stamps 'touch' on any session "
|
||||
"somebody is watching, so a session you are watching on a phone is not "
|
||||
"reaped at three hours. An enabled stream with nobody watching captures "
|
||||
"nothing and keeps nothing alive."
|
||||
)
|
||||
|
||||
|
||||
def _build_stream(verbs: Any, common: argparse.ArgumentParser) -> None:
|
||||
"""``session stream <verb>`` — a live view of one session, behind a phrase.
|
||||
|
||||
A nested namespace for the reason ``pointer`` is one: these four verbs
|
||||
share a precondition nothing else here has. It is the session's **container
|
||||
output** — a stream never falls back to the main output, because that one
|
||||
carries every other session.
|
||||
"""
|
||||
|
||||
namespace = verbs.add_parser(
|
||||
"stream",
|
||||
parents=[common],
|
||||
help="publish one session's screen on the LAN, behind a spoken phrase",
|
||||
description=(
|
||||
"A live view of one session, in a browser, at a URL whose path is "
|
||||
"four words and a five-character tail. Off by default and per "
|
||||
"session: a session does not stream because it exists, it streams "
|
||||
"because it was switched on.\n\n"
|
||||
"What is published is the session's own container output, never "
|
||||
"the main one — that output carries every other session, and "
|
||||
"putting it behind one session's phrase is the mistake this "
|
||||
"refuses to make (exit 10 with no container).\n\n"
|
||||
"The transport is MJPEG over HTTP: a browser <img> is the whole "
|
||||
"client. Capture runs only while somebody is connected."
|
||||
),
|
||||
epilog=f"{STREAM_NOTE}\n\n{ACTIVITY_NOTE}",
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
)
|
||||
streams = namespace.add_subparsers(dest="stream_verb", metavar="VERB")
|
||||
namespace.set_defaults(
|
||||
func=_cmd_stream_list, hhstream_session_handler=_cmd_stream_list, json=False
|
||||
)
|
||||
|
||||
def add_stream_verb(name: str, handler, **kwargs: Any):
|
||||
sub = streams.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
|
||||
|
||||
enable = add_stream_verb(
|
||||
"enable",
|
||||
_cmd_stream_enable,
|
||||
help="switch a session's stream on and print its URL",
|
||||
description=(
|
||||
"Mint a phrase, open a capture, and print the URL on stdout — so "
|
||||
"$(hhstream session stream enable ID) is the URL and nothing "
|
||||
"else. The phrase is kept in the session's record, so it survives "
|
||||
"a broker restart and a re-enable: somebody you read it out to "
|
||||
"keeps the URL you gave them.\n\n"
|
||||
"Re-enabling an enabled session prints the same URL. A --phrase "
|
||||
"that differs from the stored one is exit 8 rather than a silent "
|
||||
"rotation, because rotating under a caller holding the old URL is "
|
||||
"the one outcome neither answer can be mistaken for. 'disable' "
|
||||
"then 'enable' rotates it."
|
||||
),
|
||||
epilog=f"{STREAM_NOTE}\n\n{ACTIVITY_NOTE}",
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
)
|
||||
enable.add_argument("id", help="session id")
|
||||
enable.add_argument(
|
||||
"--phrase",
|
||||
metavar="PHRASE",
|
||||
help="use this phrase instead of a minted one. Held to exactly the "
|
||||
"generated shape (four words of 3+ letters, then a five-character "
|
||||
"tail): it is a password, and a looser check would accept 'a-b-c'.",
|
||||
)
|
||||
enable.add_argument(
|
||||
"--fps",
|
||||
type=int,
|
||||
metavar="N",
|
||||
help="frames per second (default: the broker's; the daemon caps it)",
|
||||
)
|
||||
|
||||
disable = add_stream_verb(
|
||||
"disable",
|
||||
_cmd_stream_disable,
|
||||
help="switch a session's stream off and forget its phrase",
|
||||
description=(
|
||||
"Close the capture, drop the route, and clear the record. The "
|
||||
"phrase is gone: a later 'enable' mints a new one, which is how a "
|
||||
"phrase is rotated.\n\n"
|
||||
"Disabling a stream the daemon has already forgotten is not an "
|
||||
"error — that is the ordinary case after the daemon restarts, and "
|
||||
"the record has to be cleared either way. 'detached' says which "
|
||||
"happened."
|
||||
),
|
||||
)
|
||||
disable.add_argument("id", help="session id")
|
||||
|
||||
add_stream_verb(
|
||||
"list",
|
||||
_cmd_stream_list,
|
||||
help="every session with a stream (does NOT count as activity)",
|
||||
description=(
|
||||
"Every session a stream was enabled on, with its output, rate and "
|
||||
"connected viewer count. The phrase is shown only under --json: "
|
||||
"this listing is the kind of thing that ends up in a terminal "
|
||||
"somebody is sharing, and the phrase is the credential.\n\n"
|
||||
"'available' is whether the stream daemon could be asked at all, "
|
||||
"so 'no streams' is distinguishable from 'no daemon' without "
|
||||
"parsing an error."
|
||||
),
|
||||
)
|
||||
|
||||
status = add_stream_verb(
|
||||
"status",
|
||||
_cmd_stream_status,
|
||||
help="one session's stream (does NOT count as activity)",
|
||||
)
|
||||
status.add_argument("id", nargs="?", help="session id; omit for all of them")
|
||||
|
||||
|
||||
def _button_help() -> str:
|
||||
return f"one of: {', '.join(BUTTONS)} (default: left)"
|
||||
|
||||
@@ -749,6 +906,9 @@ def _cmd_start(args: argparse.Namespace) -> int:
|
||||
home=args.home,
|
||||
ephemeral_home=args.ephemeral_home or None,
|
||||
request_id=args.request_id,
|
||||
stream=args.stream or None,
|
||||
stream_phrase=args.stream_phrase,
|
||||
stream_fps=args.stream_fps,
|
||||
)
|
||||
if not reply.get("ok"):
|
||||
# A failed start may still have created a session (it exited at once, or
|
||||
@@ -778,6 +938,27 @@ def _cmd_start(args: argparse.Namespace) -> int:
|
||||
"(the only mark of activity; list/status/logs/gc do not count)",
|
||||
file=sys.stderr,
|
||||
)
|
||||
if args.stream:
|
||||
stream = session.get("stream") or {}
|
||||
error = session.get("stream_error")
|
||||
if stream.get("url"):
|
||||
# stdout, beside the id: the URL is the other thing a caller asked
|
||||
# for, and `$(... --stream)` giving the id and the URL on two lines
|
||||
# is more useful than making them run a second verb for it.
|
||||
print(stream["url"])
|
||||
print(
|
||||
f"watching it counts as activity; stop it with: hhstream "
|
||||
f"session stream disable {session_id}",
|
||||
file=sys.stderr,
|
||||
)
|
||||
else:
|
||||
# The session started. Saying so loudly, because the exit code is
|
||||
# 0 and a caller who asked for a stream must not read that as one.
|
||||
print(
|
||||
f"WARNING: the session is running but its stream was not "
|
||||
f"enabled: {error or 'the broker reported no stream'}",
|
||||
file=sys.stderr,
|
||||
)
|
||||
return int(ExitCode.OK)
|
||||
|
||||
|
||||
@@ -1312,6 +1493,77 @@ def _cmd_keyboard_hold(args: argparse.Namespace) -> int:
|
||||
return _finish_gesture(args, reply, render, args.id)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# the live stream
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
@_guard
|
||||
def _cmd_stream_enable(args: argparse.Namespace) -> int:
|
||||
reply = _request(
|
||||
args, "stream.enable", id=args.id, phrase=args.phrase, fps=args.fps
|
||||
)
|
||||
if not reply.get("ok"):
|
||||
return _finish(args, reply, lambda r: "")
|
||||
if args.json:
|
||||
fmt.dump_json(reply)
|
||||
return int(ExitCode.OK)
|
||||
stream = reply.get("stream") or {}
|
||||
# stdout is the URL and nothing else, the same shape `start` and `pointer
|
||||
# acquire` already have: one token a caller passes on, detail on stderr.
|
||||
print(stream.get("url") or "")
|
||||
print(
|
||||
f"{reply.get('id')}: streaming output {stream.get('output')} "
|
||||
f"at {stream.get('fps')} fps",
|
||||
file=sys.stderr,
|
||||
)
|
||||
print(
|
||||
"the phrase in that URL is its only protection, and watching it counts "
|
||||
"as activity; stop it with: hhstream session stream disable "
|
||||
f"{reply.get('id')}",
|
||||
file=sys.stderr,
|
||||
)
|
||||
if not stream.get("attached"):
|
||||
# `enable` cannot normally get here -- it had to attach to succeed --
|
||||
# but a reply without it means the daemon answered and then went away,
|
||||
# and a printed URL that serves nothing is worse than a warning.
|
||||
print(
|
||||
"WARNING: the broker recorded this stream but the daemon did not "
|
||||
"confirm it is attached; the URL may not answer",
|
||||
file=sys.stderr,
|
||||
)
|
||||
return int(ExitCode.OK)
|
||||
|
||||
|
||||
@_guard
|
||||
def _cmd_stream_disable(args: argparse.Namespace) -> int:
|
||||
reply = _request(args, "stream.disable", id=args.id)
|
||||
|
||||
def render(r: dict[str, Any]) -> str:
|
||||
detached = r.get("detached")
|
||||
return (
|
||||
f"{r.get('id')}: stream disabled and its phrase forgotten"
|
||||
+ ("" if detached else "; the daemon had already dropped it")
|
||||
)
|
||||
|
||||
return _finish(args, reply, render)
|
||||
|
||||
|
||||
@_guard
|
||||
def _cmd_stream_list(args: argparse.Namespace) -> int:
|
||||
reply = _request(args, "stream.list")
|
||||
return _finish(args, reply, fmt.render_streams)
|
||||
|
||||
|
||||
@_guard
|
||||
def _cmd_stream_status(args: argparse.Namespace) -> int:
|
||||
session_id = getattr(args, "id", None)
|
||||
reply = _request(args, "stream.status", id=session_id)
|
||||
if session_id is None:
|
||||
return _finish(args, reply, fmt.render_streams)
|
||||
return _finish(args, reply, fmt.render_stream)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# standalone use
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
@@ -120,6 +120,87 @@ def render_list(
|
||||
)
|
||||
|
||||
|
||||
def render_streams(reply: dict[str, Any]) -> str:
|
||||
"""``session stream list``: what is published, and who is watching.
|
||||
|
||||
**The phrase is not in this table**, and that is the whole shape of it. A
|
||||
listing is the kind of thing that ends up in a shared terminal, a paste or
|
||||
a screenshot, and the phrase is the stream's only credential — so what is
|
||||
shown is enough to recognise and manage a stream (the session, the output,
|
||||
the rate, the viewers) and not enough to watch one. ``--json`` carries the
|
||||
phrase and the URL, because a caller that asked for the object asked for
|
||||
the credential too.
|
||||
|
||||
``available`` is printed even when there are streams: "two records and no
|
||||
daemon" is a different situation from "two records and two captures", and
|
||||
the difference is invisible from the rows alone.
|
||||
"""
|
||||
|
||||
rows = []
|
||||
for row in reply.get("streams") or []:
|
||||
rows.append(
|
||||
[
|
||||
_cell(row.get("id")),
|
||||
_cell(row.get("app")),
|
||||
_cell(row.get("output")),
|
||||
_cell(row.get("fps")),
|
||||
"yes" if row.get("attached") else "NO",
|
||||
_cell(row.get("viewers")),
|
||||
]
|
||||
)
|
||||
lines = [
|
||||
render_table(rows, ["ID", "APP", "OUTPUT", "FPS", "LIVE", "VIEWERS"])
|
||||
if rows
|
||||
else "no session has a stream enabled"
|
||||
]
|
||||
available = reply.get("available")
|
||||
lines.append(
|
||||
"daemon: "
|
||||
+ (
|
||||
"answering"
|
||||
if available
|
||||
else "NOT REACHABLE — the records below are what was asked for, "
|
||||
"not what is running"
|
||||
)
|
||||
)
|
||||
if rows:
|
||||
lines.append(
|
||||
"the URL (with its phrase) is in --json, or in `stream status <id>`"
|
||||
)
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def render_stream(reply: dict[str, Any]) -> str:
|
||||
"""``session stream status ID``: one session's stream, URL included.
|
||||
|
||||
The URL *is* here, unlike in the listing: this was asked about one session
|
||||
by name, which is what somebody about to watch it does, and making them
|
||||
reach for ``--json`` to get the thing the verb is for would be a worse
|
||||
trade than the one the listing makes.
|
||||
"""
|
||||
|
||||
stream = reply.get("stream")
|
||||
if not stream:
|
||||
return f"{_cell(reply.get('id'))}: no stream enabled"
|
||||
lines = [
|
||||
f"{_cell(reply.get('id'))}: output {_cell(stream.get('output'))} "
|
||||
f"at {_cell(stream.get('fps'))} fps",
|
||||
]
|
||||
if stream.get("attached"):
|
||||
lines.append(f" url {_cell(stream.get('url'))}")
|
||||
lines.append(f" viewers {_cell(stream.get('viewers'))}")
|
||||
else:
|
||||
# No URL, deliberately: the record's phrase is still there, but a URL
|
||||
# that no longer serves anything is worse than none. See
|
||||
# `SessionManager._stream_public`.
|
||||
lines.append(
|
||||
" url — (the daemon is not publishing this; the phrase is "
|
||||
"kept, so re-enabling restores the same URL)"
|
||||
)
|
||||
lines.append(f" enabled {_cell(stream.get('enabled_at'))}")
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def render_containers(reply: dict[str, Any]) -> str:
|
||||
"""``session container`` with no id: every container, and every orphan.
|
||||
|
||||
|
||||
@@ -0,0 +1,301 @@
|
||||
"""The broker's end of the stream daemon's socket (CONTRACT-sessions.md §3.5).
|
||||
|
||||
`hhstream-live` is a third executor beside the pointer driver, and this module
|
||||
is the client that talks to it. The split is the driver's, for the driver's
|
||||
reasons: ``grim`` blocks tens to hundreds of milliseconds, so the capture must
|
||||
not run where ``touch`` and ``kill`` are answered, and a LAN-facing HTTP parser
|
||||
must not run in the frame server whose one-socket contract cannot grow one.
|
||||
|
||||
**The broker holds the decision; the daemon holds the capture.** Which session
|
||||
streams, and under which phrase, is the broker's — it is in the session record
|
||||
and it survives a restart. The port, the bind address, the capture command and
|
||||
the URL prefix are the daemon's, from its own unit's argv. So nothing here
|
||||
passes a port and nothing here builds a URL: :attr:`Attachment.url` comes back
|
||||
from the daemon, because a URL assembled from a port the broker was told about
|
||||
once is a URL that lies the first time an operator moves the listener.
|
||||
|
||||
**The phrase is never logged.** It is the stream's only credential, in
|
||||
cleartext in a URL on whatever the bind allows. Every log line here names the
|
||||
output and the session; `_safe` is what keeps a phrase out of the ones that
|
||||
would otherwise carry it.
|
||||
|
||||
Transport, lifetime and failure semantics are :mod:`hhstreamd.driver`'s, down to
|
||||
the held connection and the EOF check before each write. One difference in
|
||||
what a failure *means*: a dropped `release_all` leaves a key down in the
|
||||
compositor, which is why the driver never retries; a dropped `attach` leaves
|
||||
nothing behind but an unattached phrase, so `attach` is **idempotent on the
|
||||
daemon's side** and re-sending it is safe. That is the daemon's guarantee, not
|
||||
this module's, and it is what makes re-enabling after a restart cheap.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import dataclasses
|
||||
import json
|
||||
import logging
|
||||
import select
|
||||
import socket
|
||||
import threading
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
log = logging.getLogger("hhstreamd.live")
|
||||
|
||||
#: The daemon answers from memory for every op here -- it does not capture a
|
||||
#: frame to answer `attach`, and `viewers` is a counter read. This only bounds
|
||||
#: a daemon that has stopped answering at all.
|
||||
DEFAULT_TIMEOUT_S = 2.0
|
||||
|
||||
#: Matches the daemon's own ceiling.
|
||||
MAX_LINE_BYTES = 1 << 20
|
||||
|
||||
|
||||
class LiveUnavailable(Exception):
|
||||
"""The daemon could not be reached, or did not answer intelligibly.
|
||||
|
||||
Distinct from :class:`LiveRejected`: this one means nothing is known about
|
||||
whether the stream is attached, so the caller reports a *degraded* stream
|
||||
rather than an absent one. The session is unaffected either way -- a
|
||||
stream that cannot be reached is a stream, not a dead application -- which
|
||||
is why the manager maps this to exit 10 and never to a session failure.
|
||||
"""
|
||||
|
||||
|
||||
class LiveRejected(Exception):
|
||||
"""The daemon refused. ``kind`` decides the exit code, as the driver's does."""
|
||||
|
||||
def __init__(self, message: str, *, kind: str | None = None) -> None:
|
||||
super().__init__(message)
|
||||
self.kind = kind
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Attachment:
|
||||
"""One stream, as the daemon reports it."""
|
||||
|
||||
phrase: str
|
||||
output: str
|
||||
fps: int
|
||||
session: str | None
|
||||
#: The daemon's own prefix, e.g. ``http://127.0.0.1:9988/<phrase>/``.
|
||||
url: str
|
||||
viewers: int
|
||||
|
||||
@classmethod
|
||||
def parse(cls, data: Any) -> "Attachment":
|
||||
if not isinstance(data, dict):
|
||||
raise ValueError(f"stream is not an object: {type(data).__name__}")
|
||||
try:
|
||||
return cls(
|
||||
phrase=str(data["phrase"]),
|
||||
output=str(data["output"]),
|
||||
fps=int(data["fps"]),
|
||||
session=None if data.get("session") is None else str(data["session"]),
|
||||
url=str(data.get("url") or ""),
|
||||
viewers=int(data.get("viewers") or 0),
|
||||
)
|
||||
except (KeyError, TypeError, ValueError) as exc:
|
||||
raise ValueError(f"malformed stream in the daemon's reply: {exc}") from exc
|
||||
|
||||
|
||||
def _safe(phrase: str) -> str:
|
||||
"""A phrase, for a log line. The shape, never the words.
|
||||
|
||||
``amber-otter-lantern-harbor-7k2qp`` becomes ``<phrase:5 tokens>``. A log
|
||||
is read by whoever can read logs, and this one is a password.
|
||||
"""
|
||||
|
||||
return f"<phrase:{len(phrase.split('-'))} tokens>"
|
||||
|
||||
|
||||
class LiveStreams:
|
||||
"""A client for one stream daemon's socket. Thread-safe; one op at a time."""
|
||||
|
||||
def __init__(self, socket_path: Path | str, *, timeout_s: float = DEFAULT_TIMEOUT_S) -> None:
|
||||
self.socket_path = Path(socket_path)
|
||||
self.timeout_s = float(timeout_s)
|
||||
self._lock = threading.Lock()
|
||||
self._sock: socket.socket | None = None
|
||||
self._stream = None
|
||||
|
||||
# -- the ops ----------------------------------------------------------
|
||||
|
||||
def attach(
|
||||
self,
|
||||
*,
|
||||
phrase: str,
|
||||
output: str,
|
||||
fps: int | None = None,
|
||||
session: str | None = None,
|
||||
label: str = "",
|
||||
) -> Attachment:
|
||||
"""Publish ``output`` under ``phrase``. Idempotent on the phrase.
|
||||
|
||||
The daemon returns the existing stream if the same phrase is already
|
||||
aimed at the same output, rather than starting a second capture: a
|
||||
re-enable after a broker restart must not double the ``grim`` rate on
|
||||
one output. The same phrase aimed somewhere else is a rejection.
|
||||
|
||||
``fps`` is **omitted** when nobody asked for one, and that is the point:
|
||||
the default rate is the daemon's, from its own unit's argv, for the same
|
||||
reason the port is. A broker that sent its own default on every attach
|
||||
would make the operator's ``sessions.stream.fps`` a setting that changed
|
||||
nothing -- which is exactly the failure the keyboard layout's
|
||||
``--xkb-layout`` comment in this tree is about.
|
||||
"""
|
||||
|
||||
request: dict[str, Any] = {
|
||||
"op": "attach",
|
||||
"phrase": phrase,
|
||||
"output": output,
|
||||
"session": session,
|
||||
"label": label,
|
||||
}
|
||||
if fps is not None:
|
||||
request["fps"] = int(fps)
|
||||
reply = self.request(request)
|
||||
attachment = Attachment.parse(reply.get("stream"))
|
||||
log.info(
|
||||
"attached %s to output %s at %s fps (%s)",
|
||||
session or "a standalone stream",
|
||||
output,
|
||||
attachment.fps,
|
||||
_safe(phrase),
|
||||
)
|
||||
return attachment
|
||||
|
||||
def detach(self, phrase: str) -> bool:
|
||||
"""Stop publishing ``phrase``. ``False`` if it was not attached.
|
||||
|
||||
Not an error: ``disable`` on a session whose daemon restarted since
|
||||
``enable`` is the ordinary case, and the caller's job is to clear the
|
||||
record either way.
|
||||
"""
|
||||
|
||||
reply = self.request({"op": "detach", "phrase": phrase})
|
||||
return bool(reply.get("detached"))
|
||||
|
||||
def list(self) -> list[Attachment]:
|
||||
"""Every stream the daemon is publishing, in its own order."""
|
||||
|
||||
reply = self.request({"op": "list"})
|
||||
streams = reply.get("streams")
|
||||
if not isinstance(streams, list):
|
||||
raise LiveUnavailable(
|
||||
f"stream daemon {self.socket_path}: `list` returned "
|
||||
f"{type(streams).__name__}, not a list"
|
||||
)
|
||||
try:
|
||||
return [Attachment.parse(entry) for entry in streams]
|
||||
except ValueError as exc:
|
||||
raise LiveUnavailable(f"stream daemon {self.socket_path}: {exc}") from exc
|
||||
|
||||
def viewers(self) -> dict[str, int]:
|
||||
"""Phrase to connected viewers, for the activity sweep (§4).
|
||||
|
||||
A reading, and nothing more: what it means for the idle clock is the
|
||||
manager's, and this module deliberately has no opinion about it.
|
||||
"""
|
||||
|
||||
reply = self.request({"op": "viewers"})
|
||||
counts = reply.get("viewers")
|
||||
if not isinstance(counts, dict):
|
||||
raise LiveUnavailable(
|
||||
f"stream daemon {self.socket_path}: `viewers` returned "
|
||||
f"{type(counts).__name__}, not an object"
|
||||
)
|
||||
read: dict[str, int] = {}
|
||||
for phrase, count in counts.items():
|
||||
try:
|
||||
read[str(phrase)] = int(count)
|
||||
except (TypeError, ValueError) as exc:
|
||||
raise LiveUnavailable(
|
||||
f"stream daemon {self.socket_path}: viewer count for "
|
||||
f"{_safe(str(phrase))} is not a number: {exc}"
|
||||
) from exc
|
||||
return read
|
||||
|
||||
# -- transport --------------------------------------------------------
|
||||
|
||||
def request(self, message: dict[str, Any]) -> dict[str, Any]:
|
||||
"""One request, one reply. Raises rather than returning a guess."""
|
||||
|
||||
with self._lock:
|
||||
try:
|
||||
return self._exchange(message)
|
||||
except (OSError, ValueError) as exc:
|
||||
# The connection is now of unknown state -- a half-written
|
||||
# request, a partial reply -- so it is dropped rather than
|
||||
# reused for the next op.
|
||||
self._disconnect()
|
||||
raise LiveUnavailable(f"stream daemon {self.socket_path}: {exc}") from exc
|
||||
|
||||
def close(self) -> None:
|
||||
with self._lock:
|
||||
self._disconnect()
|
||||
|
||||
def _exchange(self, message: dict[str, Any]) -> dict[str, Any]:
|
||||
stream = self._connect()
|
||||
line = json.dumps(message, separators=(",", ":")).encode("utf-8") + b"\n"
|
||||
stream.write(line)
|
||||
stream.flush()
|
||||
reply_line = stream.readline(MAX_LINE_BYTES + 1)
|
||||
if not reply_line:
|
||||
raise OSError("the daemon closed the connection without answering")
|
||||
if len(reply_line) > MAX_LINE_BYTES:
|
||||
raise ValueError("reply exceeds the frame limit")
|
||||
reply = json.loads(reply_line)
|
||||
if not isinstance(reply, dict):
|
||||
raise ValueError(f"reply is not an object: {type(reply).__name__}")
|
||||
if not reply.get("ok"):
|
||||
kind = reply.get("kind")
|
||||
raise LiveRejected(
|
||||
str(reply.get("error") or "the stream daemon refused the request"),
|
||||
kind=kind if isinstance(kind, str) else None,
|
||||
)
|
||||
return reply
|
||||
|
||||
def _connect(self):
|
||||
if self._stream is not None and not self._stale():
|
||||
return self._stream
|
||||
self._disconnect()
|
||||
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
||||
try:
|
||||
sock.settimeout(self.timeout_s)
|
||||
sock.connect(str(self.socket_path))
|
||||
except OSError:
|
||||
sock.close()
|
||||
raise
|
||||
self._sock = sock
|
||||
self._stream = sock.makefile("rwb")
|
||||
log.debug("connected to the stream daemon at %s", self.socket_path)
|
||||
return self._stream
|
||||
|
||||
def _stale(self) -> bool:
|
||||
"""True if the held connection has died since the last op.
|
||||
|
||||
The daemon never speaks unsolicited, so a readable socket can only be
|
||||
at EOF. One non-blocking ``select``, and it is what makes reconnecting
|
||||
safe: a request is written only to a connection that was alive when it
|
||||
was written.
|
||||
"""
|
||||
|
||||
sock = self._sock
|
||||
if sock is None:
|
||||
return True
|
||||
try:
|
||||
readable, _, _ = select.select([sock], [], [], 0)
|
||||
except (OSError, ValueError):
|
||||
return True
|
||||
return bool(readable)
|
||||
|
||||
def _disconnect(self) -> None:
|
||||
stream, self._stream = self._stream, None
|
||||
sock, self._sock = self._sock, None
|
||||
for closeable in (stream, sock):
|
||||
if closeable is None:
|
||||
continue
|
||||
try:
|
||||
closeable.close()
|
||||
except OSError:
|
||||
pass
|
||||
+468
-4
@@ -57,6 +57,7 @@ from .container_host import (
|
||||
ContainerHost,
|
||||
)
|
||||
from .driver import DriverRejected, DriverUnavailable, PointerDriver
|
||||
from .live import Attachment, LiveRejected, LiveStreams, LiveUnavailable
|
||||
from .ipc import CompositorUnavailable
|
||||
from .launcher import Launcher
|
||||
from .pointer import Bookmark, LeaseBusy, LeaseInvalid, PointerLease
|
||||
@@ -70,6 +71,7 @@ from .registry import (
|
||||
State,
|
||||
container_record,
|
||||
pointer_record,
|
||||
stream_record,
|
||||
)
|
||||
from .textio import tail_lines
|
||||
|
||||
@@ -110,6 +112,16 @@ READBACK_INTERVAL_S = 0.05
|
||||
#: as long as nobody asks.
|
||||
POINTER_SWEEP_S = 1.0
|
||||
|
||||
#: How often the broker asks the stream daemon for viewer counts, and stamps
|
||||
#: `touch` on every session that has one (CONTRACT-sessions.md §4).
|
||||
#:
|
||||
#: A minute, not a second: this is the one exception to "`touch` is the only
|
||||
#: mark of activity", and the thing it exists to prevent is a three-hour idle
|
||||
#: timeout firing under somebody's eyes. Against three hours a minute of
|
||||
#: granularity is free, and a tighter sweep would be one `grim`-adjacent round
|
||||
#: trip per second for a fact that changes when a browser tab opens.
|
||||
STREAM_SWEEP_S = 60.0
|
||||
|
||||
#: The workspace band (CONTRACT-sessions.md §5) and how many slots of it this
|
||||
#: broker will hand out. The real ceiling is a CPU question the plan defers to
|
||||
#: a measurement (PLAN §5.5); the band is the part that can be enforced here,
|
||||
@@ -199,8 +211,17 @@ class ManagerConfig:
|
||||
pointer_ttl_s: float = 30.0
|
||||
pointer_max_s: float = 300.0
|
||||
pointer_sweep_s: float = POINTER_SWEEP_S
|
||||
#: The broker↔stream socket (CONTRACT-sessions.md §3.5). Derived from the
|
||||
#: runtime dir for the reason `pointer_socket` is: the path is frozen, so a
|
||||
#: flag for it would be a flag for a value that may not vary.
|
||||
live_socket: Path | None = None
|
||||
#: How often the viewer sweep runs. The one thing that moves an idle clock
|
||||
#: without a caller asking (CONTRACT-sessions.md §4).
|
||||
stream_sweep_s: float = STREAM_SWEEP_S
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
if self.live_socket is None:
|
||||
self.live_socket = Path(self.runtime_dir) / "live.sock"
|
||||
if self.pointer_socket is None:
|
||||
# `<runtime dir>/pointer.sock` is the frozen path
|
||||
# (CONTRACT-sessions.md §5: /run/hhstream/pointer.sock), and
|
||||
@@ -221,6 +242,7 @@ class SessionManager:
|
||||
audit: AuditLog | None = None,
|
||||
host: ContainerHost | None = None,
|
||||
driver: PointerDriver | None = None,
|
||||
live: LiveStreams | None = None,
|
||||
) -> None:
|
||||
self.config = config
|
||||
self.clock = clock or Clock()
|
||||
@@ -251,6 +273,10 @@ class SessionManager:
|
||||
ttl_s=config.pointer_ttl_s, max_s=config.pointer_max_s, clock=self.clock.boottime
|
||||
)
|
||||
self.driver = driver
|
||||
#: The stream daemon's client, or ``None`` with no socket configured --
|
||||
#: in which case every `stream.*` verb answers `stream_unavailable`
|
||||
#: (exit 10) rather than pretending there is a stream.
|
||||
self.live = live
|
||||
# Per-session asyncio plumbing, never persisted.
|
||||
self._exited: dict[str, asyncio.Event] = {}
|
||||
self._watchers: dict[str, asyncio.Task] = {}
|
||||
@@ -259,6 +285,7 @@ class SessionManager:
|
||||
#: Held so the loop does not collect a task mid-flight.
|
||||
self._background: set[asyncio.Task] = set()
|
||||
self._pointer_sweeper: asyncio.Task | None = None
|
||||
self._stream_sweeper: asyncio.Task | None = None
|
||||
#: Set while a lease is held with a caller-supplied TTL, so the default
|
||||
#: comes back when the lease ends (the frozen ``acquire`` takes no TTL).
|
||||
self._pointer_ttl_override = False
|
||||
@@ -339,6 +366,13 @@ class SessionManager:
|
||||
self._pointer_sweeper = asyncio.create_task(
|
||||
self._sweep_pointer(), name="hhstreamd.pointer-sweep"
|
||||
)
|
||||
# Unconditional, even with no stream enabled anywhere: the sweep's own
|
||||
# first act is to ask the daemon, and a broker that only started it on
|
||||
# the first `enable` would be a broker whose adopted records were not
|
||||
# being watched after a restart.
|
||||
self._stream_sweeper = asyncio.create_task(
|
||||
self._sweep_streams(), name="hhstreamd.stream-sweep"
|
||||
)
|
||||
return summary
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
@@ -632,11 +666,14 @@ class SessionManager:
|
||||
"""
|
||||
|
||||
await self.reaper.stop()
|
||||
if self._pointer_sweeper is not None:
|
||||
self._pointer_sweeper.cancel()
|
||||
for name in ("_pointer_sweeper", "_stream_sweeper"):
|
||||
sweeper = getattr(self, name)
|
||||
if sweeper is None:
|
||||
continue
|
||||
sweeper.cancel()
|
||||
with contextlib.suppress(asyncio.CancelledError, Exception):
|
||||
await self._pointer_sweeper
|
||||
self._pointer_sweeper = None
|
||||
await sweeper
|
||||
setattr(self, name, None)
|
||||
for task in list(self._background):
|
||||
task.cancel()
|
||||
for task in list(self._background):
|
||||
@@ -650,6 +687,12 @@ class SessionManager:
|
||||
with contextlib.suppress(Exception):
|
||||
await self._release_all_buttons()
|
||||
self.driver.close()
|
||||
if self.live is not None:
|
||||
# Nothing to lift on this one: a stream left attached across a
|
||||
# broker restart is re-attached by `enable`, and the daemon keeps
|
||||
# publishing meanwhile -- which is the behaviour an operator
|
||||
# watching a long job wants.
|
||||
self.live.close()
|
||||
for task in list(self._watchers.values()):
|
||||
task.cancel()
|
||||
for task in list(self._watchers.values()):
|
||||
@@ -878,6 +921,9 @@ class SessionManager:
|
||||
wait_ready_s: float | None = None,
|
||||
home: str | None = None,
|
||||
ephemeral_home: bool = False,
|
||||
stream: bool = False,
|
||||
stream_phrase: str | None = None,
|
||||
stream_fps: int | None = None,
|
||||
) -> dict[str, Any]:
|
||||
policy = self.config.policy
|
||||
policy.check_capacity(len(self.registry.live()))
|
||||
@@ -971,8 +1017,38 @@ class SessionManager:
|
||||
ready = await self._settle(session, wait_ready)
|
||||
if session.live:
|
||||
await self._read_back(session, app_id)
|
||||
stream_error: str | None = None
|
||||
if stream and session.live:
|
||||
# After the read-back, because that is what settles the container's
|
||||
# output, and a stream has to have one to publish
|
||||
# (`_stream_output`). Before the record below, so the phrase comes
|
||||
# back with the session the caller asked for -- which is the whole
|
||||
# reason `start` takes these arguments instead of making every
|
||||
# caller sequence "start, then enable" and handle the half-done
|
||||
# case in between.
|
||||
#
|
||||
# A stream that cannot be opened does NOT fail the start. The
|
||||
# application is on the screen and killing it over a web page would
|
||||
# be the wrong trade; the refusal is reported on the session's
|
||||
# `stream_error` and the caller can retry `stream.enable`.
|
||||
try:
|
||||
await self.stream_enable(
|
||||
session.id, phrase=stream_phrase, fps=stream_fps
|
||||
)
|
||||
except ManagerError as exc:
|
||||
log.warning("could not enable %s's stream: %s", session.id, exc.reason)
|
||||
session.last_error = session.last_error or exc.reason
|
||||
# A local, not an attribute: two starts can be in flight at
|
||||
# once and an attribute would hand one of them the other's
|
||||
# failure.
|
||||
stream_error = exc.reason
|
||||
self.reaper.wake()
|
||||
record = session.public(self.now())
|
||||
if stream:
|
||||
# Present whenever a stream was asked for, `None` when it worked:
|
||||
# a key that appears only on failure is a key every caller has to
|
||||
# remember to look for.
|
||||
record["stream_error"] = stream_error
|
||||
if session.state == State.EXITED:
|
||||
# The app exited during the settle: surface it rather than handing
|
||||
# back a healthy-looking id (DESIGN.md §7 #3).
|
||||
@@ -1235,7 +1311,17 @@ class SessionManager:
|
||||
# has four values (lease|timeout|crash|kill), and a reap is the
|
||||
# broker killing the session.
|
||||
await self._drop_lease_for(session, reason="kill")
|
||||
# The stream goes BEFORE the output does, and the order is
|
||||
# load-bearing (CONTRACT-sessions.md §4): a capture aimed at a
|
||||
# removed output fails every time, so the daemon's own failure
|
||||
# budget would close the viewers with "unknown output" instead of
|
||||
# the session simply ending. Never raises -- a daemon that cannot
|
||||
# be reached must not stop a session being killed.
|
||||
stream_detached = await self._detach_stream(session)
|
||||
if (session.stream or {}).get("phrase"):
|
||||
session.stream = None
|
||||
container_result = self._destroy_container(session)
|
||||
container_result["stream_detached"] = stream_detached
|
||||
|
||||
if refused is None:
|
||||
state_now = state
|
||||
@@ -1929,6 +2015,368 @@ class SessionManager:
|
||||
|
||||
# -- lease internals --------------------------------------------------
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# the live stream (CONTRACT-sessions.md §4, v4)
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
async def stream_enable(
|
||||
self, session_id: str, *, phrase: str | None = None, fps: int | None = None
|
||||
) -> dict[str, Any]:
|
||||
"""Publish this session's container output under a spoken phrase.
|
||||
|
||||
**Does not** count as activity, like every `pointer.*` verb: switching
|
||||
a stream on is not saying the session is wanted. What *is* activity is
|
||||
somebody watching it, and that is :meth:`_sweep_streams`.
|
||||
|
||||
The phrase is minted here and stored in the record, so it survives a
|
||||
broker restart and a re-enable: an operator who read four words out to
|
||||
somebody must not have them change because the daemon bounced. A
|
||||
caller's own `phrase` is held to the generated shape -- it is this
|
||||
stream's only credential, so anything a caller may set is a password,
|
||||
and a looser check would accept `a-b-c`.
|
||||
|
||||
Re-enabling an enabled session returns the same phrase. A different
|
||||
`phrase` is `stream_busy` (exit 8) rather than a silent rotation,
|
||||
because rotating under a caller who is holding the old URL is the one
|
||||
outcome neither answer can be mistaken for.
|
||||
"""
|
||||
|
||||
session = self._require_live(session_id)
|
||||
output = self._stream_output(session)
|
||||
rate = self._checked_fps(fps)
|
||||
stored = session.stream or {}
|
||||
wanted = self._checked_phrase(phrase)
|
||||
|
||||
if stored.get("phrase") and wanted and wanted != stored["phrase"]:
|
||||
raise ManagerError(
|
||||
"stream_busy",
|
||||
f"session {session.id} already has a stream under a different phrase",
|
||||
hint="`stream disable` then `stream enable` rotates it; a stream "
|
||||
"cannot have two phrases, because the old one is a URL somebody "
|
||||
"may be holding",
|
||||
id=session.id,
|
||||
)
|
||||
settled = stored.get("phrase") or wanted or self._mint_phrase()
|
||||
# The stored rate wins on a re-enable with no `fps`: a re-attach after a
|
||||
# restart must not quietly re-rate a stream somebody is watching. With
|
||||
# neither, the rate is left UNSET and the daemon applies its own
|
||||
# configured default -- the broker does not have one, on purpose.
|
||||
rate = rate or stored.get("fps")
|
||||
|
||||
attachment = await self._attach_stream(
|
||||
session, phrase=settled, output=output, fps=None if rate is None else int(rate)
|
||||
)
|
||||
record = stream_record(
|
||||
phrase=settled,
|
||||
output=output,
|
||||
fps=attachment.fps,
|
||||
enabled_at=stored.get("enabled_at") or iso(self.clock.wall()),
|
||||
)
|
||||
session.stream = record
|
||||
# `force=True`: the phrase is the one field here that cannot be
|
||||
# re-derived, so it is on disk before the caller is told what it is.
|
||||
self.registry.persist(session, force=True)
|
||||
# The phrase is NOT in the audit entry (CONTRACT-sessions.md §3.5): the
|
||||
# log is read by whoever can read logs, and this one is a password.
|
||||
self.audit.emit(
|
||||
"stream_enable", id=session.id, output=output, fps=attachment.fps
|
||||
)
|
||||
return {"id": session.id, "stream": self._stream_public(record, attachment)}
|
||||
|
||||
async def stream_disable(self, session_id: str) -> dict[str, Any]:
|
||||
"""Stop publishing, and clear the record.
|
||||
|
||||
Detaching a stream the daemon has already forgotten is **not** an
|
||||
error: `disable` after a daemon restart is the ordinary case, and the
|
||||
record has to be cleared either way. `detached` says which happened.
|
||||
"""
|
||||
|
||||
session = self._require_live(session_id)
|
||||
stored = session.stream or {}
|
||||
if not stored.get("phrase"):
|
||||
raise ManagerError(
|
||||
"stream_unavailable",
|
||||
f"session {session.id} has no stream to disable",
|
||||
hint="`stream enable` first",
|
||||
id=session.id,
|
||||
)
|
||||
detached = await self._detach_stream(session)
|
||||
session.stream = None
|
||||
self.registry.persist(session, force=True)
|
||||
self.audit.emit(
|
||||
"stream_disable", id=session.id, output=stored.get("output"), detached=detached
|
||||
)
|
||||
return {"id": session.id, "stream": None, "detached": detached}
|
||||
|
||||
def stream_list(self) -> dict[str, Any]:
|
||||
"""Every session with a stream, with the daemon's view merged in.
|
||||
|
||||
Does not count as activity. ``available`` is whether the daemon could
|
||||
be asked at all, so a caller can tell "no streams" from "no daemon"
|
||||
without parsing an error.
|
||||
"""
|
||||
|
||||
attachments, available = self._attachments()
|
||||
streams = []
|
||||
for session in self.registry.live():
|
||||
stored = session.stream or {}
|
||||
if not stored.get("phrase"):
|
||||
continue
|
||||
streams.append(
|
||||
{
|
||||
"id": session.id,
|
||||
"app": session.app,
|
||||
**self._stream_public(stored, attachments.get(stored["phrase"])),
|
||||
}
|
||||
)
|
||||
return {"streams": streams, "available": available}
|
||||
|
||||
def stream_status(self, session_id: str | None = None) -> dict[str, Any]:
|
||||
"""One session's stream, or every one of them. Not activity."""
|
||||
|
||||
if session_id is None:
|
||||
return self.stream_list()
|
||||
session = self._require(session_id)
|
||||
stored = session.stream or {}
|
||||
if not stored.get("phrase"):
|
||||
return {"id": session.id, "stream": None}
|
||||
attachments, _ = self._attachments()
|
||||
return {
|
||||
"id": session.id,
|
||||
"stream": self._stream_public(stored, attachments.get(stored["phrase"])),
|
||||
}
|
||||
|
||||
# -- the pieces the four verbs share ---------------------------------
|
||||
|
||||
def _stream_output(self, session: Session) -> str:
|
||||
"""The output a stream publishes: the session's own container.
|
||||
|
||||
Refused rather than defaulted, and the reason is stronger than the
|
||||
pointer's: the main output carries *every other session*, so falling
|
||||
back to it would put somebody else's desktop on a phone behind a phrase
|
||||
that was issued for this one.
|
||||
"""
|
||||
|
||||
output = (session.container or {}).get("output")
|
||||
if output:
|
||||
return str(output)
|
||||
raise ManagerError(
|
||||
"stream_unavailable",
|
||||
f"session {session.id} has no container output to publish",
|
||||
hint="a stream never falls back to the main output -- that one "
|
||||
"carries every other session. `container.reconcile` once the "
|
||||
"compositor is reachable, or start the session with containers on",
|
||||
id=session.id,
|
||||
container=session.container,
|
||||
)
|
||||
|
||||
def _mint_phrase(self) -> str:
|
||||
"""A fresh phrase.
|
||||
|
||||
From `hhstream_live.phrase`, which owns the wordlist, the shape and the
|
||||
validator -- one definition, so a phrase the broker mints is one the
|
||||
daemon will accept and a `--phrase` an operator types is held to the
|
||||
same bar. Imported here rather than at module scope because this is the
|
||||
only path that needs it and `hhstreamd` must stay importable without
|
||||
the web app's wordlist being readable.
|
||||
"""
|
||||
|
||||
from hhstream_live import phrase as phrase_mod
|
||||
|
||||
return phrase_mod.generate()
|
||||
|
||||
def _checked_phrase(self, phrase: Any) -> str | None:
|
||||
if phrase is None:
|
||||
return None
|
||||
from hhstream_live import phrase as phrase_mod
|
||||
|
||||
if not isinstance(phrase, str):
|
||||
raise ManagerError(
|
||||
"invalid_argument", "phrase must be a string", id=None
|
||||
)
|
||||
try:
|
||||
return phrase_mod.validate(phrase)
|
||||
except ValueError:
|
||||
# The validator's own message names the value it refused, which is
|
||||
# right for an operator reading their own terminal and wrong here:
|
||||
# this reason reaches the broker's log and the audit trail, and the
|
||||
# value is a credential (CONTRACT-sessions.md §3.5). So the shape
|
||||
# is described and the phrase is NOT interpolated -- deliberately,
|
||||
# and `from None` so the chained message cannot carry it either.
|
||||
raise ManagerError(
|
||||
"invalid_argument",
|
||||
"the phrase given is not of the expected shape",
|
||||
hint="four words of at least three letters and a five-character "
|
||||
"tail, e.g. amber-otter-lantern-harbor-7k2qp; omit it to have "
|
||||
"one minted",
|
||||
) from None
|
||||
|
||||
def _checked_fps(self, fps: Any) -> int | None:
|
||||
if fps is None:
|
||||
return None
|
||||
if isinstance(fps, bool) or not isinstance(fps, int):
|
||||
raise ManagerError(
|
||||
"invalid_argument", f"fps must be an int, got {type(fps).__name__}"
|
||||
)
|
||||
if fps <= 0:
|
||||
raise ManagerError("invalid_argument", f"fps must be positive, got {fps}")
|
||||
# The ceiling is deliberately NOT checked here. It belongs to the
|
||||
# daemon (`hhstream_live.publisher.FPS_CAP`), which is the process that
|
||||
# has to keep up with it, and a second copy of the number here would be
|
||||
# a second thing to raise when the box gets faster.
|
||||
return fps
|
||||
|
||||
async def _attach_stream(
|
||||
self, session: Session, *, phrase: str, output: str, fps: int | None
|
||||
) -> Attachment:
|
||||
live = self._live_streams()
|
||||
if live is None:
|
||||
raise ManagerError(
|
||||
"stream_unavailable",
|
||||
"no stream daemon is configured for this broker",
|
||||
hint="the `hhstream-live` unit is what captures a stream; "
|
||||
"`sessions.stream` in the module turns it on",
|
||||
id=session.id,
|
||||
)
|
||||
try:
|
||||
return await asyncio.to_thread(
|
||||
live.attach,
|
||||
phrase=phrase,
|
||||
output=output,
|
||||
fps=fps,
|
||||
session=session.id,
|
||||
label=session.app,
|
||||
)
|
||||
except LiveRejected as exc:
|
||||
# The daemon's own vocabulary, mapped once: its `invalid_argument`
|
||||
# is the caller's mistake (exit 2) and anything else is a stream
|
||||
# that could not be opened (exit 10). The same split the driver's
|
||||
# `kind` already gets.
|
||||
error = "invalid_argument" if exc.kind == "invalid_argument" else "stream_unavailable"
|
||||
raise ManagerError(error, str(exc), id=session.id) from exc
|
||||
except LiveUnavailable as exc:
|
||||
raise ManagerError(
|
||||
"stream_unavailable",
|
||||
f"the stream daemon could not be reached: {exc}",
|
||||
hint="is hhstream-live running? the session itself is unaffected",
|
||||
id=session.id,
|
||||
) from exc
|
||||
|
||||
async def _detach_stream(self, session: Session) -> bool:
|
||||
"""Stop the capture for this session, if there is one.
|
||||
|
||||
Never raises. Called from `disable`, which has a record to clear
|
||||
regardless, and from teardown, where a daemon that cannot be reached
|
||||
must not stop a session from being killed.
|
||||
"""
|
||||
|
||||
phrase = (session.stream or {}).get("phrase")
|
||||
live = self._live_streams()
|
||||
if not phrase or live is None:
|
||||
return False
|
||||
try:
|
||||
return await asyncio.to_thread(live.detach, str(phrase))
|
||||
except (LiveRejected, LiveUnavailable) as exc:
|
||||
log.warning(
|
||||
"could not detach %s's stream on output %s: %s",
|
||||
session.id,
|
||||
(session.stream or {}).get("output"),
|
||||
exc,
|
||||
)
|
||||
return False
|
||||
|
||||
def _attachments(self) -> tuple[dict[str, Attachment], bool]:
|
||||
"""The daemon's streams by phrase, and whether it answered.
|
||||
|
||||
Synchronous and tolerant: the read verbs report what they can, and a
|
||||
down daemon turns `attached` false rather than failing a `list` that
|
||||
has records to show.
|
||||
"""
|
||||
|
||||
live = self._live_streams()
|
||||
if live is None:
|
||||
return {}, False
|
||||
try:
|
||||
return {a.phrase: a for a in live.list()}, True
|
||||
except (LiveRejected, LiveUnavailable) as exc:
|
||||
log.debug("the stream daemon did not answer `list`: %s", exc)
|
||||
return {}, False
|
||||
|
||||
@staticmethod
|
||||
def _stream_public(
|
||||
stored: dict[str, Any], attachment: Attachment | None
|
||||
) -> dict[str, Any]:
|
||||
"""The record, with the daemon's live view merged in.
|
||||
|
||||
``attached`` is its own field and is **not** folded into ``enabled``: a
|
||||
record may say a session is enabled while the daemon is down, and "the
|
||||
operator asked for this" and "a capture is running right now" are two
|
||||
different facts. ``url`` and ``viewers`` are *absent* when it is false,
|
||||
rather than stale -- a URL that no longer serves anything is worse than
|
||||
no URL.
|
||||
"""
|
||||
|
||||
public = dict(stored)
|
||||
public["attached"] = attachment is not None
|
||||
if attachment is not None:
|
||||
public["url"] = attachment.url
|
||||
public["viewers"] = attachment.viewers
|
||||
public["fps"] = attachment.fps
|
||||
return public
|
||||
|
||||
async def _sweep_streams(self) -> None:
|
||||
"""Stamp `touch` on every session somebody is watching.
|
||||
|
||||
The one exception to "`touch` is the only mark of activity"
|
||||
(CONTRACT-sessions.md §4), and the only thing in this daemon that
|
||||
treats an observation as an intention. It exists for one failure: an
|
||||
operator watching a long job on his phone, saying nothing to the
|
||||
broker, and losing the session at three hours *because* watching was
|
||||
all he was doing.
|
||||
|
||||
It cannot hold a session open by itself. An enabled stream with no
|
||||
viewer runs no `grim` and stamps nothing, so a forgotten `enable` is
|
||||
not a leak -- which is why this is safe to run unconditionally.
|
||||
"""
|
||||
|
||||
while True:
|
||||
await asyncio.sleep(self.config.stream_sweep_s)
|
||||
try:
|
||||
await self._touch_watched()
|
||||
except asyncio.CancelledError:
|
||||
raise
|
||||
except Exception: # noqa: BLE001 -- a sweep must outlive one failure
|
||||
log.exception("the stream viewer sweep failed; continuing")
|
||||
|
||||
async def _touch_watched(self) -> list[str]:
|
||||
"""One pass of the sweep. Returns the ids it touched."""
|
||||
|
||||
live = self._live_streams()
|
||||
if live is None:
|
||||
return []
|
||||
try:
|
||||
counts = await asyncio.to_thread(live.viewers)
|
||||
except (LiveRejected, LiveUnavailable) as exc:
|
||||
log.debug("the stream daemon did not answer `viewers`: %s", exc)
|
||||
return []
|
||||
touched: list[str] = []
|
||||
for session in self.registry.live():
|
||||
phrase = (session.stream or {}).get("phrase")
|
||||
if not phrase:
|
||||
continue
|
||||
viewers = counts.get(str(phrase), 0)
|
||||
if viewers <= 0:
|
||||
continue
|
||||
self.registry.touch(session, force_flush=True)
|
||||
touched.append(session.id)
|
||||
self.audit.emit(
|
||||
"stream_viewer_activity",
|
||||
id=session.id,
|
||||
output=(session.stream or {}).get("output"),
|
||||
viewers=viewers,
|
||||
)
|
||||
return touched
|
||||
|
||||
async def _sweep_pointer(self) -> None:
|
||||
"""Expire a stale lease even when nobody asks.
|
||||
|
||||
@@ -2152,6 +2600,22 @@ class SessionManager:
|
||||
self.driver = PointerDriver(self.config.pointer_socket)
|
||||
return self.driver
|
||||
|
||||
# -- the stream daemon ------------------------------------------------
|
||||
|
||||
def _live_streams(self) -> LiveStreams | None:
|
||||
"""The stream daemon's client, built on first use.
|
||||
|
||||
``None`` rather than raising, unlike :meth:`_pointer_driver`, and the
|
||||
asymmetry is the point: a pointer verb with no driver is a verb that
|
||||
cannot do its job, while a *read* of stream state with no daemon has a
|
||||
true answer -- the records, with ``attached: false``. The write paths
|
||||
(`_attach_stream`) raise `stream_unavailable` for themselves.
|
||||
"""
|
||||
|
||||
if self.live is None and self.config.live_socket is not None:
|
||||
self.live = LiveStreams(self.config.live_socket)
|
||||
return self.live
|
||||
|
||||
async def _drive(self, verb: str, *args: Any) -> Any:
|
||||
"""One driver call, off the event loop.
|
||||
|
||||
|
||||
@@ -102,8 +102,17 @@ EXIT_CODE_FOR_ERROR: dict[str, ExitCode] = {
|
||||
"pointer_busy": ExitCode.BUSY,
|
||||
# 9 — the lease is required and not held
|
||||
"no_lease": ExitCode.NO_LEASE,
|
||||
# 8 — a phrase that is not this session's (v4)
|
||||
"stream_busy": ExitCode.BUSY,
|
||||
# 6 — the stream daemon's own cap (v4)
|
||||
"stream_budget": ExitCode.POLICY,
|
||||
# 10 — the compositor side failed; the session itself is fine
|
||||
"compositor": ExitCode.COMPOSITOR,
|
||||
# The stream could not be reached or has no output to aim at (v4). Exit 10
|
||||
# for the reason `driver_refused` is: the *session* keeps running, and a
|
||||
# caller that treated an unreachable stream as a dead session would kill an
|
||||
# application over a web page.
|
||||
"stream_unavailable": ExitCode.COMPOSITOR,
|
||||
"compositor_unavailable": ExitCode.COMPOSITOR,
|
||||
"no_container": ExitCode.COMPOSITOR,
|
||||
"driver_unavailable": ExitCode.COMPOSITOR,
|
||||
@@ -156,6 +165,12 @@ VERBS = (
|
||||
# warp retargets the keys. So there is no `keyboard.acquire`.
|
||||
"keyboard.key",
|
||||
"keyboard.type",
|
||||
# v4: the per-session live stream. `list` and `status` read; `enable` and
|
||||
# `disable` are in the mutation set below.
|
||||
"stream.enable",
|
||||
"stream.disable",
|
||||
"stream.list",
|
||||
"stream.status",
|
||||
)
|
||||
|
||||
#: Verbs whose reply is remembered by ``request_id``, so a caller that died
|
||||
@@ -185,6 +200,12 @@ MUTATING_VERBS = frozenset(
|
||||
# nothing, and a cached one would be a stale one.
|
||||
"keyboard.key",
|
||||
"keyboard.type",
|
||||
# v4. `enable` mints or rotates a phrase: a retry that minted a second
|
||||
# one would invalidate the URL somebody is already holding, and
|
||||
# `disable` is here for symmetry -- a retried disable after a daemon
|
||||
# restart must report what the first one did.
|
||||
"stream.enable",
|
||||
"stream.disable",
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
@@ -23,11 +23,12 @@ from .clock import Clock, iso
|
||||
log = logging.getLogger("hhstreamd.registry")
|
||||
|
||||
#: 3 adds the container, the pointer bookmark and the compositor signature
|
||||
#: (PLAN §7). The number is read, never written by anyone but this module: a
|
||||
#: record carrying an older one is **migrated on load** (:func:`migrate`), not
|
||||
#: refused, because the processes it describes are still running and refusing
|
||||
#: the record would strand them.
|
||||
SCHEMA = 3
|
||||
#: (PLAN §7); 4 adds the live stream (CONTRACT-sessions.md §6, v4). The number
|
||||
#: is read, never written by anyone but this module: a record carrying an older
|
||||
#: one is **migrated on load** (:func:`migrate`), not refused, because the
|
||||
#: processes it describes are still running and refusing the record would
|
||||
#: strand them.
|
||||
SCHEMA = 4
|
||||
|
||||
#: Tombstones survive this long so a ``status`` after an unexplained failure
|
||||
#: still answers the question. ``gc`` prunes them.
|
||||
@@ -138,6 +139,17 @@ class Session:
|
||||
#: ``{bookmark, last_released_at, released_by}``. Absent (``None``) means
|
||||
#: the pointer was never aimed here — not that its position is unknown.
|
||||
pointer: dict[str, Any] | None = None
|
||||
#: The live stream, or ``None`` for a session nobody switched one on for
|
||||
#: (CONTRACT-sessions.md §4). ``{enabled, phrase, output, fps, port,
|
||||
#: enabled_at}``; the daemon's ``url`` and ``viewers`` are merged in by the
|
||||
#: manager when it could be asked, and are deliberately not stored -- a
|
||||
#: viewer count on disk is a number that is wrong the moment it is written.
|
||||
#:
|
||||
#: The phrase lives here because it has to survive a broker restart and a
|
||||
#: re-enable: it is the stream's only credential, and an operator who read
|
||||
#: four words out to somebody must not have them change underneath him
|
||||
#: because the daemon bounced.
|
||||
stream: dict[str, Any] | None = None
|
||||
#: ``HYPRLAND_INSTANCE_SIGNATURE`` of the compositor this session's
|
||||
#: container lives in, so a restarted broker re-attaches to the same
|
||||
#: instance instead of picking whichever one is there now.
|
||||
@@ -234,6 +246,38 @@ def container_record(
|
||||
}
|
||||
|
||||
|
||||
def stream_record(
|
||||
*,
|
||||
phrase: str,
|
||||
output: str,
|
||||
fps: int,
|
||||
enabled_at: str,
|
||||
) -> dict[str, Any]:
|
||||
"""One ``stream`` sub-record (CONTRACT-sessions.md §4).
|
||||
|
||||
Only what survives a restart. The daemon's ``url`` and ``viewers`` are
|
||||
merged in by the manager when it could be asked and are deliberately absent
|
||||
here: a viewer count on disk is wrong the moment it is written, and a URL
|
||||
assembled from a remembered port is a URL that lies the first time the
|
||||
listener moves.
|
||||
|
||||
``enabled`` is always ``True`` in a stored record. A session that was
|
||||
never enabled has ``stream: None``, and `disable` clears the field rather
|
||||
than setting ``enabled: False`` -- "nobody asked for a stream here" and
|
||||
"somebody asked and then stopped" are the same state as far as anything
|
||||
downstream is concerned, and two spellings for one state is how a
|
||||
`if stream:` check starts being wrong.
|
||||
"""
|
||||
|
||||
return {
|
||||
"enabled": True,
|
||||
"phrase": phrase,
|
||||
"output": output,
|
||||
"fps": fps,
|
||||
"enabled_at": enabled_at,
|
||||
}
|
||||
|
||||
|
||||
def pointer_record(
|
||||
*,
|
||||
bookmark: dict[str, Any] | None,
|
||||
@@ -284,7 +328,14 @@ def migrate(data: dict[str, Any]) -> dict[str, Any]:
|
||||
upgraded = dict(data)
|
||||
# Only ever *adds* keys. A v2 record that somehow carries a container must
|
||||
# keep it: the field is new to the schema, not new to the session.
|
||||
for key in ("container", "pointer", "signature"):
|
||||
#
|
||||
# `stream` (schema 4) is `None` for the same reason the others are: a
|
||||
# session written by a daemon that knew nothing of streams had no stream,
|
||||
# and "no stream" is a defined value rather than a guess. It must NOT be
|
||||
# invented as `{"enabled": false}` either -- a record that says it was
|
||||
# asked about and declined is a different claim from one that was never
|
||||
# asked.
|
||||
for key in ("container", "pointer", "signature", "stream"):
|
||||
upgraded.setdefault(key, None)
|
||||
upgraded["schema"] = SCHEMA
|
||||
log.info("migrated record %s from schema %s to %s", data.get("id"), schema, SCHEMA)
|
||||
|
||||
@@ -75,6 +75,10 @@ class ControlServer:
|
||||
"pointer.state": self._op_pointer_state,
|
||||
"keyboard.key": self._op_keyboard_key,
|
||||
"keyboard.type": self._op_keyboard_type,
|
||||
"stream.enable": self._op_stream_enable,
|
||||
"stream.disable": self._op_stream_disable,
|
||||
"stream.list": self._op_stream_list,
|
||||
"stream.status": self._op_stream_status,
|
||||
}
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
@@ -264,6 +268,9 @@ class ControlServer:
|
||||
wait_ready_s=request.get("wait_ready_s"),
|
||||
home=request.get("home"),
|
||||
ephemeral_home=bool(request.get("ephemeral_home", False)),
|
||||
stream=bool(request.get("stream", False)),
|
||||
stream_phrase=request.get("stream_phrase"),
|
||||
stream_fps=request.get("stream_fps"),
|
||||
)
|
||||
return protocol.ok(id=record["id"], state=record["state"], session=record)
|
||||
|
||||
@@ -297,6 +304,32 @@ class ControlServer:
|
||||
)
|
||||
return protocol.ok(id=record["id"], state=record["state"], session=record)
|
||||
|
||||
async def _op_stream_enable(
|
||||
self, request: dict[str, Any], caller: dict[str, Any]
|
||||
) -> dict[str, Any]:
|
||||
return protocol.ok(
|
||||
**await self.manager.stream_enable(
|
||||
request.get("id"),
|
||||
phrase=request.get("phrase"),
|
||||
fps=request.get("fps"),
|
||||
)
|
||||
)
|
||||
|
||||
async def _op_stream_disable(
|
||||
self, request: dict[str, Any], caller: dict[str, Any]
|
||||
) -> dict[str, Any]:
|
||||
return protocol.ok(**await self.manager.stream_disable(request.get("id")))
|
||||
|
||||
async def _op_stream_list(
|
||||
self, request: dict[str, Any], caller: dict[str, Any]
|
||||
) -> dict[str, Any]:
|
||||
return protocol.ok(**self.manager.stream_list())
|
||||
|
||||
async def _op_stream_status(
|
||||
self, request: dict[str, Any], caller: dict[str, Any]
|
||||
) -> dict[str, Any]:
|
||||
return protocol.ok(**self.manager.stream_status(request.get("id")))
|
||||
|
||||
async def _op_container_list(
|
||||
self, request: dict[str, Any], caller: dict[str, Any]
|
||||
) -> dict[str, Any]:
|
||||
|
||||
@@ -25,11 +25,19 @@ PHRASE = "amber-otter-lantern-harbor-7k2qp"
|
||||
|
||||
|
||||
class StubCapture:
|
||||
"""A `Capture` under the test's control: counts grabs, can be told to fail."""
|
||||
"""A `Capture` under the test's control: counts grabs, can be told to fail.
|
||||
|
||||
def __init__(self, frames=None, fail_first: int = 0, delay: float = 0.0):
|
||||
`fail_first` is a capture that is broken from the start (a cold start that
|
||||
never works); `fail_after` is one that works and then stops -- the output
|
||||
was removed while someone was watching, which is grim's "unknown output" on
|
||||
every grab from then on.
|
||||
"""
|
||||
|
||||
def __init__(self, frames=None, fail_first: int = 0, delay: float = 0.0,
|
||||
fail_after: int | None = None):
|
||||
self.frames = list(frames) if frames else [jpeg_bytes(i) for i in range(1, 50)]
|
||||
self.fail_first = fail_first
|
||||
self.fail_after = fail_after
|
||||
self.delay = delay
|
||||
self.calls = 0
|
||||
self._lock = threading.Lock()
|
||||
@@ -42,6 +50,8 @@ class StubCapture:
|
||||
time.sleep(self.delay)
|
||||
if call <= self.fail_first:
|
||||
raise RuntimeError(f"stub capture failing on purpose (call {call})")
|
||||
if self.fail_after is not None and call > self.fail_after:
|
||||
raise RuntimeError(f"stub capture: unknown output (call {call})")
|
||||
return self.frames[(call - 1 - self.fail_first) % len(self.frames)]
|
||||
|
||||
|
||||
|
||||
@@ -3,10 +3,22 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import io
|
||||
import os
|
||||
import pathlib
|
||||
import re
|
||||
import signal
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
from contextlib import redirect_stdout
|
||||
|
||||
import pytest
|
||||
from hhstream_live.__main__ import DEFAULT_CAPTURE, capture_argv, main, parse_stream
|
||||
from hhstream_live.__main__ import (DEFAULT_CAPTURE, capture_argv, main, parse_args,
|
||||
parse_stream)
|
||||
|
||||
#: What `hhstream-live phrase` must print: four alphabetic words and a tail.
|
||||
PHRASE_SHAPE = re.compile(r"^[a-z]+(?:-[a-z]+){3}-[a-z0-9]{5}$")
|
||||
_SRC = pathlib.Path(__file__).resolve().parents[2] / "src"
|
||||
|
||||
|
||||
def test_capture_command_is_aimed_by_inserting_the_output_before_stdout():
|
||||
@@ -40,7 +52,9 @@ def test_the_phrase_subcommand_prints_a_phrase():
|
||||
with redirect_stdout(out):
|
||||
assert main(["phrase"]) == 0
|
||||
printed = out.getvalue().strip()
|
||||
assert printed.count("-") == 4 # four words + tail
|
||||
# Not just `count("-") == 4`: a hyphenated word on the list would satisfy
|
||||
# the count with five words and four hyphens in the wrong places.
|
||||
assert PHRASE_SHAPE.match(printed), printed
|
||||
|
||||
|
||||
def test_the_phrase_subcommand_can_print_several():
|
||||
@@ -48,3 +62,64 @@ def test_the_phrase_subcommand_can_print_several():
|
||||
with redirect_stdout(out):
|
||||
main(["phrase", "--count", "3"])
|
||||
assert len(out.getvalue().split()) == 3
|
||||
|
||||
|
||||
# ---- the default subcommand, and shutdown ----------------------------------
|
||||
|
||||
def test_a_bare_command_line_means_serve():
|
||||
"""`hhstream-live` with no subcommand is `hhstream-live serve`.
|
||||
|
||||
The serve options live on the `serve` subparser, so the namespace has to be
|
||||
the subparser's; reading `capture_command` off the top-level one is the
|
||||
`AttributeError` this guards.
|
||||
"""
|
||||
args = parse_args([])
|
||||
assert args.command == "serve"
|
||||
assert args.capture_command is None
|
||||
assert args.port and args.bind and args.stream == []
|
||||
assert args.log_level == "info"
|
||||
|
||||
|
||||
def test_serve_options_work_without_naming_the_subcommand():
|
||||
args = parse_args(["--port", "0", "--bind", "0.0.0.0"])
|
||||
assert (args.command, args.port, args.bind) == ("serve", 0, "0.0.0.0")
|
||||
|
||||
|
||||
def test_a_global_option_survives_the_subcommand():
|
||||
"""`--log-level` is on both parsers; the subparser must not reset it."""
|
||||
assert parse_args(["--log-level", "debug"]).log_level == "debug"
|
||||
assert parse_args(["--log-level", "debug", "serve"]).log_level == "debug"
|
||||
assert parse_args(["--log-level", "debug", "phrase"]).log_level == "debug"
|
||||
|
||||
|
||||
def test_a_bare_run_serves_and_sigterm_stops_it_cleanly():
|
||||
"""The whole path: no subcommand, then the signal a service is stopped with.
|
||||
|
||||
`SIGTERM`'s default action kills the process outright, so without a handler
|
||||
`server.stop()` never runs and the exit status is a signal, not a 0.
|
||||
"""
|
||||
env = dict(os.environ, PYTHONPATH=os.pathsep.join(
|
||||
[str(_SRC), os.environ.get("PYTHONPATH", "")]).rstrip(os.pathsep))
|
||||
proc = subprocess.Popen(
|
||||
[sys.executable, "-m", "hhstream_live", "--port", "0"],
|
||||
stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, env=env,
|
||||
)
|
||||
try:
|
||||
deadline = time.monotonic() + 20
|
||||
banner = ""
|
||||
while "landing page:" not in banner and time.monotonic() < deadline:
|
||||
line = proc.stderr.readline()
|
||||
if not line:
|
||||
break
|
||||
banner += line
|
||||
assert "landing page:" in banner, banner
|
||||
assert "bound to 127.0.0.1:" in banner, banner
|
||||
|
||||
proc.send_signal(signal.SIGTERM)
|
||||
out, err = proc.communicate(timeout=20)
|
||||
except BaseException:
|
||||
proc.kill()
|
||||
proc.communicate()
|
||||
raise
|
||||
assert proc.returncode == 0, (proc.returncode, banner, err)
|
||||
assert "Traceback" not in err, err
|
||||
@@ -8,6 +8,7 @@ import pytest
|
||||
from hhstream_live import phrase
|
||||
|
||||
SHAPE = re.compile(r"^[a-z]+(-[a-z]+){3}-[a-z0-9]{5}$")
|
||||
WORD = re.compile(r"^[a-z]+$")
|
||||
|
||||
|
||||
def test_generated_phrase_has_the_agreed_shape():
|
||||
@@ -24,11 +25,24 @@ def test_entropy_is_what_the_plan_claims():
|
||||
assert phrase.entropy_bits() > 75
|
||||
|
||||
|
||||
def test_wordlist_is_the_eff_large_list():
|
||||
def test_wordlist_is_the_eff_large_list_minus_its_hyphenated_entries():
|
||||
words = phrase.words()
|
||||
assert len(words) == 7776
|
||||
assert len(set(words)) == 7776
|
||||
# The file is the EFF large list, 7776 lines; four of them are hyphenated
|
||||
# and the loader drops them, because a hyphen is the phrase's separator.
|
||||
assert len(words) == 7772
|
||||
assert len(set(words)) == 7772
|
||||
assert "abacus" in words
|
||||
assert "drop-down" not in words
|
||||
|
||||
|
||||
def test_every_loaded_word_is_plain_lowercase_letters():
|
||||
"""Not a sampling test: one hyphenated word makes a six-token phrase.
|
||||
|
||||
`test_generated_phrase_has_the_agreed_shape` would only catch that by luck
|
||||
-- four draws out of 7776 hit a hyphenated entry about 0.2% of the time --
|
||||
so the property is asserted over the whole list instead.
|
||||
"""
|
||||
assert all(WORD.match(word) for word in phrase.words())
|
||||
|
||||
|
||||
def test_generate_is_not_reproducible_from_a_seed():
|
||||
@@ -47,7 +61,15 @@ def test_normalize_lowercases_and_trims():
|
||||
|
||||
|
||||
def test_validate_accepts_a_good_phrase_and_returns_the_normalized_form():
|
||||
assert phrase.validate("Amber-Otter-Lantern-7K2QP") == "amber-otter-lantern-7k2qp"
|
||||
assert phrase.validate("Amber-Otter-Lantern-Harbor-7K2QP") == (
|
||||
"amber-otter-lantern-harbor-7k2qp"
|
||||
)
|
||||
|
||||
|
||||
def test_validate_accepts_everything_generate_produces():
|
||||
for _ in range(50):
|
||||
generated = phrase.generate()
|
||||
assert phrase.validate(generated) == generated
|
||||
|
||||
|
||||
@pytest.mark.parametrize("bad", ["", "single", "two-tokens", "has space-phrase-x",
|
||||
@@ -58,6 +80,26 @@ def test_validate_rejects_a_phrase_that_is_not_the_shape(bad):
|
||||
phrase.validate(bad)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("weak", [
|
||||
"a-b-c", # the reviewer's example: three letters
|
||||
"ab-cd-ef-gh-12345", # four "words" of two letters
|
||||
"amber-otter-lantern-7k2qp", # three words, not four
|
||||
"amber-otter-lantern-harbor", # four words, no tail
|
||||
"amber-otter-lantern-harbor-7k2", # a three-character tail
|
||||
"amber-otter-lantern-harbor-7k2qpz", # a six-character tail
|
||||
"amber-otter-lantern-harbor-hill-7k2qp", # five words
|
||||
"amber-0tter-lantern-harbor-7k2qp", # a digit inside a word
|
||||
])
|
||||
def test_validate_rejects_a_phrase_weaker_than_the_generated_shape(weak):
|
||||
"""`--phrase` is a password for a LAN-facing stream, not a label.
|
||||
|
||||
Anything `validate` accepts is something an operator can set, so the floor
|
||||
has to be the shape `generate` produces -- otherwise `a-b-c` opens a stream.
|
||||
"""
|
||||
with pytest.raises(ValueError):
|
||||
phrase.validate(weak)
|
||||
|
||||
|
||||
def test_validate_rejects_an_overlong_phrase():
|
||||
with pytest.raises(ValueError):
|
||||
phrase.validate("-".join(["averyverylongword"] * 8))
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import time
|
||||
|
||||
import pytest
|
||||
@@ -94,6 +95,64 @@ def test_a_dead_capture_gives_up_and_closes_viewers():
|
||||
stream.stop()
|
||||
|
||||
|
||||
def test_a_capture_that_dies_after_a_good_frame_also_gives_up():
|
||||
"""The cap counts failures *in a row*, not failures before the first frame.
|
||||
|
||||
An output removed while someone is watching fails every grab from then on.
|
||||
A give-up rule that only applied to a cold start would leave this stream
|
||||
retrying twice a second for as long as the viewer held the page open --
|
||||
exactly the busy loop on a dead session the cap exists to stop.
|
||||
"""
|
||||
capture = StubCapture(fail_after=1) # one good frame, then the output is gone
|
||||
stream = make_stream(capture, fps=10)
|
||||
stream.start()
|
||||
try:
|
||||
stream.add_viewer() # and the viewer stays attached for the whole test
|
||||
frame, seq = stream.wait_frame(0, timeout=5)
|
||||
assert frame is not None and seq >= 1
|
||||
|
||||
# Poll through the viewer's own wait, so a `wait_frame` that hangs is a
|
||||
# failure here rather than a test that quietly waits for the deadline.
|
||||
deadline = time.monotonic() + 15
|
||||
while not stream.stopped and time.monotonic() < deadline:
|
||||
assert stream.wait_frame(seq, timeout=1.0) == (None, seq)
|
||||
assert stream.stopped, "a dead output must stop the stream, frame or no frame"
|
||||
|
||||
# And the viewer in the loop is released at once rather than on timeout.
|
||||
started = time.monotonic()
|
||||
assert stream.wait_frame(seq, timeout=10.0) == (None, seq)
|
||||
assert time.monotonic() - started < 1.0
|
||||
assert capture.calls >= FAILURE_LIMIT
|
||||
finally:
|
||||
stream.stop()
|
||||
|
||||
|
||||
def test_giving_up_never_writes_the_phrase_to_the_log(caplog):
|
||||
"""A log line is the easiest place for the stream's one credential to leak.
|
||||
|
||||
faulthandler and `threading.excepthook` print thread names, so the capture
|
||||
thread is checked here too.
|
||||
"""
|
||||
capture = StubCapture(fail_first=10_000)
|
||||
stream = make_stream(capture, fps=10)
|
||||
with caplog.at_level(logging.DEBUG, logger="hhstream.live"):
|
||||
stream.start()
|
||||
thread_name = stream._thread.name
|
||||
try:
|
||||
stream.add_viewer()
|
||||
assert stream.wait_frame(0, timeout=15) == (None, 0)
|
||||
assert stream.stopped
|
||||
finally:
|
||||
stream.stop()
|
||||
|
||||
messages = [record.getMessage() for record in caplog.records]
|
||||
assert messages, "the give-up must be logged at all"
|
||||
assert any("hh-demo" in message for message in messages)
|
||||
for message in messages:
|
||||
assert PHRASE not in message, message
|
||||
assert PHRASE not in thread_name and "hh-demo" in thread_name
|
||||
|
||||
|
||||
# ---- registry --------------------------------------------------------------
|
||||
|
||||
def test_registry_adds_and_finds_a_phrase_case_insensitively():
|
||||
|
||||
@@ -2,11 +2,13 @@
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import socket
|
||||
import threading
|
||||
import time
|
||||
|
||||
from live_helpers import PHRASE, StubCapture, read_parts
|
||||
from hhstream_live.server import BOUNDARY
|
||||
from hhstream_live.server import BOUNDARY, HEADER_TIMEOUT_S, LiveServer, RateLimiter
|
||||
|
||||
WRONG = "no-such-phrase-here-00000"
|
||||
|
||||
@@ -94,6 +96,10 @@ def test_stream_is_mjpeg_and_delivers_valid_jpeg_parts(serve, http_conn):
|
||||
assert resp.getheader("Content-Type") == (
|
||||
f"multipart/x-mixed-replace; boundary={BOUNDARY}"
|
||||
)
|
||||
# The stream has no length and is not chunked, so the only thing that
|
||||
# can delimit it is the close -- which an intermediary is only entitled
|
||||
# to expect if the response says so.
|
||||
assert resp.getheader("Connection") == "close"
|
||||
parts = read_parts(resp, 2)
|
||||
assert len(parts) == 2
|
||||
for part in parts:
|
||||
@@ -150,6 +156,104 @@ def test_no_capture_until_a_request_arrives(serve):
|
||||
assert capture.calls >= 1
|
||||
|
||||
|
||||
def test_a_silent_client_does_not_pin_a_handler_thread(serve):
|
||||
"""A connection that never sends a request line must not hold a thread.
|
||||
|
||||
The socket timeout is the only thing that ends it; without one the handler
|
||||
sits in `readline` for the life of the process.
|
||||
"""
|
||||
assert HEADER_TIMEOUT_S <= 30 # a cap that never fires is not a cap
|
||||
|
||||
with serve() as (server, _):
|
||||
before = threading.active_count()
|
||||
sock = socket.create_connection(("127.0.0.1", server.port), timeout=5)
|
||||
try:
|
||||
time.sleep(0.2)
|
||||
assert threading.active_count() > before # a handler is waiting on us
|
||||
sock.settimeout(HEADER_TIMEOUT_S + 10)
|
||||
started = time.monotonic()
|
||||
# The server closes on timeout, which arrives here as EOF.
|
||||
assert sock.recv(4096) == b""
|
||||
waited = time.monotonic() - started
|
||||
assert waited <= HEADER_TIMEOUT_S + 5, waited
|
||||
finally:
|
||||
sock.close()
|
||||
|
||||
|
||||
def test_a_viewer_that_drops_mid_stream_releases_its_slot(serve, http_conn):
|
||||
"""A dropped viewer must bring `viewers` back to 0, or grim keeps running."""
|
||||
import json
|
||||
|
||||
with serve(fps=10) as (server, _):
|
||||
sock = socket.create_connection(("127.0.0.1", server.port), timeout=10)
|
||||
sock.sendall(f"GET /{PHRASE}/stream.mjpg HTTP/1.1\r\n"
|
||||
f"Host: 127.0.0.1\r\n\r\n".encode("ascii"))
|
||||
assert sock.recv(4096) # headers, and at least the start of a part
|
||||
|
||||
def viewers() -> int:
|
||||
return json.loads(get(http_conn(server), f"/{PHRASE}/status.json")[2])["viewers"]
|
||||
|
||||
# The headers can reach us a moment before the handler counts itself in.
|
||||
deadline = time.monotonic() + 10
|
||||
while viewers() == 0 and time.monotonic() < deadline:
|
||||
time.sleep(0.05)
|
||||
assert viewers() == 1
|
||||
|
||||
sock.close() # the phone walked out of range
|
||||
|
||||
deadline = time.monotonic() + 10
|
||||
while viewers() and time.monotonic() < deadline:
|
||||
time.sleep(0.1)
|
||||
assert viewers() == 0
|
||||
|
||||
|
||||
def test_the_access_log_never_carries_the_phrase(serve, http_conn, caplog):
|
||||
"""Debug logging is on in development, and the request line is the phrase."""
|
||||
with caplog.at_level(logging.DEBUG, logger="hhstream.live"):
|
||||
with serve() as (server, _):
|
||||
assert get(http_conn(server), f"/{PHRASE}/status.json")[0] == 200
|
||||
assert get(http_conn(server), f"/{WRONG}/")[0] == 404
|
||||
|
||||
messages = [record.getMessage() for record in caplog.records]
|
||||
assert messages, "something must be logged, or this proves nothing"
|
||||
for message in messages:
|
||||
assert PHRASE not in message, message
|
||||
assert WRONG not in message, message
|
||||
|
||||
|
||||
def test_the_server_says_when_it_is_bound_to_every_interface(registry):
|
||||
"""`url_for` must print something dialable; the bind line tells the truth."""
|
||||
loopback = LiveServer(registry, host="127.0.0.1", port=9988)
|
||||
assert loopback.describe_bind() == "bound to 127.0.0.1:9988"
|
||||
assert not loopback.binds_everywhere
|
||||
|
||||
everywhere = LiveServer(registry, host="0.0.0.0", port=9988)
|
||||
assert everywhere.binds_everywhere
|
||||
assert everywhere.address == "127.0.0.1" # still dialable
|
||||
described = everywhere.describe_bind()
|
||||
assert "0.0.0.0:9988" in described and "all interfaces" in described
|
||||
|
||||
|
||||
def test_the_rate_limiter_counts_each_client_separately_and_forgets_them():
|
||||
"""One noisy client must not spend another's budget, and must not be kept.
|
||||
|
||||
`_hits` is keyed by client address, so a table that only grew would be a
|
||||
memory leak any LAN host could drive.
|
||||
"""
|
||||
now = [0.0]
|
||||
limiter = RateLimiter(limit=2, window=60.0, clock=lambda: now[0])
|
||||
|
||||
assert limiter.allow("10.0.0.1")
|
||||
assert limiter.allow("10.0.0.1")
|
||||
assert not limiter.allow("10.0.0.1") # that client is out of budget
|
||||
assert limiter.allow("10.0.0.2") # this one is not
|
||||
assert limiter.tracked == 2
|
||||
|
||||
now[0] += 61.0 # both windows have passed
|
||||
assert limiter.allow("10.0.0.1")
|
||||
assert limiter.tracked == 1, "a client that went quiet is not kept"
|
||||
|
||||
|
||||
def test_repeated_wrong_phrases_are_rate_limited(serve, http_conn):
|
||||
with serve(limit=3) as (server, _):
|
||||
conn = http_conn(server)
|
||||
|
||||
@@ -0,0 +1,152 @@
|
||||
"""A recording stand-in for the CLI, and two image fixtures, for the MCP tests.
|
||||
|
||||
The MCP server calls ``hhstream.cli``'s handlers in this process, so what sits
|
||||
between a tool and the broker is **the argv list** -- and that list is the only
|
||||
thing this layer decides. :class:`FakeCli` is therefore an entry point that
|
||||
records the argv it was given, prints whatever the test told it to, and returns
|
||||
the exit code the test chose: everything the real entry point is, minus the
|
||||
broker.
|
||||
|
||||
That is also why there is no live socket anywhere in this suite. The broker's
|
||||
behaviour is `tests/sessions`' subject and the VM checks'; what is left here is
|
||||
the shim. Two tests in ``test_mcp_invoke.py`` do drive the **real** entry point
|
||||
against a socket path that does not exist, which is the honest way to prove the
|
||||
dispatch, the capture and the exit-code mapping without standing a daemon up.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import pathlib
|
||||
import struct
|
||||
import sys
|
||||
import zlib
|
||||
from typing import Any
|
||||
|
||||
|
||||
class FakeCli:
|
||||
"""Where :func:`hhstream_mcp.invoke.dispatch` goes in a test.
|
||||
|
||||
Prints through ``sys.stdout``/``sys.stderr`` rather than returning text, so
|
||||
the capture under test is exercised rather than bypassed.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
*,
|
||||
stdout: str = "",
|
||||
stderr: str = "",
|
||||
exit_code: int = 0,
|
||||
write_png: bytes | None = None,
|
||||
raises: BaseException | None = None,
|
||||
) -> None:
|
||||
self.stdout = stdout
|
||||
self.stderr = stderr
|
||||
self.exit_code = exit_code
|
||||
self.write_png = write_png
|
||||
self.raises = raises
|
||||
#: Every argv this was called with, in order.
|
||||
self.calls: list[list[str]] = []
|
||||
|
||||
def __call__(self, argv: list[str]) -> int:
|
||||
self.calls.append(list(argv))
|
||||
if self.write_png is not None:
|
||||
destination = _value_of("--out", argv)
|
||||
if destination:
|
||||
pathlib.Path(destination).write_bytes(self.write_png)
|
||||
if self.stdout:
|
||||
sys.stdout.write(self.stdout)
|
||||
if self.stderr:
|
||||
sys.stderr.write(self.stderr)
|
||||
if self.raises is not None:
|
||||
raise self.raises
|
||||
return self.exit_code
|
||||
|
||||
@property
|
||||
def argv(self) -> list[str]:
|
||||
"""The single call's argv. Fails loudly if there was not exactly one."""
|
||||
|
||||
assert len(self.calls) == 1, f"expected one CLI call, got {self.calls}"
|
||||
return self.calls[0]
|
||||
|
||||
|
||||
def _value_of(name: str, argv: list[str]) -> str | None:
|
||||
prefix = f"{name}="
|
||||
for argument in argv:
|
||||
if argument.startswith(prefix):
|
||||
return argument[len(prefix) :]
|
||||
return None
|
||||
|
||||
|
||||
def reply(**fields: Any) -> str:
|
||||
"""A protocol object the way the CLI prints one: ``json.dumps(indent=2)``."""
|
||||
|
||||
return json.dumps(fields, indent=2, sort_keys=True) + "\n"
|
||||
|
||||
|
||||
def png(width: int = 8, height: int = 4) -> bytes:
|
||||
"""A minimal valid truecolour PNG of a known size.
|
||||
|
||||
Built here rather than shared with the suite's other helper because what is
|
||||
under test is "the server reports the geometry the file actually has", so
|
||||
the size has to be the test's to choose.
|
||||
"""
|
||||
|
||||
def chunk(kind: bytes, data: bytes) -> bytes:
|
||||
return (
|
||||
struct.pack(">I", len(data))
|
||||
+ kind
|
||||
+ data
|
||||
+ struct.pack(">I", zlib.crc32(kind + data) & 0xFFFFFFFF)
|
||||
)
|
||||
|
||||
raster = (b"\x00" + b"\x10\x20\x30" * width) * height
|
||||
return (
|
||||
b"\x89PNG\r\n\x1a\n"
|
||||
+ chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0))
|
||||
+ chunk(b"IDAT", zlib.compress(raster, 9))
|
||||
+ chunk(b"IEND", b"")
|
||||
)
|
||||
|
||||
|
||||
def jpeg(width: int = 6, height: int = 3) -> bytes:
|
||||
"""Enough of a JPEG to carry a SOF0: magic, APP0, SOF0, EOI.
|
||||
|
||||
Not a decodable image, deliberately: what is under test is the header scan
|
||||
that has to skip a segment it does not care about and find the one it does.
|
||||
"""
|
||||
|
||||
app0 = (
|
||||
b"\xff\xe0"
|
||||
+ struct.pack(">H", 16)
|
||||
+ b"JFIF\x00"
|
||||
+ b"\x01\x01\x00"
|
||||
+ b"\x00\x01" * 2
|
||||
+ b"\x00\x00"
|
||||
)
|
||||
sof0 = (
|
||||
b"\xff\xc0"
|
||||
+ struct.pack(">H", 11)
|
||||
+ b"\x08"
|
||||
+ struct.pack(">HH", height, width)
|
||||
+ b"\x01\x01\x11\x00"
|
||||
)
|
||||
return b"\xff\xd8" + app0 + sof0 + b"\xff\xd9"
|
||||
|
||||
|
||||
def isolate(monkeypatch, tmp_path: pathlib.Path) -> None:
|
||||
"""Point every path the CLI reads from the environment at ``tmp_path``.
|
||||
|
||||
A developer's shell has `$HHSTREAM_SOCKET` set, and the real entry point
|
||||
reads it -- so without this a test could reach a live broker on the machine
|
||||
it is running on. The lease directory is redirected for the same reason:
|
||||
`pointer acquire` writes a cache there, and a test must not touch the one a
|
||||
real session is using.
|
||||
"""
|
||||
|
||||
monkeypatch.setenv("HHSTREAM_SOCKET", str(tmp_path / "control.sock"))
|
||||
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(tmp_path / "stream.sock"))
|
||||
monkeypatch.setenv("HHSTREAM_LEASE_DIR", str(tmp_path / "leases"))
|
||||
# `$HHSTREAM_LEASE` outranks the cache in `hhstream_session.lease.recall`,
|
||||
# so an inherited one would hand a gesture a lease it never acquired.
|
||||
monkeypatch.delenv("HHSTREAM_LEASE", raising=False)
|
||||
+38
-13
@@ -75,12 +75,18 @@ def test_a_failure_after_a_good_frame_keeps_the_known_size():
|
||||
|
||||
|
||||
def test_env_is_overlaid_on_our_own_environment():
|
||||
argv = [sys.executable, "-c",
|
||||
"import os,sys;sys.stdout.write(os.environ['WAYLAND_DISPLAY']+':'+"
|
||||
"('PATH' in os.environ and 'haspath' or 'nopath'))"]
|
||||
argv = [
|
||||
sys.executable,
|
||||
"-c",
|
||||
"import os,sys;sys.stdout.write(os.environ['WAYLAND_DISPLAY']+':'+"
|
||||
+ "('PATH' in os.environ and 'haspath' or 'nopath'))",
|
||||
]
|
||||
before = os.environ.get("WAYLAND_DISPLAY")
|
||||
capture = CommandCapture(argv, env={"WAYLAND_DISPLAY": "wayland-9"})
|
||||
assert capture.grab() == b"wayland-9:haspath"
|
||||
assert "WAYLAND_DISPLAY" not in os.environ, "our own environment was mutated"
|
||||
assert os.environ.get("WAYLAND_DISPLAY") == before, (
|
||||
"our own environment was mutated"
|
||||
)
|
||||
|
||||
|
||||
def test_empty_argv_and_bad_timeout_are_rejected_up_front():
|
||||
@@ -91,8 +97,10 @@ def test_empty_argv_and_bad_timeout_are_rejected_up_front():
|
||||
|
||||
|
||||
def test_the_helpers_stdin_is_closed_so_it_cannot_steal_ours():
|
||||
code = ("import sys;"
|
||||
"sys.stdout.buffer.write(b'EMPTY' if not sys.stdin.read() else b'DATA')")
|
||||
code = (
|
||||
"import sys;"
|
||||
"sys.stdout.buffer.write(b'EMPTY' if not sys.stdin.read() else b'DATA')"
|
||||
)
|
||||
assert CommandCapture([sys.executable, "-c", code]).grab() == b"EMPTY"
|
||||
|
||||
|
||||
@@ -102,15 +110,32 @@ def test_image_size_reads_png_headers(width, height):
|
||||
|
||||
|
||||
def test_image_size_reads_a_jpeg_sof_header():
|
||||
jpeg = (b"\xff\xd8"
|
||||
+ b"\xff\xe0" + (16).to_bytes(2, "big") + b"JFIF\x00" + b"\x00" * 9
|
||||
+ b"\xff\xc0" + (17).to_bytes(2, "big") + b"\x08"
|
||||
+ (720).to_bytes(2, "big") + (1280).to_bytes(2, "big")
|
||||
+ b"\x03" + b"\x00" * 9)
|
||||
jpeg = (
|
||||
b"\xff\xd8"
|
||||
+ b"\xff\xe0"
|
||||
+ (16).to_bytes(2, "big")
|
||||
+ b"JFIF\x00"
|
||||
+ b"\x00" * 9
|
||||
+ b"\xff\xc0"
|
||||
+ (17).to_bytes(2, "big")
|
||||
+ b"\x08"
|
||||
+ (720).to_bytes(2, "big")
|
||||
+ (1280).to_bytes(2, "big")
|
||||
+ b"\x03"
|
||||
+ b"\x00" * 9
|
||||
)
|
||||
assert image_size(jpeg) == (1280, 720)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("data", [b"", b"not an image", b"\x89PNG\r\n\x1a\n",
|
||||
b"\xff\xd8", b"\xff\xd8\xff\xc0\x00\x11"])
|
||||
@pytest.mark.parametrize(
|
||||
"data",
|
||||
[
|
||||
b"",
|
||||
b"not an image",
|
||||
b"\x89PNG\r\n\x1a\n",
|
||||
b"\xff\xd8",
|
||||
b"\xff\xd8\xff\xc0\x00\x11",
|
||||
],
|
||||
)
|
||||
def test_image_size_returns_none_when_it_cannot_tell(data):
|
||||
assert image_size(data) is None
|
||||
@@ -0,0 +1,389 @@
|
||||
"""The runner: how the CLI is called in process, decoded, and mapped to a code.
|
||||
|
||||
Most of this drives a recording stand-in (:class:`mcp_fake.FakeCli`), because
|
||||
the subject is what this layer decides -- the argv list and the mapping. Three
|
||||
tests drive the **real** entry point, against a control socket that does not
|
||||
exist: that is the honest way to prove the dispatch, the capture and the
|
||||
exit-code mapping against the CLI's actual parser without standing a daemon up.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import contextlib
|
||||
import os
|
||||
import signal
|
||||
|
||||
import mcp_fake
|
||||
import pytest
|
||||
from hhstreamd.protocol import ExitCode
|
||||
from hhstream_mcp import invoke, media
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def _isolated(monkeypatch, tmp_path):
|
||||
mcp_fake.isolate(monkeypatch, tmp_path)
|
||||
|
||||
|
||||
# ── the call ───────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_the_argv_reaches_the_entry_point_unchanged():
|
||||
fake = mcp_fake.FakeCli(stdout="hello\n")
|
||||
outcome = invoke.Runner(fake).run(["session", "list", "--json"])
|
||||
|
||||
assert outcome.ok
|
||||
assert outcome.stdout == "hello\n"
|
||||
assert fake.argv == ["session", "list", "--json"]
|
||||
assert outcome.argv == ["session", "list", "--json"]
|
||||
|
||||
|
||||
def test_a_metacharacter_is_one_argument_and_never_a_statement():
|
||||
"""There is no shell between a tool and the CLI, and no string either."""
|
||||
|
||||
fake = mcp_fake.FakeCli()
|
||||
nasty = "; rm -rf / #"
|
||||
invoke.Runner(fake).run(["session", "keyboard", "type", "--", "s1", nasty])
|
||||
|
||||
assert fake.argv == ["session", "keyboard", "type", "--", "s1", nasty]
|
||||
|
||||
|
||||
def test_what_the_cli_prints_is_captured_and_not_leaked_to_the_transport(capsys):
|
||||
"""A print on stdout here would be a parse error at the client."""
|
||||
|
||||
fake = mcp_fake.FakeCli(stdout="on stdout\n", stderr="on stderr\n")
|
||||
outcome = invoke.Runner(fake).run(["status"])
|
||||
|
||||
assert outcome.stdout == "on stdout\n"
|
||||
assert outcome.stderr == "on stderr\n"
|
||||
escaped = capsys.readouterr()
|
||||
assert escaped.out == ""
|
||||
assert escaped.err == ""
|
||||
|
||||
|
||||
def test_sys_exit_is_the_exit_code_a_process_would_have_had():
|
||||
"""argparse refuses with `sys.exit(2)`; handlers exit on a missing tool."""
|
||||
|
||||
fake = mcp_fake.FakeCli(raises=SystemExit(2))
|
||||
assert invoke.Runner(fake).run(["session"]).returncode == int(ExitCode.USAGE)
|
||||
|
||||
# `sys.exit("message")` is status 1 in a real process, and the message is
|
||||
# the exit code object rather than something printed.
|
||||
fake = mcp_fake.FakeCli(raises=SystemExit("hhstream: grim is not on PATH"))
|
||||
assert invoke.Runner(fake).run(["shot"]).returncode == invoke.GENERIC_FAILURE
|
||||
|
||||
fake = mcp_fake.FakeCli(raises=SystemExit(None))
|
||||
assert invoke.Runner(fake).run(["status"]).returncode == 0
|
||||
|
||||
|
||||
def test_an_uncaught_exception_becomes_exit_one_with_its_traceback():
|
||||
"""What a CLI process would have done, rather than a transport error."""
|
||||
|
||||
fake = mcp_fake.FakeCli(raises=RuntimeError("boom"))
|
||||
outcome = invoke.Runner(fake).run(["session", "list", "--json"])
|
||||
|
||||
assert outcome.returncode == invoke.GENERIC_FAILURE
|
||||
assert "RuntimeError: boom" in outcome.stderr
|
||||
assert "Traceback" in outcome.stderr
|
||||
|
||||
|
||||
def test_a_keyboard_interrupt_is_not_swallowed_as_a_tool_result():
|
||||
"""BaseException is caught on purpose; the code still says "failed"."""
|
||||
|
||||
fake = mcp_fake.FakeCli(raises=KeyboardInterrupt())
|
||||
outcome = invoke.Runner(fake).run(["session", "list"])
|
||||
assert outcome.returncode == invoke.GENERIC_FAILURE
|
||||
|
||||
|
||||
def test_a_call_runs_with_the_serialising_lock_held():
|
||||
"""The CLI prints to a process-global stdout, so one call at a time.
|
||||
|
||||
Asserted from inside the call rather than by racing two threads and hoping
|
||||
their output interleaves: a race that passes by luck is not a test. The
|
||||
private name is the point -- what is being asserted is that this specific
|
||||
lock is held while a handler runs.
|
||||
"""
|
||||
|
||||
def probing(argv):
|
||||
free = invoke._ONE_AT_A_TIME.acquire(blocking=False)
|
||||
if free:
|
||||
invoke._ONE_AT_A_TIME.release()
|
||||
print("free" if free else "held", end="")
|
||||
return 0
|
||||
|
||||
assert invoke.Runner(probing).run(["status"]).stdout == "held"
|
||||
|
||||
|
||||
# ── decoding ───────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_the_protocol_object_is_read_from_stdout_on_success():
|
||||
fields = {"ok": True, "id": "s-1", "session": {"state": "running"}}
|
||||
fake = mcp_fake.FakeCli(stdout=mcp_fake.reply(**fields))
|
||||
assert invoke.Runner(fake).run(["session", "status", "--json"]).payload() == fields
|
||||
|
||||
|
||||
def test_the_protocol_object_is_read_from_stderr_on_failure():
|
||||
"""The CLI's own split: an error goes to stderr whatever the output mode."""
|
||||
|
||||
fields = {"ok": False, "error": "no_lease", "reason": "no pointer lease for s-1"}
|
||||
fake = mcp_fake.FakeCli(
|
||||
stderr=mcp_fake.reply(**fields), exit_code=int(ExitCode.NO_LEASE)
|
||||
)
|
||||
outcome = invoke.Runner(fake).run(["session", "pointer", "click", "--json"])
|
||||
|
||||
assert not outcome.ok
|
||||
assert outcome.payload() == fields
|
||||
|
||||
|
||||
def test_an_object_printed_under_a_bare_line_is_still_found():
|
||||
"""`session start` prints the id beside its object; parsing must survive it."""
|
||||
|
||||
fake = mcp_fake.FakeCli(stdout='s-1\n{\n "ok": true,\n "id": "s-1"\n}\n')
|
||||
assert invoke.Runner(fake).run(["session", "start"]).payload() == {
|
||||
"ok": True,
|
||||
"id": "s-1",
|
||||
}
|
||||
|
||||
|
||||
def test_no_json_at_all_is_none_rather_than_an_invention():
|
||||
fake = mcp_fake.FakeCli(stdout="services:\n hyprland-headless.service active\n")
|
||||
assert invoke.Runner(fake).run(["status"]).payload() is None
|
||||
|
||||
|
||||
def test_a_json_array_is_not_mistaken_for_the_protocol_object():
|
||||
assert invoke.first_json_object("[1, 2, 3]") is None
|
||||
assert invoke.first_json_object('[{"a": 1}]') == {"a": 1}
|
||||
|
||||
|
||||
# ── the real entry point, with nothing listening ───────────────────────────
|
||||
|
||||
|
||||
def test_the_real_cli_refuses_a_bad_flag_with_the_frozen_usage_code():
|
||||
"""argparse's own refusal, through the CLI's own parser, mapped to exit 2."""
|
||||
|
||||
outcome = invoke.Runner().run(
|
||||
["session", "pointer", "click", "--json", "--button=nonsense", "--", "s-1"]
|
||||
)
|
||||
|
||||
assert outcome.returncode == int(ExitCode.USAGE)
|
||||
assert "invalid choice" in outcome.stderr
|
||||
# And nothing escaped onto the real stdout: argparse prints usage there for
|
||||
# --help and to stderr for an error, and both are captured.
|
||||
assert outcome.stdout == ""
|
||||
|
||||
|
||||
def test_the_real_cli_reports_an_unreachable_broker_as_the_frozen_code():
|
||||
"""No socket, no daemon, no fake: the mapping end to end."""
|
||||
|
||||
outcome = invoke.Runner().run(["session", "list", "--json"])
|
||||
|
||||
assert outcome.returncode == int(ExitCode.DAEMON_UNREACHABLE)
|
||||
payload = outcome.payload()
|
||||
assert payload is not None
|
||||
assert payload["error"] == "daemon_unreachable"
|
||||
|
||||
|
||||
def test_the_real_cli_refuses_a_gesture_with_no_lease_without_a_broker():
|
||||
"""Exit 9 is produced by the CLI before the socket is touched at all."""
|
||||
|
||||
outcome = invoke.Runner().run(
|
||||
["session", "pointer", "click", "--json", "--", "s-1"]
|
||||
)
|
||||
|
||||
assert outcome.returncode == int(ExitCode.NO_LEASE)
|
||||
assert (outcome.payload() or {}).get("error") == "no_lease"
|
||||
|
||||
|
||||
def test_an_unreachable_frame_socket_earns_the_hint_the_sg_re_exec_replaces():
|
||||
"""The one capability lost by calling the CLI in process, said out loud."""
|
||||
|
||||
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=1)).run(["shot"])
|
||||
|
||||
assert "cannot read" in outcome.stderr
|
||||
assert "sg hhstream" in outcome.stderr
|
||||
|
||||
|
||||
def test_the_hint_is_absent_when_the_socket_is_readable(tmp_path, monkeypatch):
|
||||
readable = tmp_path / "stream.sock"
|
||||
readable.write_bytes(b"")
|
||||
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(readable))
|
||||
|
||||
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=1)).run(["shot"])
|
||||
assert "sg hhstream" not in outcome.stderr
|
||||
|
||||
|
||||
def test_a_session_verb_never_earns_the_frame_socket_hint():
|
||||
"""It has nothing to do with the control socket, so it must not be offered."""
|
||||
|
||||
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=int(ExitCode.BUSY))).run(
|
||||
["session", "pointer", "acquire", "--json", "--", "s-1"]
|
||||
)
|
||||
assert "sg hhstream" not in outcome.stderr
|
||||
|
||||
|
||||
# ── the exit-code table ────────────────────────────────────────────────────
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"code",
|
||||
[
|
||||
ExitCode.USAGE,
|
||||
ExitCode.NO_SUCH_SESSION,
|
||||
ExitCode.BAD_STATE,
|
||||
ExitCode.DAEMON_UNREACHABLE,
|
||||
ExitCode.POLICY,
|
||||
ExitCode.TIMEOUT,
|
||||
ExitCode.BUSY,
|
||||
ExitCode.NO_LEASE,
|
||||
ExitCode.COMPOSITOR,
|
||||
],
|
||||
)
|
||||
def test_every_frozen_exit_code_has_a_remedy_naming_itself(code):
|
||||
"""A new code in the frozen table must not fall through to a generic line."""
|
||||
|
||||
text = invoke.remedy_for(int(code))
|
||||
assert text.startswith(f"exit {int(code)} ({code.name})")
|
||||
assert int(code) in invoke.REMEDY
|
||||
|
||||
|
||||
def test_the_lease_codes_say_the_two_different_things_an_agent_must_do():
|
||||
"""8 and 9 are the pair that must never read alike (CONTRACT-sessions.md §4)."""
|
||||
|
||||
busy = invoke.remedy_for(int(ExitCode.BUSY))
|
||||
none_held = invoke.remedy_for(int(ExitCode.NO_LEASE))
|
||||
|
||||
assert "hhstream://pointer" in busy and "wait" in busy
|
||||
assert "pointer_acquire" in none_held
|
||||
# "acquire one" must not be the advice for BUSY: that is the one confusion
|
||||
# the two codes exist to prevent.
|
||||
assert "pointer_acquire" not in busy
|
||||
|
||||
|
||||
def test_an_unclassified_code_is_still_a_failure_and_says_so():
|
||||
text = invoke.remedy_for(42)
|
||||
assert "exit 42 (UNCLASSIFIED)" in text
|
||||
assert "do not assume anything happened" in text
|
||||
|
||||
|
||||
def test_generic_failure_is_its_own_case():
|
||||
"""Exit 1 is the frame verbs', and is not in the broker's frozen table."""
|
||||
|
||||
assert invoke.GENERIC_FAILURE not in [int(code) for code in ExitCode]
|
||||
assert "grim" in invoke.remedy_for(invoke.GENERIC_FAILURE)
|
||||
|
||||
|
||||
# ── launch, for `run` ──────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_launch_leaves_the_application_running_in_its_own_session(wayland):
|
||||
"""`run` launches and forgets, and a killed server must not take it along."""
|
||||
|
||||
spawned = invoke.Runner().launch(["sleep", "30"], settle=0.3)
|
||||
try:
|
||||
assert not spawned.exited
|
||||
assert spawned.pid > 0
|
||||
os.kill(spawned.pid, 0)
|
||||
# Its own session, so a client that kills this server's process group
|
||||
# does not kill the desktop with it.
|
||||
assert os.getsid(spawned.pid) == spawned.pid
|
||||
assert os.getsid(spawned.pid) != os.getsid(0)
|
||||
finally:
|
||||
with contextlib.suppress(ProcessLookupError):
|
||||
os.kill(spawned.pid, signal.SIGTERM)
|
||||
|
||||
|
||||
def test_launch_reports_an_application_that_died_inside_the_window(wayland):
|
||||
spawned = invoke.Runner().launch(["false"], settle=5.0)
|
||||
|
||||
assert spawned.exited
|
||||
assert spawned.pid > 0
|
||||
|
||||
|
||||
def test_launch_hands_back_what_a_failing_application_said(wayland):
|
||||
spawned = invoke.Runner().launch(
|
||||
["sh", "-c", "echo 'cannot open display' >&2; exit 3"], settle=5.0
|
||||
)
|
||||
|
||||
assert spawned.exited
|
||||
assert "cannot open display" in spawned.stderr
|
||||
|
||||
|
||||
def test_launch_refuses_a_command_that_is_not_on_path_rather_than_forking(wayland):
|
||||
spawned = invoke.Runner().launch(["definitely-not-a-program-here"], settle=5.0)
|
||||
|
||||
assert spawned.exited
|
||||
assert spawned.pid == 0
|
||||
assert "no executable" in spawned.stderr
|
||||
|
||||
|
||||
def test_launch_passes_on_the_cli_s_own_refusal_when_there_is_no_compositor(tmp_path, monkeypatch):
|
||||
"""`env_for_session` exits with the message; it is handed on verbatim."""
|
||||
|
||||
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(tmp_path / "empty" / "stream.sock"))
|
||||
(tmp_path / "empty").mkdir()
|
||||
spawned = invoke.Runner().launch(["true"], settle=1.0)
|
||||
|
||||
assert spawned.exited
|
||||
assert spawned.pid == 0
|
||||
assert "no wayland socket" in spawned.stderr
|
||||
assert "is the compositor up?" in spawned.stderr
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def wayland(workdir, monkeypatch):
|
||||
"""A runtime directory with something `env_for_session` accepts in it.
|
||||
|
||||
A real AF_UNIX socket, because that function checks `is_socket()` -- an
|
||||
empty file would make it refuse for a reason these tests are not about.
|
||||
The suite's `workdir` fixture and not `tmp_path`, because an AF_UNIX
|
||||
address is capped near 108 bytes and pytest's own paths are longer than
|
||||
that.
|
||||
"""
|
||||
|
||||
import socket
|
||||
|
||||
listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
||||
listener.bind(str(workdir / "wayland-0"))
|
||||
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(workdir / "stream.sock"))
|
||||
yield workdir
|
||||
listener.close()
|
||||
|
||||
|
||||
# ── artefact readers ───────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_a_png_is_sniffed_by_its_header_not_its_extension():
|
||||
image = media.sniff(mcp_fake.png(width=13, height=7))
|
||||
assert image is not None
|
||||
assert (image.media_type, image.width, image.height) == ("image/png", 13, 7)
|
||||
|
||||
|
||||
def test_a_jpeg_under_a_png_filename_is_still_a_jpeg():
|
||||
"""The publisher serves `image/jpeg` on the deployment machine."""
|
||||
|
||||
image = media.sniff(mcp_fake.jpeg(width=6, height=3))
|
||||
assert image is not None
|
||||
assert (image.media_type, image.width, image.height) == ("image/jpeg", 6, 3)
|
||||
|
||||
|
||||
def test_an_unrecognised_format_is_none_rather_than_a_guess():
|
||||
assert media.sniff(b"GIF89a\x00\x00") is None
|
||||
assert media.sniff(b"") is None
|
||||
|
||||
|
||||
def test_the_measured_record_rate_is_read_off_the_cli_s_own_line():
|
||||
found = media.recording("/tmp/out.mp4 (57 frames in 6.02s -> 9 fps)\n")
|
||||
assert found is not None
|
||||
assert (found.path, found.frames, found.seconds, found.fps) == ("/tmp/out.mp4", 57, 6.02, 9)
|
||||
|
||||
|
||||
def test_a_record_line_in_an_unexpected_shape_is_not_half_parsed():
|
||||
assert media.recording("/tmp/out.mp4\n") is None
|
||||
assert media.recording("") is None
|
||||
|
||||
|
||||
def test_temp_name_is_unique_per_process_and_under_a_named_directory():
|
||||
first = invoke.temp_name("recording", ".mp4")
|
||||
assert "hhstream-mcp" in first
|
||||
assert first.endswith(".mp4")
|
||||
assert str(os.getpid()) in first
|
||||
@@ -0,0 +1,303 @@
|
||||
"""The resource table: which URI runs which CLI call, and what comes back.
|
||||
|
||||
Same subject as ``test_mcp_tools.py`` and the same stand-in: what this layer
|
||||
decides is the argv list, and here also the *routing* -- which entry a URI
|
||||
resolves to, and which query parameters it will accept. Nothing here imports
|
||||
the MCP SDK; the protocol wiring is ``test_mcp_server.py``.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
|
||||
import mcp_fake
|
||||
import pytest
|
||||
from hhstreamd.protocol import ExitCode
|
||||
from hhstream_mcp import invoke, resources, tools
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def _isolated(monkeypatch, tmp_path):
|
||||
mcp_fake.isolate(monkeypatch, tmp_path)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def read():
|
||||
"""`read("hhstream://sessions")` -> (Reading, [argv, ...])."""
|
||||
|
||||
def _read(uri, **script):
|
||||
fake = mcp_fake.FakeCli(**script)
|
||||
reading = resources.read(invoke.Runner(fake), uri)
|
||||
return reading, fake.calls
|
||||
|
||||
return _read
|
||||
|
||||
|
||||
# ── the table ──────────────────────────────────────────────────────────────
|
||||
|
||||
#: Every resource `docs/CONTRACT-mcp.md` §4 freezes, written out rather than
|
||||
#: derived, for the reason the tool list is.
|
||||
EXPECTED_FIXED = {
|
||||
"hhstream://status",
|
||||
"hhstream://sessions",
|
||||
"hhstream://pointer",
|
||||
"hhstream://containers",
|
||||
"hhstream://screen",
|
||||
}
|
||||
EXPECTED_TEMPLATES = {
|
||||
"hhstream://sessions/{id}{?events}",
|
||||
"hhstream://sessions/{id}/logs{?lines}",
|
||||
"hhstream://outputs/{name}",
|
||||
}
|
||||
|
||||
|
||||
def test_the_whole_surface_is_there_and_nothing_else_is():
|
||||
assert {entry.uri for entry in resources.FIXED} == EXPECTED_FIXED
|
||||
assert {entry.uri_template for entry in resources.TEMPLATES} == EXPECTED_TEMPLATES
|
||||
assert len(resources.ENTRIES) == len(EXPECTED_FIXED) + len(EXPECTED_TEMPLATES)
|
||||
|
||||
|
||||
def test_every_entry_has_a_unique_name_and_a_description():
|
||||
names = [entry.name for entry in resources.ENTRIES]
|
||||
assert len(names) == len(set(names))
|
||||
for entry in resources.ENTRIES:
|
||||
assert entry.title, entry.name
|
||||
assert len(entry.description) > 40, entry.name
|
||||
assert entry.media_type
|
||||
|
||||
|
||||
def test_a_template_is_exactly_an_entry_with_a_capture():
|
||||
for entry in resources.FIXED:
|
||||
assert entry.captures == ()
|
||||
for entry in resources.TEMPLATES:
|
||||
assert entry.captures
|
||||
|
||||
|
||||
def test_the_three_reads_the_activity_rule_names_say_so_themselves():
|
||||
"""The rule has to be where it is read, and these are read, not called."""
|
||||
|
||||
for name in ("sessions", "session", "session-logs", "pointer", "containers"):
|
||||
description = resources.BY_NAME[name].description
|
||||
assert "does NOT reset" in description, name
|
||||
assert "`session_touch`" in description, name
|
||||
|
||||
|
||||
# ── routing ────────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_a_literal_route_beats_a_template_that_would_also_match():
|
||||
"""`hhstream://sessions` is the listing, not a session with a blank id."""
|
||||
|
||||
entry, arguments = resources.resolve("hhstream://sessions")
|
||||
assert entry.name == "sessions"
|
||||
assert arguments == {}
|
||||
|
||||
|
||||
def test_a_capture_becomes_the_argument_the_cli_takes(read):
|
||||
_, calls = read("hhstream://sessions/foot-abc", stdout=mcp_fake.reply(ok=True))
|
||||
assert calls == [["session", "status", "--json", "--", "foot-abc"]]
|
||||
|
||||
|
||||
def test_a_deeper_route_is_its_own_entry(read):
|
||||
_, calls = read("hhstream://sessions/foot-abc/logs", stdout=mcp_fake.reply(ok=True))
|
||||
assert calls == [["session", "logs", "--json", "--", "foot-abc"]]
|
||||
|
||||
|
||||
def test_each_fixed_resource_runs_the_verb_it_names(read):
|
||||
cases = {
|
||||
"hhstream://status": ["status"],
|
||||
"hhstream://sessions": ["session", "list", "--json"],
|
||||
"hhstream://pointer": ["session", "pointer", "state", "--json"],
|
||||
"hhstream://containers": ["session", "container", "--json"],
|
||||
}
|
||||
for uri, argv in cases.items():
|
||||
_, calls = read(uri, stdout=mcp_fake.reply(ok=True))
|
||||
assert calls == [argv], uri
|
||||
|
||||
|
||||
def test_the_status_resource_is_text_because_the_verb_has_no_json(read):
|
||||
reading, calls = read("hhstream://status", stdout="services:\n up\n")
|
||||
assert calls == [["status"]]
|
||||
assert reading.media_type == "text/plain"
|
||||
assert reading.text == "services:\n up"
|
||||
assert reading.blob is None
|
||||
|
||||
|
||||
def test_a_json_resource_passes_the_protocol_object_through_unchanged(read):
|
||||
reply = {"ok": True, "sessions": [{"id": "s-1", "state": "running"}]}
|
||||
reading, _ = read("hhstream://sessions", stdout=json.dumps(reply, indent=2))
|
||||
|
||||
assert reading.media_type == "application/json"
|
||||
assert json.loads(reading.text) == reply
|
||||
|
||||
|
||||
def test_a_scheme_this_server_does_not_serve_is_refused(read):
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read("file:///etc/passwd")
|
||||
assert "not a hhstream resource" in str(caught.value)
|
||||
|
||||
|
||||
def test_a_uri_that_names_nothing_is_refused_and_points_at_the_listing(read):
|
||||
for uri in ("hhstream://nonsense", "hhstream://sessions/a/b/c", "hhstream://"):
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read(uri)
|
||||
assert "resources/list" in str(caught.value) or "names no resource" in str(
|
||||
caught.value
|
||||
)
|
||||
|
||||
|
||||
def test_nothing_was_run_for_a_uri_that_did_not_resolve(monkeypatch, tmp_path):
|
||||
"""The routing refuses before the CLI is reached, as a schema would."""
|
||||
|
||||
fake = mcp_fake.FakeCli()
|
||||
with pytest.raises(resources.ReadRefused):
|
||||
resources.read(invoke.Runner(fake), "hhstream://nonsense")
|
||||
assert fake.calls == []
|
||||
|
||||
|
||||
# ── query parameters ───────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_a_declared_parameter_becomes_the_flag_the_cli_takes(read):
|
||||
_, calls = read(
|
||||
"hhstream://sessions/foot-abc/logs?lines=250", stdout=mcp_fake.reply(ok=True)
|
||||
)
|
||||
assert calls == [["session", "logs", "--json", "--lines=250", "--", "foot-abc"]]
|
||||
|
||||
_, calls = read(
|
||||
"hhstream://sessions/foot-abc?events=5", stdout=mcp_fake.reply(ok=True)
|
||||
)
|
||||
assert calls == [["session", "status", "--json", "--events=5", "--", "foot-abc"]]
|
||||
|
||||
|
||||
def test_a_switch_parameter_is_a_bare_flag_or_nothing(read):
|
||||
"""`--all=false` is not a thing the CLI takes, so false must omit it."""
|
||||
|
||||
_, calls = read("hhstream://sessions?all=true", stdout=mcp_fake.reply(ok=True))
|
||||
assert calls == [["session", "list", "--json", "--all"]]
|
||||
|
||||
for falsey in ("false", "0", "no", "off", ""):
|
||||
_, calls = read(f"hhstream://sessions?all={falsey}", stdout=mcp_fake.reply(ok=True))
|
||||
assert calls == [["session", "list", "--json"]], falsey
|
||||
|
||||
|
||||
def test_an_undeclared_parameter_is_refused_rather_than_dropped(read):
|
||||
"""A parameter silently ignored is a read that answered another question."""
|
||||
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read("hhstream://sessions?lines=5")
|
||||
assert "'lines'" in str(caught.value)
|
||||
assert "all" in str(caught.value)
|
||||
|
||||
|
||||
def test_a_resource_with_no_parameters_says_so_when_given_one(read):
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read("hhstream://pointer?id=s-1")
|
||||
assert "accepts: none" in str(caught.value)
|
||||
|
||||
|
||||
def test_a_parameter_given_twice_is_refused(read):
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read("hhstream://sessions/s-1/logs?lines=1&lines=2")
|
||||
assert "more than once" in str(caught.value)
|
||||
|
||||
|
||||
def test_the_template_advertises_the_parameters_it_accepts():
|
||||
"""So a client can construct a URI without guessing."""
|
||||
|
||||
logs = resources.BY_NAME["session-logs"]
|
||||
assert logs.uri_template == "hhstream://sessions/{id}/logs{?lines}"
|
||||
assert logs.parameters == ("lines",)
|
||||
|
||||
|
||||
# ── refusals ───────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_a_cli_refusal_is_raised_and_never_returned_as_the_body(read):
|
||||
"""A resource has no `isError`; returning the failure object would lie."""
|
||||
|
||||
reply = {"ok": False, "error": "no_such_session", "reason": "no session 'nope'"}
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read(
|
||||
"hhstream://sessions/nope",
|
||||
stderr=mcp_fake.reply(**reply),
|
||||
exit_code=int(ExitCode.NO_SUCH_SESSION),
|
||||
)
|
||||
refused = caught.value
|
||||
assert "exit 3 (NO_SUCH_SESSION)" in refused.message
|
||||
assert "no session 'nope'" in refused.message
|
||||
# And the structured detail carries what a tool error would have carried.
|
||||
assert refused.detail["exit_code"] == int(ExitCode.NO_SUCH_SESSION)
|
||||
assert refused.detail["error"] == "no_such_session"
|
||||
assert "hhstream://sessions" in refused.detail["remedy"]
|
||||
|
||||
|
||||
def test_an_unreachable_broker_is_refused_with_the_operator_s_remedy(read):
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read(
|
||||
"hhstream://sessions",
|
||||
stderr=mcp_fake.reply(ok=False, error="daemon_unreachable", reason="no socket"),
|
||||
exit_code=int(ExitCode.DAEMON_UNREACHABLE),
|
||||
)
|
||||
assert "HHSTREAM_SOCKET" in caught.value.message
|
||||
|
||||
|
||||
# ── frames ─────────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_the_screen_resource_is_the_frame_bytes_with_its_real_media_type(read):
|
||||
frame = mcp_fake.png(width=320, height=180)
|
||||
reading, calls = read("hhstream://screen", write_png=frame)
|
||||
|
||||
assert calls[0][0] == "shot"
|
||||
assert calls[0][1].startswith("--out=")
|
||||
assert len(calls[0]) == 2, "the screen takes no --output"
|
||||
assert reading.blob == frame
|
||||
assert reading.text is None
|
||||
assert reading.media_type == "image/png"
|
||||
|
||||
|
||||
def test_an_output_resource_captures_that_output_alone(read):
|
||||
frame = mcp_fake.png()
|
||||
reading, calls = read("hhstream://outputs/hh-foot-abc", write_png=frame)
|
||||
|
||||
assert "--output=hh-foot-abc" in calls[0]
|
||||
assert reading.blob == frame
|
||||
|
||||
|
||||
def test_a_frame_s_media_type_is_sniffed_and_not_assumed(read):
|
||||
"""The entry declares image/png; a JPEG publisher must still be told truly."""
|
||||
|
||||
assert resources.BY_NAME["screen"].media_type == "image/png"
|
||||
reading, _ = read("hhstream://screen", write_png=mcp_fake.jpeg())
|
||||
assert reading.media_type == "image/jpeg"
|
||||
|
||||
|
||||
def test_a_capture_that_wrote_no_file_is_refused_rather_than_empty(read):
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read("hhstream://screen")
|
||||
assert "no readable file" in str(caught.value)
|
||||
|
||||
|
||||
def test_a_refused_capture_carries_the_cli_s_own_words(read):
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read(
|
||||
"hhstream://outputs/hh-gone",
|
||||
stderr="hhstream: could not capture output 'hh-gone': unknown output\n",
|
||||
exit_code=1,
|
||||
)
|
||||
assert "unknown output" in str(caught.value)
|
||||
assert "hh-gone" in str(caught.value)
|
||||
|
||||
|
||||
# ── the one read that must not be a resource ───────────────────────────────
|
||||
|
||||
|
||||
def test_there_is_no_resource_for_the_reconciling_container_read():
|
||||
"""`session container <id>` writes. Only the no-id list is a resource."""
|
||||
|
||||
assert "hhstream://containers" in EXPECTED_FIXED
|
||||
for entry in resources.ENTRIES:
|
||||
assert entry.route[:1] != ("containers",) or entry.captures == ()
|
||||
# ...and the writing form is still reachable, as a tool.
|
||||
assert "session_container" in tools.BY_NAME
|
||||
@@ -0,0 +1,530 @@
|
||||
"""The SDK wiring: the handshake, the listing, and one call of each shape.
|
||||
|
||||
This is the file that imports the MCP SDK, and it does so unconditionally. The
|
||||
tool table is standard library and tested without it
|
||||
(``test_mcp_tools.py``); what is left is the part only the SDK can judge --
|
||||
whether every schema validates, whether every name is one the specification
|
||||
allows, and whether a refusal arrives as a tool error rather than a success. A
|
||||
file that skipped when the SDK was absent would be green in exactly the build
|
||||
where that mattered, which is why ``checks/unit.nix`` puts ``mcp`` in the test
|
||||
environment rather than making it optional.
|
||||
|
||||
The server runs in process, over the SDK's in-memory transport. The stdio
|
||||
transport itself is proved end to end by ``checks/vm-mcp.nix`` and by the
|
||||
handshake in the pull request description -- a pair of memory streams cannot
|
||||
tell you that a stray ``print`` has corrupted stdout.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
|
||||
import anyio
|
||||
import jsonschema
|
||||
import mcp.types as types
|
||||
import mcp_fake
|
||||
import pytest
|
||||
from hhstreamd.protocol import ExitCode
|
||||
from mcp.shared.memory import create_connected_server_and_client_session
|
||||
from mcp.shared.tool_name_validation import validate_tool_name
|
||||
from pydantic import AnyUrl
|
||||
|
||||
from hhstream_mcp import SERVER_NAME, __version__, invoke, resources, server, tools
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def _isolated(monkeypatch, tmp_path):
|
||||
mcp_fake.isolate(monkeypatch, tmp_path)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def session():
|
||||
"""`session(...)` -> (the recording CLI, a connected client session).
|
||||
|
||||
The stand-in is scripted per test, exactly as in the table's own tests;
|
||||
what is added here is a real client on the other end of a real server, so
|
||||
`initialize` and the two request types are exercised rather than asserted
|
||||
about.
|
||||
"""
|
||||
|
||||
def _session(toolsets=None, **script):
|
||||
fake = mcp_fake.FakeCli(**script)
|
||||
built = server.build(invoke.Runner(fake), toolsets)
|
||||
return fake, create_connected_server_and_client_session(
|
||||
built, raise_exceptions=True
|
||||
)
|
||||
|
||||
return _session
|
||||
|
||||
|
||||
def run(coroutine):
|
||||
return anyio.run(coroutine)
|
||||
|
||||
|
||||
# ── the handshake ──────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_initialize_names_this_server_and_declares_tools(session):
|
||||
_, connected = session()
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
result = await client.initialize()
|
||||
return result
|
||||
|
||||
initialized = run(go)
|
||||
assert initialized.serverInfo.name == SERVER_NAME
|
||||
assert initialized.serverInfo.version == __version__
|
||||
assert initialized.capabilities.tools is not None
|
||||
# Resources are half the surface now, so the capability has to be declared
|
||||
# or a host will never ask for them.
|
||||
assert initialized.capabilities.resources is not None
|
||||
# The instructions are where the two rules are said once for the whole
|
||||
# surface; a client that shows them must be given them.
|
||||
assert initialized.instructions
|
||||
assert "`session_touch` is the ONLY" in initialized.instructions
|
||||
|
||||
|
||||
def test_the_instructions_carry_both_rules():
|
||||
assert "`session_touch` is the ONLY" in server.INSTRUCTIONS
|
||||
assert "POINTER lease" in server.INSTRUCTIONS
|
||||
assert "There is no keyboard lease" in server.INSTRUCTIONS
|
||||
# And the two lease codes an agent has to tell apart.
|
||||
assert "Exit 8 means" in server.INSTRUCTIONS
|
||||
assert "9 means you need to acquire one" in server.INSTRUCTIONS
|
||||
|
||||
|
||||
def test_the_instructions_explain_the_split_they_cannot_be_read_without():
|
||||
"""An agent that does not know state is a resource will look for a tool."""
|
||||
|
||||
assert "Resources are the state" in server.INSTRUCTIONS
|
||||
assert "Tools are the acts" in server.INSTRUCTIONS
|
||||
for uri in ("hhstream://status", "hhstream://sessions", "hhstream://pointer"):
|
||||
assert uri in server.INSTRUCTIONS
|
||||
|
||||
|
||||
# ── the listing ────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_tools_list_returns_every_tool_with_a_title_and_a_description(session):
|
||||
_, connected = session()
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.list_tools()
|
||||
|
||||
listed = run(go).tools
|
||||
assert {tool.name for tool in listed} == set(tools.BY_NAME)
|
||||
assert len(listed) == 21
|
||||
for tool in listed:
|
||||
assert tool.title, tool.name
|
||||
assert tool.description and len(tool.description) > 40, tool.name
|
||||
assert tool.annotations is not None
|
||||
assert tool.annotations.openWorldHint is False
|
||||
|
||||
|
||||
def test_every_tool_name_is_one_the_specification_allows():
|
||||
for tool in tools.TOOLS:
|
||||
result = validate_tool_name(tool.name)
|
||||
assert result.is_valid, (tool.name, result.warnings)
|
||||
# Warnings are not failures to the SDK, but a name that earns one is a
|
||||
# name that will be mangled by some client.
|
||||
assert result.warnings == [], (tool.name, result.warnings)
|
||||
|
||||
|
||||
def test_every_input_schema_is_a_schema_the_validator_accepts():
|
||||
"""The SDK validates every call against these; a bad one fails at call time."""
|
||||
|
||||
for tool in tools.TOOLS:
|
||||
jsonschema.Draft202012Validator.check_schema(tool.schema)
|
||||
|
||||
|
||||
def test_the_read_only_hint_is_set_from_the_verb_and_not_from_the_name():
|
||||
for tool in tools.TOOLS:
|
||||
described = server.describe(tool)
|
||||
assert described.annotations.readOnlyHint == tool.read_only
|
||||
if tool.read_only:
|
||||
assert described.annotations.destructiveHint is None
|
||||
else:
|
||||
assert described.annotations.destructiveHint is tool.destructive
|
||||
|
||||
|
||||
# ── the schemas, through the validator the server actually uses ────────────
|
||||
|
||||
|
||||
def test_move_requires_exactly_one_of_to_and_by():
|
||||
schema = tools.BY_NAME["pointer_move"].schema
|
||||
jsonschema.validate({"id": "s", "lease": "L", "to": [0.5, 0.5]}, schema)
|
||||
jsonschema.validate({"id": "s", "lease": "L", "by": [0.5, 0.5]}, schema)
|
||||
for bad in (
|
||||
{"id": "s", "lease": "L"},
|
||||
{"id": "s", "lease": "L", "to": [0.5, 0.5], "by": [0.1, 0.1]},
|
||||
{"id": "s", "lease": "L", "to": [0.5]},
|
||||
{"id": "s", "lease": "L", "to": [0.5, 0.5, 0.5]},
|
||||
):
|
||||
with pytest.raises(jsonschema.ValidationError):
|
||||
jsonschema.validate(bad, schema)
|
||||
|
||||
|
||||
def test_home_and_ephemeral_home_are_refused_together_by_the_schema():
|
||||
"""The CLI's mutually exclusive group, moved forward to where it is cheaper."""
|
||||
|
||||
schema = tools.BY_NAME["session_start"].schema
|
||||
jsonschema.validate({"app": "foot"}, schema)
|
||||
jsonschema.validate({"app": "foot", "home": "/tmp/h"}, schema)
|
||||
jsonschema.validate({"app": "foot", "ephemeral_home": True}, schema)
|
||||
with pytest.raises(jsonschema.ValidationError):
|
||||
jsonschema.validate({"app": "foot", "home": "/tmp/h", "ephemeral_home": True}, schema)
|
||||
|
||||
|
||||
def test_a_gesture_without_a_lease_is_refused_before_the_cli_is_run(session):
|
||||
"""The lease is required, so the schema refuses and no argv is built."""
|
||||
|
||||
fake, connected = session()
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.call_tool("pointer_click", {"id": "s-1"})
|
||||
|
||||
result = run(go)
|
||||
assert result.isError
|
||||
assert "lease" in result.content[0].text
|
||||
# The point of a schema refusal: the CLI was never reached.
|
||||
assert fake.calls == []
|
||||
|
||||
|
||||
# ── calls ──────────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_a_successful_call_carries_the_protocol_object_as_structured_content(session):
|
||||
reply = {"ok": True, "pruned": 0}
|
||||
fake, connected = session(stdout=json.dumps(reply, indent=2))
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.call_tool("session_gc", {})
|
||||
|
||||
result = run(go)
|
||||
assert not result.isError
|
||||
assert result.structuredContent == reply
|
||||
assert fake.calls == [["session", "gc", "--json"]]
|
||||
|
||||
|
||||
def test_a_refused_call_arrives_as_a_tool_error_an_agent_can_read(session):
|
||||
reply = {"ok": False, "error": "no_lease", "reason": "no pointer lease for s-1"}
|
||||
_, connected = session(
|
||||
stderr=json.dumps(reply, indent=2), exit_code=int(ExitCode.NO_LEASE)
|
||||
)
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.call_tool(
|
||||
"pointer_click", {"id": "s-1", "lease": "stale"}
|
||||
)
|
||||
|
||||
result = run(go)
|
||||
assert result.isError is True
|
||||
assert result.structuredContent["exit_code"] == int(ExitCode.NO_LEASE)
|
||||
text = result.content[0].text
|
||||
assert "exit 9 (NO_LEASE)" in text
|
||||
assert "pointer_acquire" in text
|
||||
|
||||
|
||||
def test_a_frame_arrives_as_image_content_beside_its_geometry(session):
|
||||
frame = mcp_fake.png(width=64, height=48)
|
||||
_, connected = session(write_png=frame, stdout="/tmp/ignored.png\n")
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.call_tool("shot", {})
|
||||
|
||||
result = run(go)
|
||||
assert not result.isError
|
||||
kinds = [block.type for block in result.content]
|
||||
assert kinds == ["text", "image"]
|
||||
text, image = result.content
|
||||
assert "64x48 image/png" in text.text
|
||||
assert image.mimeType == "image/png"
|
||||
|
||||
import base64
|
||||
|
||||
assert base64.b64decode(image.data) == frame
|
||||
|
||||
|
||||
def test_a_v1_tool_name_is_told_which_resource_replaced_it(session):
|
||||
"""`no such tool` alone reads as a broken server rather than a moved surface."""
|
||||
|
||||
fake, connected = session()
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.call_tool("session_list", {})
|
||||
|
||||
result = run(go)
|
||||
assert result.isError is True
|
||||
text = result.content[0].text
|
||||
assert "It is a RESOURCE now" in text
|
||||
assert "hhstream://sessions" in text
|
||||
assert fake.calls == []
|
||||
|
||||
|
||||
def test_a_tool_that_does_not_exist_names_the_ones_that_do(session):
|
||||
"""And is an error. The SDK turns a raised McpError into this shape anyway."""
|
||||
|
||||
fake, connected = session()
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.call_tool("session_detonate", {})
|
||||
|
||||
result = run(go)
|
||||
assert result.isError is True
|
||||
assert "no such tool: 'session_detonate'" in result.content[0].text
|
||||
assert "session_touch" in result.content[0].text
|
||||
assert fake.calls == []
|
||||
|
||||
|
||||
def test_a_handler_that_raises_is_reported_to_the_agent_and_not_only_logged():
|
||||
"""A CLI process would have died with a traceback and status 1; so does this."""
|
||||
|
||||
fake = mcp_fake.FakeCli(raises=RuntimeError("the broker said something odd"))
|
||||
result = server.call(invoke.Runner(fake), "session_gc", {})
|
||||
|
||||
assert result.isError is True
|
||||
assert result.structuredContent["exit_code"] == invoke.GENERIC_FAILURE
|
||||
assert "the broker said something odd" in result.content[0].text
|
||||
|
||||
|
||||
def test_the_transport_is_moved_off_the_descriptor_the_cli_prints_to():
|
||||
"""The one thing an in-process CLI call could break, asserted directly."""
|
||||
|
||||
read_fd, write_fd = os.pipe()
|
||||
saved_out, saved_err = os.dup(1), os.dup(2)
|
||||
log_read, log_write = os.pipe()
|
||||
try:
|
||||
os.dup2(write_fd, 1)
|
||||
os.dup2(log_write, 2)
|
||||
_, stdout = server.claim_transport()
|
||||
# After claiming, this process's own stdout is the log (fd 2), not the
|
||||
# stream the client reads.
|
||||
assert os.path.sameopenfile(1, 2)
|
||||
assert not os.path.sameopenfile(1, stdout.wrapped.fileno())
|
||||
# ...and stdin cannot eat a request.
|
||||
assert os.readlink(f"/proc/self/fd/0") == os.devnull
|
||||
finally:
|
||||
os.dup2(saved_out, 1)
|
||||
os.dup2(saved_err, 2)
|
||||
for fd in (saved_out, saved_err, read_fd, write_fd, log_read, log_write):
|
||||
try:
|
||||
os.close(fd)
|
||||
except OSError:
|
||||
pass
|
||||
|
||||
|
||||
def test_the_listing_is_what_the_entry_point_prints(capsys):
|
||||
"""`--list-tools` is the package's own install check; keep it honest."""
|
||||
|
||||
assert server.main(["--list-tools"]) == 0
|
||||
printed = capsys.readouterr().out.splitlines()
|
||||
assert len(printed) == len(tools.TOOLS)
|
||||
assert printed[0].split("\t")[0] == tools.TOOLS[0].name
|
||||
|
||||
|
||||
def test_the_entry_point_lists_resources_too(capsys):
|
||||
assert server.main(["--list-resources"]) == 0
|
||||
printed = capsys.readouterr().out.splitlines()
|
||||
assert len(printed) == len(resources.ENTRIES)
|
||||
assert printed[0].split("\t")[0] == "hhstream://status"
|
||||
|
||||
|
||||
def test_the_entry_point_s_listing_honours_a_toolset_selection(capsys):
|
||||
assert server.main(["--list-tools", "--toolsets", "keyboard"]) == 0
|
||||
printed = capsys.readouterr().out.splitlines()
|
||||
assert [line.split("\t")[0] for line in printed] == list(
|
||||
tools.TOOLSETS["keyboard"]
|
||||
)
|
||||
|
||||
|
||||
def test_an_unknown_toolset_on_the_command_line_is_argparse_s_exit_two(capsys):
|
||||
with pytest.raises(SystemExit) as caught:
|
||||
server.main(["--list-tools", "--toolsets", "mouse"])
|
||||
assert caught.value.code == 2
|
||||
assert "no such toolset" in capsys.readouterr().err
|
||||
|
||||
|
||||
def test_an_empty_toolset_list_is_refused_rather_than_read_as_all(capsys):
|
||||
"""`--toolsets ""` is a mistake, and serving everything would hide it."""
|
||||
|
||||
with pytest.raises(SystemExit) as caught:
|
||||
server.main(["--list-tools", "--toolsets", " , "])
|
||||
assert caught.value.code == 2
|
||||
|
||||
|
||||
# ── resources, over the protocol ───────────────────────────────────────────
|
||||
|
||||
|
||||
def test_resources_list_returns_the_fixed_ones_with_their_descriptions(session):
|
||||
_, connected = session()
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.list_resources()
|
||||
|
||||
listed = run(go).resources
|
||||
assert {str(r.uri) for r in listed} == {e.uri for e in resources.FIXED}
|
||||
for resource in listed:
|
||||
assert resource.title and resource.description and resource.mimeType
|
||||
|
||||
|
||||
def test_resource_templates_are_listed_separately_with_their_parameters(session):
|
||||
_, connected = session()
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.list_resource_templates()
|
||||
|
||||
listed = run(go).resourceTemplates
|
||||
assert {t.uriTemplate for t in listed} == {e.uri_template for e in resources.TEMPLATES}
|
||||
logs = next(t for t in listed if t.uriTemplate.endswith("/logs{?lines}"))
|
||||
assert logs.name == "session-logs"
|
||||
|
||||
|
||||
def test_reading_a_json_resource_returns_the_broker_s_object(session):
|
||||
reply = {"ok": True, "sessions": [{"id": "s-1", "state": "running"}]}
|
||||
fake, connected = session(stdout=json.dumps(reply, indent=2))
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.read_resource(AnyUrl("hhstream://sessions"))
|
||||
|
||||
result = run(go)
|
||||
assert len(result.contents) == 1
|
||||
content = result.contents[0]
|
||||
assert content.mimeType == "application/json"
|
||||
assert json.loads(content.text) == reply
|
||||
assert fake.calls == [["session", "list", "--json"]]
|
||||
|
||||
|
||||
def test_reading_a_template_passes_the_capture_and_the_query_through(session):
|
||||
fake, connected = session(stdout=mcp_fake.reply(ok=True, lines=[]))
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.read_resource(
|
||||
AnyUrl("hhstream://sessions/foot-abc/logs?lines=7")
|
||||
)
|
||||
|
||||
run(go)
|
||||
assert fake.calls == [
|
||||
["session", "logs", "--json", "--lines=7", "--", "foot-abc"]
|
||||
]
|
||||
|
||||
|
||||
def test_reading_a_frame_resource_returns_a_blob_not_text(session):
|
||||
frame = mcp_fake.png(width=48, height=24)
|
||||
_, connected = session(write_png=frame)
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.read_resource(AnyUrl("hhstream://screen"))
|
||||
|
||||
content = run(go).contents[0]
|
||||
assert isinstance(content, types.BlobResourceContents)
|
||||
assert content.mimeType == "image/png"
|
||||
|
||||
import base64
|
||||
|
||||
assert base64.b64decode(content.blob) == frame
|
||||
|
||||
|
||||
def test_a_refused_read_is_a_protocol_error_carrying_the_remedy(session):
|
||||
"""A resource read has no `isError`, so the refusal has to be an error."""
|
||||
|
||||
from mcp.shared.exceptions import McpError
|
||||
|
||||
fake, connected = session(
|
||||
stderr=mcp_fake.reply(ok=False, error="no_such_session", reason="no session 'nope'"),
|
||||
exit_code=int(ExitCode.NO_SUCH_SESSION),
|
||||
)
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
with pytest.raises(McpError) as caught:
|
||||
await client.read_resource(AnyUrl("hhstream://sessions/nope"))
|
||||
return caught.value
|
||||
|
||||
error = run(go)
|
||||
assert "exit 3 (NO_SUCH_SESSION)" in str(error)
|
||||
assert "no session 'nope'" in str(error)
|
||||
|
||||
|
||||
def test_a_uri_that_names_no_resource_is_a_protocol_error(session):
|
||||
from mcp.shared.exceptions import McpError
|
||||
|
||||
fake, connected = session()
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
with pytest.raises(McpError) as caught:
|
||||
await client.read_resource(AnyUrl("hhstream://nonsense"))
|
||||
return caught.value
|
||||
|
||||
error = run(go)
|
||||
assert "no resource at" in str(error)
|
||||
assert fake.calls == []
|
||||
|
||||
|
||||
# ── toolsets, over the protocol ────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_a_toolset_selection_narrows_the_listing_but_not_the_resources(session):
|
||||
_, connected = session(toolsets=["keyboard"])
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.list_tools(), await client.list_resources()
|
||||
|
||||
listed, resource_list = run(go)
|
||||
assert [t.name for t in listed.tools] == list(tools.TOOLSETS["keyboard"])
|
||||
# Resources are the host's context, not the model's tool budget.
|
||||
assert len(resource_list.resources) == len(resources.FIXED)
|
||||
|
||||
|
||||
def test_a_tool_outside_the_selection_cannot_be_called_by_name(session):
|
||||
"""Unlisted must mean unreachable, or the selection is cosmetic."""
|
||||
|
||||
fake, connected = session(toolsets=["keyboard"])
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.call_tool("session_kill", {"id": "s-1"})
|
||||
|
||||
result = run(go)
|
||||
assert result.isError is True
|
||||
text = result.content[0].text
|
||||
assert "session_kill" in text
|
||||
assert "without its toolset" in text
|
||||
assert fake.calls == []
|
||||
|
||||
|
||||
def test_content_for_a_text_only_result_has_no_image_block():
|
||||
blocks = server.content_for(tools.Result(text="hello"))
|
||||
assert [block.type for block in blocks] == ["text"]
|
||||
assert isinstance(blocks[0], types.TextContent)
|
||||
@@ -0,0 +1,603 @@
|
||||
"""The tool table: the argv each tool builds, and what it makes of the answer.
|
||||
|
||||
The subject is the shim and nothing else. Every test here drives a tool
|
||||
through :class:`hhstream_mcp.invoke.Runner` with a recording stand-in
|
||||
(:class:`mcp_fake.FakeCli`) where the CLI goes, and asserts on the argv it was
|
||||
handed -- which is the only thing this layer actually decides.
|
||||
|
||||
Nothing in this file imports the MCP SDK: the table is standard library by
|
||||
design, so an argv bug is findable without a protocol stack. The SDK wiring is
|
||||
``test_mcp_server.py``, and the real CLI entry point is exercised in
|
||||
``test_mcp_invoke.py``.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import signal
|
||||
|
||||
import mcp_fake
|
||||
import pytest
|
||||
from hhstreamd.protocol import ExitCode
|
||||
from hhstream_mcp import invoke, tools
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def _isolated(monkeypatch, tmp_path):
|
||||
mcp_fake.isolate(monkeypatch, tmp_path)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def call():
|
||||
"""`call("session_touch", {"id": "s-1"})` -> (Result, [argv, ...])."""
|
||||
|
||||
def _call(name, arguments, **script):
|
||||
fake = mcp_fake.FakeCli(**script)
|
||||
result = tools.BY_NAME[name].invoke(invoke.Runner(fake), arguments)
|
||||
return result, fake.calls
|
||||
|
||||
return _call
|
||||
|
||||
|
||||
# ── the surface is all there ───────────────────────────────────────────────
|
||||
|
||||
#: Every tool `docs/CONTRACT-mcp.md` §3 freezes. Written out rather than derived
|
||||
#: from the table, because a list derived from the thing it checks cannot
|
||||
#: notice a missing entry.
|
||||
EXPECTED = {
|
||||
# frames -- capturing is an act at a moment, so these stay tools
|
||||
"shot", "record", "run",
|
||||
# lifecycle. The read-only verbs are resources; see MOVED_TO_RESOURCES.
|
||||
"session_start", "session_touch", "session_kill", "session_gc",
|
||||
"session_adopt", "session_container", "session_reconcile",
|
||||
# pointer
|
||||
"pointer_acquire", "pointer_move", "pointer_click", "pointer_scroll",
|
||||
"pointer_down", "pointer_up", "pointer_release",
|
||||
# keyboard
|
||||
"keyboard_type", "keyboard_key", "keyboard_down", "keyboard_up",
|
||||
}
|
||||
|
||||
#: Verbs that are resources now and must NOT come back as tools. Named, not
|
||||
#: merely absent, so re-adding one is a failure rather than a silent widening
|
||||
#: of the surface mcp-v2 narrowed.
|
||||
MOVED_TO_RESOURCES = {
|
||||
"status",
|
||||
"session_list",
|
||||
"session_status",
|
||||
"session_logs",
|
||||
"pointer_state",
|
||||
}
|
||||
|
||||
|
||||
def test_the_acting_verbs_are_tools_and_nothing_else_is():
|
||||
assert set(tools.BY_NAME) == EXPECTED
|
||||
assert len(tools.TOOLS) == 21
|
||||
|
||||
|
||||
def test_the_read_only_verbs_are_not_tools():
|
||||
"""They are `hhstream://…` resources: the host's context, not the model's acts."""
|
||||
|
||||
assert MOVED_TO_RESOURCES.isdisjoint(set(tools.BY_NAME))
|
||||
# ...and the table that says where each one went covers exactly those five,
|
||||
# so a caller holding a v1 name can be told rather than just refused.
|
||||
assert set(tools.MOVED_TO_RESOURCES) == MOVED_TO_RESOURCES
|
||||
for uri in tools.MOVED_TO_RESOURCES.values():
|
||||
assert uri.startswith("hhstream://")
|
||||
|
||||
|
||||
def test_session_container_stayed_a_tool_because_it_writes():
|
||||
"""With an id the CLI runs `container.reconcile`, so it is not a read."""
|
||||
|
||||
assert "session_container" in tools.BY_NAME
|
||||
assert not tools.BY_NAME["session_container"].read_only
|
||||
assert "write" in tools.BY_NAME["session_container"].description
|
||||
|
||||
|
||||
def test_the_table_is_ordered_and_has_no_duplicate_names():
|
||||
names = [tool.name for tool in tools.TOOLS]
|
||||
assert len(names) == len(set(names))
|
||||
assert isinstance(tools.TOOLS, tuple)
|
||||
|
||||
|
||||
def test_only_the_verbs_that_read_are_marked_read_only():
|
||||
"""One left, now that the rest of the reads are resources."""
|
||||
|
||||
read_only = {tool.name for tool in tools.TOOLS if tool.read_only}
|
||||
assert read_only == {"shot"}
|
||||
# `record` writes a file, so it is not read-only either.
|
||||
assert not tools.BY_NAME["record"].read_only
|
||||
assert tools.BY_NAME["session_kill"].destructive
|
||||
assert [t.name for t in tools.TOOLS if t.destructive] == ["session_kill"]
|
||||
|
||||
|
||||
# ── the two rules an agent gets wrong ──────────────────────────────────────
|
||||
|
||||
#: The tools the CLI's own note names as NOT counting as activity. The others
|
||||
#: it names are resources now, and `test_mcp_resources.py` holds those.
|
||||
NON_ACTIVITY = {
|
||||
"session_gc",
|
||||
"session_container",
|
||||
"session_reconcile",
|
||||
}
|
||||
|
||||
GESTURES = {
|
||||
"pointer_move",
|
||||
"pointer_click",
|
||||
"pointer_scroll",
|
||||
"pointer_down",
|
||||
"pointer_up",
|
||||
"pointer_release",
|
||||
"keyboard_type",
|
||||
"keyboard_key",
|
||||
"keyboard_down",
|
||||
"keyboard_up",
|
||||
}
|
||||
|
||||
#: The four families `--toolsets` selects from.
|
||||
FAMILIES = ("frames", "sessions", "pointer", "keyboard")
|
||||
|
||||
|
||||
def test_the_idle_clock_rule_is_on_every_tool_that_does_not_reset_it():
|
||||
for name in NON_ACTIVITY | GESTURES | {"session_start", "session_touch", "pointer_acquire"}:
|
||||
description = tools.BY_NAME[name].description
|
||||
assert tools.ACTIVITY_NOTE in description, f"{name} does not carry the activity rule"
|
||||
|
||||
|
||||
def test_the_idle_clock_rule_names_touch_as_the_only_mark_of_activity():
|
||||
assert "`session_touch` is the ONLY thing" in tools.ACTIVITY_NOTE
|
||||
# It has to name the *resources* now, because that is where reading moved:
|
||||
# an agent told "listing does not count" cannot act on it if the thing it
|
||||
# is listing with is no longer called `session_list`.
|
||||
for named in ("hhstream://sessions", "session_gc", "pointer or keyboard tool"):
|
||||
assert named in tools.ACTIVITY_NOTE
|
||||
assert "does NOT count" in tools.ACTIVITY_NOTE
|
||||
|
||||
|
||||
def test_the_cli_still_owns_the_rule_this_wording_restates():
|
||||
"""A tripwire, not a duplication.
|
||||
|
||||
`tools.ACTIVITY_NOTE` and `tools.LEASE_NOTE` are the CLI's two epilogues
|
||||
said in terms of tools. If the CLI's constants are renamed or stop saying
|
||||
what they say, these notes have silently become this server's own opinion --
|
||||
so the originals are asserted to still exist and still carry the rule.
|
||||
"""
|
||||
|
||||
import hhstream_session
|
||||
|
||||
assert "ONLY" in hhstream_session.ACTIVITY_NOTE
|
||||
assert "touch" in hhstream_session.ACTIVITY_NOTE
|
||||
assert "no 'keyboard acquire'" in hhstream_session.KEYBOARD_LEASE_NOTE
|
||||
|
||||
|
||||
def test_every_keyboard_tool_says_it_needs_the_pointer_lease():
|
||||
for name in ("keyboard_type", "keyboard_key", "keyboard_down", "keyboard_up"):
|
||||
description = tools.BY_NAME[name].description
|
||||
assert tools.LEASE_NOTE in description, f"{name} does not carry the lease rule"
|
||||
assert "POINTER lease" in tools.LEASE_NOTE
|
||||
assert "exit 9" in tools.LEASE_NOTE
|
||||
assert "`pointer_acquire`" in tools.LEASE_NOTE
|
||||
assert "There is no keyboard lease" in tools.LEASE_NOTE
|
||||
assert "only while it holds" in tools.LEASE_NOTE
|
||||
|
||||
|
||||
def test_holding_a_non_modifier_is_warned_about_where_it_can_happen():
|
||||
assert tools.HOLD_NOTE in tools.BY_NAME["keyboard_down"].description
|
||||
assert "FLOODS THE WINDOW" in tools.HOLD_NOTE
|
||||
assert "the APPLICATION does the repeating" in tools.HOLD_NOTE
|
||||
|
||||
|
||||
def test_the_lease_is_a_required_argument_on_every_gesture_and_is_never_cached():
|
||||
for name in GESTURES:
|
||||
schema = tools.BY_NAME[name].schema
|
||||
assert "lease" in schema["required"], f"{name} does not require a lease"
|
||||
# ...and acquire is the one that hands it out, so it must not require one.
|
||||
assert "lease" not in tools.BY_NAME["pointer_acquire"].schema.get("required", [])
|
||||
|
||||
|
||||
# ── toolsets ───────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_every_tool_is_in_exactly_one_toolset():
|
||||
"""Or `--toolsets` would be able to hide a tool nobody could ask for."""
|
||||
|
||||
assert tuple(tools.TOOLSETS) == FAMILIES
|
||||
seen: list[str] = []
|
||||
for family in FAMILIES:
|
||||
seen.extend(tools.TOOLSETS[family])
|
||||
assert len(seen) == len(set(seen)), "a tool is in two toolsets"
|
||||
assert set(seen) == set(tools.BY_NAME), "a tool is in no toolset"
|
||||
|
||||
|
||||
def test_no_toolset_named_is_every_tool():
|
||||
"""The default, and what an unconfigured client gets."""
|
||||
|
||||
assert tools.selected(None) == tools.TOOLS
|
||||
|
||||
|
||||
def test_a_selection_keeps_the_table_s_own_order():
|
||||
"""So a listing does not reshuffle because of how the flag was written."""
|
||||
|
||||
chosen = [tool.name for tool in tools.selected(["keyboard", "frames"])]
|
||||
assert chosen == ["shot", "record", "run", "keyboard_type", "keyboard_key",
|
||||
"keyboard_down", "keyboard_up"]
|
||||
|
||||
|
||||
def test_a_repeated_family_is_not_a_repeated_tool():
|
||||
assert tools.selected(["frames", "frames"]) == tools.selected(["frames"])
|
||||
|
||||
|
||||
def test_an_unknown_family_is_refused_and_names_the_known_ones():
|
||||
"""Not skipped: a typo that served nothing would look like an empty server."""
|
||||
|
||||
with pytest.raises(tools.UnknownToolset) as caught:
|
||||
tools.selected(["frames", "mouse"])
|
||||
assert "'mouse'" in str(caught.value)
|
||||
for family in FAMILIES:
|
||||
assert family in str(caught.value)
|
||||
|
||||
|
||||
def test_every_schema_refuses_an_argument_this_server_would_drop():
|
||||
for tool in tools.TOOLS:
|
||||
assert tool.schema["additionalProperties"] is False, tool.name
|
||||
assert tool.schema["type"] == "object"
|
||||
|
||||
|
||||
# ── the argv each tool builds ──────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_a_session_verb_is_run_with_json_and_its_id_after_a_separator(call):
|
||||
_, calls = call("session_touch", {"id": "s-1"})
|
||||
assert calls == [["session", "touch", "--json", "--", "s-1"]]
|
||||
|
||||
|
||||
def test_omitted_arguments_become_no_flag_at_all(call):
|
||||
"""A flag left off is the broker's own default; this layer must not supply one."""
|
||||
|
||||
_, calls = call("session_gc", {})
|
||||
assert calls == [["session", "gc", "--json"]]
|
||||
_, calls = call("session_gc", {"request_id": "r-1"})
|
||||
assert calls == [["session", "gc", "--json", "--request-id=r-1"]]
|
||||
_, calls = call("session_reconcile", {})
|
||||
assert calls == [["session", "reconcile", "--json"]]
|
||||
|
||||
|
||||
def test_start_passes_the_application_argv_after_one_separator(call):
|
||||
_, calls = call(
|
||||
"session_start",
|
||||
{
|
||||
"app": "chromium",
|
||||
"argv": ["--new-window", "https://example.invalid"],
|
||||
"idle_timeout": "5m",
|
||||
"wait_ready": "30s",
|
||||
"request_id": "req-7",
|
||||
},
|
||||
)
|
||||
assert calls == [
|
||||
[
|
||||
"session", "start", "--json",
|
||||
"--idle-timeout=5m",
|
||||
"--wait-ready=30s",
|
||||
"--request-id=req-7",
|
||||
"--",
|
||||
"chromium",
|
||||
"--new-window",
|
||||
"https://example.invalid",
|
||||
]
|
||||
]
|
||||
|
||||
|
||||
def test_an_application_argument_that_looks_like_a_flag_is_not_eaten(call):
|
||||
"""The `--` is what makes `--new-window` the application's and not the CLI's."""
|
||||
|
||||
_, calls = call("session_start", {"app": "foot", "argv": ["--help"]})
|
||||
assert calls[0] == ["session", "start", "--json", "--", "foot", "--help"]
|
||||
|
||||
|
||||
def test_an_ephemeral_home_is_a_switch_and_a_home_is_a_value(call):
|
||||
_, calls = call("session_start", {"app": "foot", "ephemeral_home": True})
|
||||
assert "--ephemeral-home" in calls[0]
|
||||
_, calls = call("session_start", {"app": "foot", "home": "/tmp/h"})
|
||||
assert "--home=/tmp/h" in calls[0]
|
||||
|
||||
|
||||
def test_a_coordinate_pair_is_sent_in_the_cli_s_own_x_comma_y_form(call):
|
||||
_, calls = call("pointer_move", {"id": "s-1", "lease": "L", "to": [0.25, 0.75]})
|
||||
assert calls == [["session", "pointer", "move", "--json", "--lease=L", "--to=0.25,0.75", "--", "s-1"]]
|
||||
|
||||
|
||||
def test_a_negative_delta_stays_one_token_so_argparse_cannot_read_it_as_a_flag(call):
|
||||
_, calls = call("pointer_move", {"id": "s-1", "lease": "L", "by": [-0.1, 0.5]})
|
||||
assert calls[0][5] == "--by=-0.1,0.5"
|
||||
|
||||
|
||||
def test_a_coordinate_is_not_rounded_on_the_way_through(call):
|
||||
"""A caller that computed a number deserves the broker's verdict on it."""
|
||||
|
||||
_, calls = call("pointer_move", {"id": "s-1", "lease": "L", "to": [1 / 3, 0.0]})
|
||||
assert calls[0][5] == f"--to={1 / 3!r},0.0"
|
||||
|
||||
|
||||
def test_a_negative_scroll_amount_stays_one_token(call):
|
||||
_, calls = call("pointer_scroll", {"id": "s-1", "lease": "L", "amount": -3, "axis": "horizontal"})
|
||||
assert calls[0] == [
|
||||
"session", "pointer", "scroll", "--json",
|
||||
"--lease=L", "--axis=horizontal", "--amount=-3.0", "--", "s-1",
|
||||
]
|
||||
|
||||
|
||||
def test_a_typed_string_is_one_positional_after_the_separator(call):
|
||||
text = "--not-a-flag\nsecond line\twith a tab"
|
||||
_, calls = call("keyboard_type", {"id": "s-1", "lease": "L", "text": text})
|
||||
assert calls == [["session", "keyboard", "type", "--json", "--lease=L", "--", "s-1", text]]
|
||||
|
||||
|
||||
def test_a_keysym_name_is_passed_through_untouched(call):
|
||||
_, calls = call("keyboard_key", {"id": "s-1", "lease": "L", "name": "BackSpace"})
|
||||
assert calls[0][-1] == "BackSpace"
|
||||
|
||||
|
||||
def test_adopt_sends_the_pid_as_a_flag_because_the_cli_requires_it(call):
|
||||
_, calls = call("session_adopt", {"pid": 4242, "app": "chromium"})
|
||||
assert calls == [["session", "adopt", "--json", "--pid=4242", "--app=chromium"]]
|
||||
|
||||
|
||||
def test_container_with_no_id_lists_and_with_an_id_reconciles(call):
|
||||
_, calls = call("session_container", {})
|
||||
assert calls == [["session", "container", "--json"]]
|
||||
_, calls = call("session_container", {"id": "s-1"})
|
||||
assert calls == [["session", "container", "--json", "--", "s-1"]]
|
||||
|
||||
|
||||
# ── what each tool makes of the answer ─────────────────────────────────────
|
||||
|
||||
|
||||
def test_a_successful_session_verb_passes_the_protocol_object_through(call):
|
||||
reply = {"ok": True, "pruned": 2, "sessions": [{"id": "s-1"}]}
|
||||
result, _ = call("session_gc", {}, stdout=json.dumps(reply, indent=2))
|
||||
|
||||
assert not result.is_error
|
||||
assert result.data == reply
|
||||
# The text is the CLI's own stdout: a shim that re-rendered it would be
|
||||
# inventing a second format for the same facts.
|
||||
assert json.loads(result.text) == reply
|
||||
|
||||
|
||||
def test_acquire_puts_the_lease_id_where_the_next_call_will_look(call):
|
||||
reply = {"ok": True, "id": "s-1", "lease_id": "lease-abc", "bookmark": {"output": "hh-s-1"}}
|
||||
result, _ = call("pointer_acquire", {"id": "s-1"}, stdout=json.dumps(reply, indent=2))
|
||||
|
||||
assert result.data == reply
|
||||
assert result.text.startswith("lease_id: lease-abc")
|
||||
assert "pointer_release" in result.text
|
||||
|
||||
|
||||
def test_start_puts_the_new_session_id_first_and_names_the_idle_clock(call):
|
||||
reply = {"ok": True, "id": "s-9", "state": "running"}
|
||||
result, _ = call("session_start", {"app": "foot"}, stdout=json.dumps(reply, indent=2))
|
||||
|
||||
assert result.text.startswith("session id: s-9")
|
||||
assert "session_touch" in result.text
|
||||
|
||||
|
||||
def test_a_refusal_is_an_error_and_never_a_success(call):
|
||||
reply = {
|
||||
"ok": False,
|
||||
"error": "no_lease",
|
||||
"reason": "no pointer lease for s-1 on this socket",
|
||||
"hint": "run 'pointer acquire s-1' first",
|
||||
}
|
||||
result, _ = call(
|
||||
"pointer_click",
|
||||
{"id": "s-1", "lease": "stale"},
|
||||
stderr=json.dumps(reply, indent=2),
|
||||
exit_code=int(ExitCode.NO_LEASE),
|
||||
)
|
||||
|
||||
assert result.is_error
|
||||
assert result.data["ok"] is False
|
||||
assert result.data["exit_code"] == int(ExitCode.NO_LEASE)
|
||||
# The remedy first, then the broker's own words: an agent needs to know what
|
||||
# to do before it needs to know what was said.
|
||||
assert result.text.startswith("exit 9 (NO_LEASE)")
|
||||
assert "pointer_acquire" in result.text
|
||||
assert "error: no_lease" in result.text
|
||||
assert "no pointer lease for s-1" in result.text
|
||||
|
||||
|
||||
def test_the_contended_lease_case_names_the_holder_and_does_not_say_acquire(call):
|
||||
reply = {"ok": False, "error": "pointer_busy", "reason": "held by s-other"}
|
||||
result, _ = call(
|
||||
"pointer_acquire",
|
||||
{"id": "s-1"},
|
||||
stderr=json.dumps(reply, indent=2),
|
||||
exit_code=int(ExitCode.BUSY),
|
||||
)
|
||||
|
||||
assert result.is_error
|
||||
assert result.text.startswith("exit 8 (BUSY)")
|
||||
assert "hhstream://pointer" in result.text
|
||||
assert "s-other" in result.text
|
||||
|
||||
|
||||
def test_a_usage_refusal_from_argparse_itself_is_still_an_error(call):
|
||||
"""Exit 2 with no JSON anywhere -- argparse wrote prose to stderr."""
|
||||
|
||||
result, _ = call(
|
||||
"pointer_click",
|
||||
{"id": "s-1", "lease": "L", "button": "left"},
|
||||
stderr="usage: hhstream session pointer click ...\nerror: argument --button: invalid choice\n",
|
||||
exit_code=int(ExitCode.USAGE),
|
||||
)
|
||||
|
||||
assert result.is_error
|
||||
assert result.data["exit_code"] == int(ExitCode.USAGE)
|
||||
assert "invalid choice" in result.text
|
||||
|
||||
|
||||
def test_a_broker_that_is_down_is_reported_as_the_operator_s_problem(call):
|
||||
result, _ = call(
|
||||
"session_gc",
|
||||
{},
|
||||
stderr="error: cannot reach the hhstream session daemon at /run/hhstream/control.sock\n",
|
||||
exit_code=int(ExitCode.DAEMON_UNREACHABLE),
|
||||
)
|
||||
|
||||
assert result.is_error
|
||||
assert "HHSTREAM_SOCKET" in result.text
|
||||
assert "frame tools" in result.text
|
||||
|
||||
|
||||
# ── shot and record ────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_shot_captures_to_a_file_and_returns_the_bytes_with_the_geometry(call):
|
||||
frame = mcp_fake.png(width=320, height=180)
|
||||
result, calls = call("shot", {}, write_png=frame, stdout="/tmp/ignored.png\n")
|
||||
|
||||
assert len(calls) == 1
|
||||
verb, out = calls[0][0], calls[0][1]
|
||||
assert verb == "shot"
|
||||
assert out.startswith("--out=")
|
||||
# The temporary directory is gone, so the file cannot be read twice: the
|
||||
# bytes are in the reply or they are nowhere.
|
||||
assert result.image == frame
|
||||
assert result.media_type == "image/png"
|
||||
assert "320x180 image/png" in result.text
|
||||
assert result.data["width"] == 320
|
||||
|
||||
|
||||
def test_shot_of_one_output_names_it_in_the_argv_and_in_the_reply(call):
|
||||
result, calls = call("shot", {"output": "hh-s-1"}, write_png=mcp_fake.png())
|
||||
assert "--output=hh-s-1" in calls[0]
|
||||
assert "output 'hh-s-1'" in result.text
|
||||
assert result.data["output"] == "hh-s-1"
|
||||
|
||||
|
||||
def test_shot_tells_the_truth_about_a_format_it_cannot_read(call):
|
||||
result, _ = call("shot", {}, write_png=b"GIF89a-not-an-image")
|
||||
|
||||
assert not result.is_error
|
||||
assert result.image is None
|
||||
assert "does not recognise" in result.text
|
||||
|
||||
|
||||
def test_shot_does_not_claim_an_image_when_the_cli_wrote_no_file(call):
|
||||
"""Exit 0 and no artefact is still a failure; the alternative is a lie."""
|
||||
|
||||
result, _ = call("shot", {}, stdout="/tmp/somewhere.png\n")
|
||||
|
||||
assert result.is_error
|
||||
assert result.data["error"] == "no_artifact"
|
||||
|
||||
|
||||
def test_shot_passes_a_refusal_through_without_reading_a_file(call):
|
||||
result, _ = call(
|
||||
"shot",
|
||||
{"output": "hh-gone"},
|
||||
stderr="hhstream: could not capture output 'hh-gone': unknown output\n",
|
||||
exit_code=1,
|
||||
)
|
||||
|
||||
assert result.is_error
|
||||
assert result.image is None
|
||||
assert "unknown output" in result.text
|
||||
|
||||
|
||||
def test_record_returns_the_path_and_the_measured_rate_not_the_video(call):
|
||||
destination = "/tmp/hhstream-mcp/clip.mp4"
|
||||
result, calls = call(
|
||||
"record",
|
||||
{"seconds": 3, "out": destination},
|
||||
stdout=f"{destination} (28 frames in 3.01s -> 9 fps)\n",
|
||||
)
|
||||
|
||||
assert calls[0] == ["record", f"--out={destination}", "--seconds=3"]
|
||||
assert result.image is None
|
||||
assert result.data == {
|
||||
"ok": True,
|
||||
"path": destination,
|
||||
"frames": 28,
|
||||
"seconds": 3.01,
|
||||
"fps": 9,
|
||||
}
|
||||
assert "measured 9 fps" in result.text
|
||||
|
||||
|
||||
def test_record_without_a_destination_generates_one_and_names_it(call):
|
||||
result, calls = call("record", {}, stdout="/x (1 frames in 1.00s -> 1 fps)\n")
|
||||
flag = next(a for a in calls[0] if a.startswith("--out="))
|
||||
assert "hhstream-mcp" in flag
|
||||
assert flag.endswith(".mp4")
|
||||
assert result.data["ok"] is True
|
||||
|
||||
|
||||
def test_record_of_one_output_passes_the_rate_target_through(call):
|
||||
_, calls = call(
|
||||
"record",
|
||||
{"seconds": 2, "output": "hh-s-1", "fps": 4, "keep": True, "work_dir": "/tmp/w"},
|
||||
stdout="/x (8 frames in 2.00s -> 4 fps)\n",
|
||||
)
|
||||
# The generated --out is asserted by the test above; what matters here is
|
||||
# the order and form of everything after it.
|
||||
assert calls[0][0] == "record"
|
||||
assert calls[0][2:] == [
|
||||
"--seconds=2",
|
||||
"--output=hh-s-1",
|
||||
"--fps=4",
|
||||
"--work-dir=/tmp/w",
|
||||
"--keep",
|
||||
]
|
||||
|
||||
|
||||
# ── run ────────────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_run_reports_the_application_s_pid_and_that_it_is_unmanaged(wayland):
|
||||
result = tools.BY_NAME["run"].invoke(
|
||||
invoke.Runner(), {"argv": ["sleep", "30"], "settle_s": 0.3}
|
||||
)
|
||||
try:
|
||||
assert not result.is_error
|
||||
assert result.data["managed"] is False
|
||||
assert result.data["pid"] > 0
|
||||
assert result.data["argv"] == ["sleep", "30"]
|
||||
# The tool's own words have to point at the managed alternative, or an
|
||||
# agent reaches for `run` because it is the shorter name.
|
||||
assert "session_start" in result.text
|
||||
assert "UNMANAGED" in result.text
|
||||
finally:
|
||||
import contextlib
|
||||
|
||||
with contextlib.suppress(ProcessLookupError):
|
||||
os.kill(result.data["pid"], signal.SIGTERM)
|
||||
|
||||
|
||||
def test_run_reports_a_launch_that_failed_immediately_as_an_error(wayland):
|
||||
result = tools.BY_NAME["run"].invoke(
|
||||
invoke.Runner(),
|
||||
{"argv": ["sh", "-c", "echo 'cannot open display' >&2; exit 1"], "settle_s": 5.0},
|
||||
)
|
||||
|
||||
assert result.is_error
|
||||
assert result.data["error"] == "run_exited"
|
||||
assert "cannot open display" in result.text
|
||||
assert "nothing is on" in result.text
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def wayland(workdir, monkeypatch):
|
||||
"""A runtime directory the CLI's `env_for_session` accepts.
|
||||
|
||||
A real AF_UNIX socket, because that function checks `is_socket()`, and the
|
||||
suite's short-pathed `workdir` because an AF_UNIX address is capped near
|
||||
108 bytes.
|
||||
"""
|
||||
|
||||
import socket
|
||||
|
||||
listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
||||
listener.bind(str(workdir / "wayland-0"))
|
||||
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(workdir / "stream.sock"))
|
||||
yield workdir
|
||||
listener.close()
|
||||
Reference in new issue
Block a user