feat(cli): session stream and start --stream
The operator's side of the four verbs: `hhstream session stream enable|disable|list|status`, and `start --stream [--stream-phrase] [--stream-fps]` for the one-call case. `stream enable` prints the URL on **stdout and nothing else**, with the detail on stderr, so `url=$(hhstream session stream enable ID)` works -- the same shape `start` already has for the session id. `start --stream` prints the id and then the URL, two lines, because a caller who asked for both should not have to run a second verb for the second one. The phrase is a credential, and the two renderers disagree on purpose: * `render_streams` (`stream list`) does **not** show it. A listing is what ends up in a shared terminal, a paste or a screenshot, so what it shows is enough to recognise and manage a stream -- session, output, rate, viewers, `LIVE` -- and not enough to watch one. It also prints the daemon's reachability, because "two records and no daemon" is a different situation from "two records and two captures" and the rows alone cannot say which. * `render_stream` (`stream status ID`) does show the URL. That question was asked about one session by name, which is what somebody about to watch it does, and making them reach for `--json` for the thing the verb is for would be the worse trade. When the daemon is not publishing, `status` says so and prints no URL -- the phrase is kept, so re-enabling restores the same one. `start --stream` that starts the session but cannot open the stream exits 0 and says `WARNING: the session is running but its stream was not enabled: …` on stderr. Loudly, because the exit code is the session's and a caller who asked for a stream must not read a 0 as one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
This commit is contained in:
1 parent
7d8ca6191b
commit
850f9caa1d
2 files changed
+333
No files matched your search
@@ -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.
|
||||
|
||||
|
||||
Reference in new issue
Block a user