diff --git a/src/hhstream_session/__init__.py b/src/hhstream_session/__init__.py index db35def..cb18495 100644 --- a/src/hhstream_session/__init__.py +++ b/src/hhstream_session/__init__.py @@ -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 `` — 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 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 # -------------------------------------------------------------------------- diff --git a/src/hhstream_session/format.py b/src/hhstream_session/format.py index c113e9c..6d70c39 100644 --- a/src/hhstream_session/format.py +++ b/src/hhstream_session/format.py @@ -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 `" + ) + 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.