web_host_terminal_sessions.py 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579
  1. """Process-lifetime host shells, owned by Webapp identity and profile home.
  2. This is a separate capability namespace from Dashboard's client-selected chat IDs.
  3. The existing PTY registry owns processes/drains; this module owns host admission.
  4. A shell dies with its profile: once a named home is missing or deleted (main's
  5. tombstone rule, ``hermes_constants.assert_named_profile_home_live``) its input is
  6. refused and the reaper closes it.
  7. """
  8. from __future__ import annotations
  9. import asyncio
  10. from concurrent.futures import ThreadPoolExecutor
  11. from contextlib import asynccontextmanager, suppress
  12. from dataclasses import dataclass
  13. import json
  14. from pathlib import Path
  15. import re
  16. import secrets
  17. import time
  18. from fastapi import HTTPException, WebSocket, WebSocketDisconnect
  19. from hermes_cli.pty_session import (
  20. _VIEWER_SEND_ERRORS, _VIEWER_SEND_TIMEOUT_SECONDS, WS_CLOSE_VIEWER_STALLED,
  21. WS_CLOSE_VIEWER_STALLED_REASON, PtySession, PtySessionRegistry, RegistryFull, _close_ws, run_reaper,
  22. )
  23. from hermes_cli.web_host_terminal import META_PREFIX
  24. from hermes_constants import assert_named_profile_home_live, get_hermes_home
  25. # No survival across backend restart. Disconnects retain a bounded ANSI tail.
  26. RETENTION_SECONDS = 15 * 60
  27. _MAX_SHELLS = 16
  28. # Inbound input buffered while one batch is written (backpressure bound): full only once it holds
  29. # both ``_INPUT_QUEUE_FRAMES`` frames and ``_INPUT_QUEUE_BYTES`` bytes, each frame also costing
  30. # ``_FRAME_OVERHEAD_BYTES``. Until then the reader keeps reading the socket, which is where the
  31. # server's keepalive pongs arrive (``_InputQueue``).
  32. _INPUT_QUEUE_FRAMES = 64
  33. _INPUT_QUEUE_BYTES = 1024 * 1024
  34. _FRAME_OVERHEAD_BYTES = 256
  35. # How often a reader held up by that bound checks that the tab is still there (``_queue_frame``).
  36. # Once the connection is gone a check fails within about three: the first can still reach the
  37. # kernel before the peer's reset comes back.
  38. _LIVENESS_PROBE_SECONDS = 1.0
  39. # How long a resize that undoes the previous one waits for the program to answer that one (``_resize``).
  40. _RESIZE_ANSWER_SECONDS = 1.0
  41. TOKEN_RE = re.compile(r"^[A-Za-z0-9_-]{43}$")
  42. class TerminalDenied(Exception):
  43. pass
  44. class TerminalExpired(Exception):
  45. pass
  46. class TerminalExited(TerminalExpired):
  47. """The shell exited by itself (``exit``, Ctrl-D); the server did not end it."""
  48. def _home_live(home: Path) -> bool:
  49. """A named home must exist and carry no deletion tombstone; any other home only has to exist."""
  50. try:
  51. assert_named_profile_home_live(home)
  52. except FileNotFoundError:
  53. return False
  54. return home.is_dir()
  55. @dataclass(frozen=True)
  56. class HostOwner:
  57. identity: tuple[str, str]
  58. home: Path
  59. shell: str
  60. cwd: str
  61. def current(self) -> bool:
  62. """Blocking filesystem reads (home, tombstone): call off-loop."""
  63. return _home_live(self.home)
  64. def admit(self, write):
  65. """Run ``write`` while this owner's profile home is live, or raise ``TerminalExpired``.
  66. Input sent once the profile is deleted never reaches the shell. Blocking: bridges call
  67. it off-loop.
  68. """
  69. if not self.current():
  70. raise TerminalExpired()
  71. return write()
  72. def _request_identity(ws: WebSocket) -> tuple[str, str]:
  73. """``(provider, user)`` of the terminal ticket that admitted *ws*; ``_ws_gate`` admits no other
  74. credential to the host terminal."""
  75. identity = getattr(ws, "_hermes_auth_identity", None) or {}
  76. user, provider = identity.get("user_id"), identity.get("provider")
  77. if not isinstance(user, str) or not user or not isinstance(provider, str) or not provider:
  78. raise TerminalDenied()
  79. return provider, user
  80. def _request_home(profile: str | None) -> Path:
  81. from hermes_cli.web_server_profiles import _resolve_profile_dir
  82. requested = (profile or "").strip()
  83. return (
  84. _resolve_profile_dir(requested)
  85. if requested and requested.lower() != "current" else get_hermes_home()
  86. ).resolve()
  87. class HostTerminalRegistry(PtySessionRegistry):
  88. # The most exited shells remembered at once: a tab that redials after the reaper took its
  89. # shell still learns that it exited (``resolve``).
  90. _EXITS_KEPT = 4 * _MAX_SHELLS
  91. def __init__(self):
  92. # Every live shell keeps a read in flight. On the loop's default executor, retained
  93. # shells would queue the keystroke fences, ownership checks, uploads and SessionDB
  94. # hops that share it; a pool sized to capacity gives each shell its own reader.
  95. super().__init__(
  96. ttl=RETENTION_SECONDS, max_sessions=_MAX_SHELLS, buffer_cap=1024 * 1024, read_timeout=0.2,
  97. drain_executor=ThreadPoolExecutor(_MAX_SHELLS, thread_name_prefix="host-pty-drain"))
  98. self.owners: dict[str, HostOwner] = {}
  99. # Token -> (owner identity, when it was reaped) of shells that exited by themselves, for
  100. # the retention TTL.
  101. self.exits: dict[str, tuple[tuple[str, str], float]] = {}
  102. def _reap_one_idle_or_raise(self) -> None:
  103. # Retention is a promise, not an LRU hint; never evict a live shell to
  104. # make room for a different pane, even if its viewer just disconnected.
  105. raise RegistryFull()
  106. async def create(self, ws: WebSocket, identity: tuple[str, str]):
  107. from hermes_cli.web_host_terminal import query_dimension, resolve_argv
  108. from hermes_cli.web_server_chat import PtyBridge
  109. token = secrets.token_urlsafe(32)
  110. owner = None
  111. def spawn():
  112. nonlocal owner
  113. home = _request_home(ws.query_params.get("profile"))
  114. if not _home_live(home):
  115. raise TerminalExpired()
  116. argv, cwd, env, shell = resolve_argv(home=home, requested_cwd=ws.query_params.get("cwd"))
  117. bridge = PtyBridge.spawn(
  118. argv, cwd=cwd, env=env,
  119. cols=query_dimension(ws.query_params.get("cols"), 80, 2000),
  120. rows=query_dimension(ws.query_params.get("rows"), 24, 1000))
  121. owner = HostOwner(identity, home, shell, cwd)
  122. return bridge
  123. session, _ = await self.attach_or_spawn(token, spawn=spawn)
  124. assert owner is not None # spawn completed
  125. self.owners[token] = owner
  126. if not await asyncio.to_thread(owner.current):
  127. await self.remove(token)
  128. raise TerminalExpired()
  129. return session, owner
  130. async def resolve(self, token: str, ws: WebSocket, identity: tuple[str, str], *, closing=False):
  131. session = self._sessions.get(token)
  132. owner = self.owners.get(token)
  133. if session is None or owner is None:
  134. raise self._gone(token, identity)
  135. if owner.identity != identity:
  136. raise TerminalDenied()
  137. def validate():
  138. if _request_home(ws.query_params.get("profile")) != owner.home:
  139. raise TerminalDenied()
  140. owner.admit(lambda: None)
  141. await asyncio.to_thread(validate)
  142. # No await between the final check and the caller's attach claim. The
  143. # home was just checked off-loop; every input write checks it again.
  144. if self._sessions.get(token) is not session:
  145. # The reaper took the shell during validation; it may have exited first.
  146. raise self._gone(token, identity)
  147. if not closing and _exited(session):
  148. raise TerminalExited()
  149. if not closing and self.expired(session):
  150. raise TerminalExpired()
  151. return session, owner
  152. def _gone(self, token: str, identity: tuple[str, str]) -> TerminalExpired:
  153. """The refusal of a token with no registered shell: ``TerminalExited`` if *identity*'s shell
  154. exited by itself, else ``TerminalExpired``."""
  155. gone = self.exits.get(token)
  156. return TerminalExited() if gone is not None and gone[0] == identity else TerminalExpired()
  157. async def remove(self, token: str):
  158. session = self._sessions.pop(token, None)
  159. self.owners.pop(token, None)
  160. if session is not None:
  161. await asyncio.shield(self._close_in_background(session))
  162. async def reap_idle(self, now=None):
  163. # Durable tombstones also detect deletion by a different process; attached
  164. # viewers do not exempt a deleted profile.
  165. # One thread hop per tick keeps every shell's marker reads off the loop.
  166. owners = list(self.owners.items())
  167. retired = await asyncio.to_thread(lambda: {token for token, owner in owners if not owner.current()})
  168. now = time.monotonic() if now is None else now
  169. for token, owner in owners:
  170. session = self._sessions.get(token)
  171. if session is not None and (token in retired or self._reapable(session, now)):
  172. if token not in retired and _exited(session):
  173. self._remember_exit(token, owner, now)
  174. await self.remove(token)
  175. for token in list(self.owners):
  176. if token not in self._sessions:
  177. self.owners.pop(token, None)
  178. for token in [token for token, (_, at) in self.exits.items() if now - at > self._ttl]:
  179. del self.exits[token]
  180. def _remember_exit(self, token: str, owner: HostOwner, now: float) -> None:
  181. self.exits[token] = (owner.identity, now)
  182. while len(self.exits) > self._EXITS_KEPT:
  183. del self.exits[next(iter(self.exits))]
  184. async def close_all(self):
  185. await super().close_all()
  186. self.owners.clear()
  187. self.exits.clear()
  188. # Every drain is cancelled by now; a read still in flight returns within its
  189. # timeout, so let it finish behind us. A closed registry never spawns again.
  190. self._drain_executor.shutdown(wait=False)
  191. def _exited(session: PtySession) -> bool:
  192. """Whether a session still in the registry lost its shell: the server pops a session before
  193. it closes one, so only the shell's own exit leaves a dead one behind."""
  194. return not session.alive or not session.bridge.is_alive()
  195. def get_host_terminals(app) -> HostTerminalRegistry:
  196. registry = getattr(app.state, "host_terminals", None)
  197. if registry is None or registry._closed:
  198. raise RuntimeError("Host terminal service is not running; start the application lifespan first.")
  199. return registry
  200. @asynccontextmanager
  201. async def host_terminal_lifespan(app):
  202. # Overlapping lifespans must not share loop-bound sessions or teardown.
  203. registry = HostTerminalRegistry()
  204. registries = getattr(app.state, "_host_terminal_registries", None)
  205. if registries is None:
  206. registries = app.state._host_terminal_registries = []
  207. registries.append(registry)
  208. app.state.host_terminals = registry
  209. reaper = asyncio.create_task(run_reaper(registry, interval=1.0))
  210. try:
  211. yield
  212. finally:
  213. # Withdraw ownership before awaiting cleanup so another teardown cannot
  214. # restore this registry while its reaper/sessions are shutting down.
  215. registries.remove(registry)
  216. if getattr(app.state, "host_terminals", None) is registry:
  217. if registries:
  218. app.state.host_terminals = registries[-1]
  219. else:
  220. del app.state.host_terminals
  221. if not registries:
  222. del app.state._host_terminal_registries
  223. reaper.cancel()
  224. with suppress(asyncio.CancelledError):
  225. await reaper
  226. await registry.close_all()
  227. def _metadata(token, owner, registry, *, reconnected, truncated):
  228. return META_PREFIX + json.dumps({
  229. "shell": owner.shell, "terminalId": token, "cwd": owner.cwd,
  230. "reconnected": reconnected, "retentionSeconds": registry._ttl,
  231. "truncated": truncated,
  232. }, separators=(",", ":"))
  233. async def _send_closed(ws: WebSocket, token: str) -> None:
  234. await ws.send_text(META_PREFIX + json.dumps({"terminalId": token, "closed": True}))
  235. await ws.close(code=1000)
  236. async def _admit(ws: WebSocket, registry: HostTerminalRegistry):
  237. """Authorize the request and return ``(session, owner)`` to attach.
  238. Returns None once a ``close`` request has been served. Raises the ``Terminal*``
  239. errors ``host_terminal`` maps to close codes.
  240. """
  241. token = ws.query_params.get("attach")
  242. action = ws.query_params.get("action")
  243. identity = _request_identity(ws)
  244. if action not in (None, "close") or (action == "close" and token is None):
  245. raise TerminalDenied()
  246. if token is not None and not TOKEN_RE.fullmatch(token):
  247. raise TerminalExpired()
  248. if action == "close" and token not in registry._sessions:
  249. # Missing is idempotent, but never bypass auth/host policy.
  250. await _send_closed(ws, token)
  251. return None
  252. if token is None:
  253. return await registry.create(ws, identity)
  254. session, owner = await registry.resolve(token, ws, identity, closing=action == "close")
  255. if action == "close":
  256. await registry.remove(token)
  257. await _send_closed(ws, token)
  258. return None
  259. return session, owner
  260. def _frame_payload(msg: dict) -> bytes:
  261. """What a frame writes to the program: a binary frame's bytes, a text frame's UTF-8. The
  262. WebSocket library decodes a text frame strictly, so its text always encodes back."""
  263. raw = msg.get("bytes")
  264. return (msg.get("text") or "").encode("utf-8") if raw is None else raw
  265. def _frame_cost(item) -> int:
  266. """What a queued item counts against ``_INPUT_QUEUE_BYTES``: its payload and the per-frame overhead."""
  267. if not isinstance(item, dict): # the reader's last item: None or the error that ended reading
  268. return _FRAME_OVERHEAD_BYTES
  269. # The bytes ``_input_runs`` writes, not characters: a CJK or emoji paste is 3-4 bytes each.
  270. return len(_frame_payload(item)) + _FRAME_OVERHEAD_BYTES
  271. class _InputQueue(asyncio.Queue):
  272. """The frames a tab sent while a batch is written, full once it holds at least
  273. ``_INPUT_QUEUE_FRAMES`` frames and at least ``_INPUT_QUEUE_BYTES`` charged by ``_frame_cost``.
  274. A full queue stops the reader, and with it the WebSocket library's own read of the socket once
  275. that buffers 32 unread frames: keepalive pongs then go unread, and a bind that pings (any
  276. non-loopback Webapp) closes a live tab with 1011 after the ping timeout, dropping the input
  277. queued behind it. A frame count alone fills on a few dozen keys typed while a paste waits on a
  278. program that is not reading, and a byte count alone on one large paste; needing both gives
  279. typing far more room (one-byte keys fill it at 4,081 frames) and never stops the reader before
  280. the frame count alone would. Typing past that stalls the reader just as large frames do.
  281. So the frame count is not a strict limit: small frames can queue thousands. The payload ceiling
  282. stays about the frame count alone's: a frame is only taken while the queue holds fewer than
  283. ``_INPUT_QUEUE_FRAMES`` frames or charges under ``_INPUT_QUEUE_BYTES``, and each frame is at
  284. most the server's ``ws_max_size``.
  285. """
  286. def __init__(self):
  287. super().__init__()
  288. self.queued = 0
  289. def full(self) -> bool:
  290. return self.qsize() >= _INPUT_QUEUE_FRAMES and self.queued >= _INPUT_QUEUE_BYTES
  291. def _put(self, item):
  292. self.queued += _frame_cost(item)
  293. super()._put(item)
  294. def _get(self):
  295. item = super()._get()
  296. self.queued -= _frame_cost(item)
  297. return item
  298. async def _queue_frame(ws: WebSocket, inbox: asyncio.Queue, ended: asyncio.Future, msg) -> None:
  299. """``inbox.put(msg)``, checking that the tab is still there while the inbox stays full.
  300. A full inbox stops the reader taking frames. That backpressure bounds what a tab can queue, but
  301. it also leaves the tab's close unread behind those frames, and short of reading them only a send
  302. can find out that the connection is gone. So while the put waits, the tab gets an empty binary
  303. frame (no output, which the client ignores) every ``_LIVENESS_PROBE_SECONDS``; attach has already
  304. sent the replay, so it is never taken for one. A send that fails means the connection is gone:
  305. ``ended`` is set, which cancels a write waiting on the program, and the put goes on waiting
  306. unprobed.
  307. """
  308. while not ended.done():
  309. try:
  310. return await asyncio.wait_for(inbox.put(msg), _LIVENESS_PROBE_SECONDS)
  311. except TimeoutError:
  312. pass
  313. try:
  314. await asyncio.wait_for(ws.send_bytes(b""), _VIEWER_SEND_TIMEOUT_SECONDS)
  315. except _VIEWER_SEND_ERRORS:
  316. ended.set_result(None)
  317. await inbox.put(msg)
  318. async def _read_frames(ws: WebSocket, inbox: asyncio.Queue, ended: asyncio.Future) -> None:
  319. """Queue inbound frames. The last item is None, or the error that ended reading
  320. (re-raised by ``_pump_input`` so the route's handlers still see it). ``ended`` gets the same
  321. item as soon as reading ends, before it is queued, or None as soon as a full inbox finds the
  322. socket gone (``_queue_frame``): a write waiting on the shell, or a full inbox behind it, must
  323. not keep the pump from seeing that the socket is gone."""
  324. end = None
  325. try:
  326. while (msg := await ws.receive()).get("type") != "websocket.disconnect":
  327. await _queue_frame(ws, inbox, ended, msg)
  328. except RuntimeError: # a superseding/drain task already closed us
  329. pass
  330. # health: allow BLE001 -- forwarded, not swallowed: _pump_input re-raises it, and a reader that died unqueued would hang the pump
  331. except Exception as exc:
  332. end = exc
  333. if not ended.done():
  334. ended.set_result(end)
  335. await inbox.put(end)
  336. async def _write_while_open(session: PtySession, ws: WebSocket, data: bytes, fence,
  337. ended: asyncio.Future) -> bool | None:
  338. """``session.write`` of *data* with no deadline while the socket is open, or None once the
  339. socket has ended and the write has to wait for the program to read.
  340. The program may leave its input unread for as long as it likes, but not past the viewer. Input
  341. the tab sent before it closed still reaches the program as far as the program takes it; the
  342. first time the write then has to wait for room, it is cancelled (the rest is dropped, as on a
  343. takeover) and the session stays alive for the caller to detach.
  344. """
  345. loop = asyncio.get_running_loop()
  346. stalled = asyncio.Event()
  347. def watched(write):
  348. accepted = fence(write)
  349. # The POSIX bridge reports 0 bytes taken when the program's input queue is full; it then
  350. # waits for room. Runs in the bridge's worker thread.
  351. full = type(accepted) is int and accepted == 0
  352. loop.call_soon_threadsafe(stalled.set if full else stalled.clear)
  353. return accepted
  354. write = asyncio.ensure_future(session.write(ws, data, fence=watched, timeout=None))
  355. try:
  356. await asyncio.wait((write, ended), return_when=asyncio.FIRST_COMPLETED)
  357. if not write.done():
  358. stall = asyncio.ensure_future(stalled.wait())
  359. try:
  360. await asyncio.wait((write, stall), return_when=asyncio.FIRST_COMPLETED)
  361. finally:
  362. stall.cancel()
  363. finally:
  364. if not write.done():
  365. write.cancel()
  366. await asyncio.wait((write,))
  367. return None if write.cancelled() else write.result()
  368. def _input_runs(frames: list[dict], resize_re):
  369. """``frames`` in order: consecutive keystrokes joined into one run, resizes as ``(cols, rows)``."""
  370. run: list[bytes] = [] # joined once: a batch can hold megabytes of pasted input
  371. for msg in frames:
  372. raw = _frame_payload(msg)
  373. match = resize_re.fullmatch(raw) if raw else None
  374. if match is None:
  375. if raw:
  376. run.append(raw)
  377. continue
  378. if run:
  379. yield b"".join(run)
  380. run = []
  381. yield int(match[1]), int(match[2])
  382. if run:
  383. yield b"".join(run)
  384. async def _resize(session: PtySession, ws: WebSocket, size: tuple[int, int], undo):
  385. """Apply ``size``; return what the next resize needs to tell whether it undoes this one.
  386. A program can read the size well after its SIGWINCH (Node, behind its event loop, and reports a
  387. 'resize', which Hermes' TUI redraws on, only when the size it reads has changed). A step undone
  388. before it looks is never seen: both signals find the size it already had. So a resize back to
  389. the size before the previous one first waits until the program has written output since that
  390. one, as a program that redraws on a resize does, or ``_RESIZE_ANSWER_SECONDS`` for one that
  391. does not. ``undo`` is ``(size before the previous resize, outputs when it was applied)``, set
  392. only when that resize changed the size.
  393. """
  394. if undo is not None and undo[0] == size:
  395. await session.wait_for_output(undo[1], _RESIZE_ANSWER_SECONDS)
  396. before = session.size()
  397. session.resize(ws, cols=size[0], rows=size[1])
  398. return (before, session.outputs) if before is not None and before != size else None
  399. async def _pump_input(ws: WebSocket, registry: HostTerminalRegistry, token: str,
  400. session: PtySession, owner: HostOwner) -> None:
  401. """Forward keystrokes and resizes while ``ws`` is the attached viewer.
  402. Keystrokes reach the shell only inside ``owner.admit``, so input sent after the
  403. profile is deleted never does, even when it queued behind input that was admitted
  404. first. The fence reads files, so it runs off the loop, once per run of keystrokes in
  405. a batch (the frames that queued while the previous batch was written): a paste of
  406. many frames costs a few fences, not one each.
  407. Writes have no deadline. While the foreground program is not reading (``sleep``,
  408. ``npm install``) the PTY takes about 1 KB of input on macOS, so a paste waits for
  409. that program, in order, with any Ctrl-C behind it, as in native Desktop's terminal.
  410. A re-attach or the socket closing cancels the wait and keeps the shell (``host_terminal``
  411. then detaches it, so the retention reaper owns it again); only a closed bridge (the shell
  412. exited or the terminal was closed) or a deleted profile drops the session. ConPTY
  413. buffers input itself, so Windows writes land at once and keep the bridge's deadline.
  414. """
  415. from hermes_cli.web_server_chat import _RESIZE_RE
  416. inbox: asyncio.Queue = _InputQueue()
  417. ended = asyncio.get_running_loop().create_future()
  418. reader = asyncio.create_task(_read_frames(ws, inbox, ended))
  419. undo = None
  420. try:
  421. # No Ctrl-L/redraw input: arbitrary foreground shell programs own stdin.
  422. while session._ws is ws and session.alive:
  423. batch = [await inbox.get()]
  424. while not inbox.empty():
  425. batch.append(inbox.get_nowait())
  426. frames = [msg for msg in batch if isinstance(msg, dict)]
  427. for item in _input_runs(frames, _RESIZE_RE):
  428. if isinstance(item, tuple):
  429. undo = await _resize(session, ws, item, undo)
  430. continue
  431. try:
  432. delivered = await _write_while_open(session, ws, item, owner.admit, ended)
  433. except (TerminalExpired, FileNotFoundError):
  434. await registry.remove(token)
  435. return
  436. if delivered is None:
  437. # The socket ended and this input was left waiting for the program: stop here,
  438. # so the caller detaches a shell that is still running.
  439. if isinstance(ended.result(), Exception):
  440. raise ended.result()
  441. return
  442. if not delivered:
  443. # A closed bridge marked the session dead. A takeover only cancelled this
  444. # write: drop the rest of the batch and leave this socket for the new viewer
  445. # to supersede, so this tab does not reconnect and take the shell back.
  446. if not session.alive:
  447. await registry.remove(token)
  448. return
  449. break
  450. if len(frames) < len(batch):
  451. if isinstance(batch[-1], Exception):
  452. raise batch[-1]
  453. return
  454. finally:
  455. reader.cancel()
  456. with suppress(asyncio.CancelledError):
  457. await reader
  458. async def host_terminal(ws: WebSocket) -> None:
  459. """Called only after both the existing WS gate and host policy have passed."""
  460. from hermes_cli.pty_session import WS_CLOSE_PROCESS_EXITED, WS_CLOSE_PROCESS_EXITED_REASON
  461. from hermes_cli.web_server_chat import _pty_fail
  462. session = None
  463. try:
  464. registry = get_host_terminals(ws.app)
  465. admitted = await _admit(ws, registry)
  466. if admitted is None:
  467. return
  468. session, owner = admitted
  469. token = session.key
  470. reconnected = ws.query_params.get("attach") is not None
  471. def initial_text(truncated: bool) -> str:
  472. # Says whether the replay that follows leaves out older output.
  473. return _metadata(token, owner, registry, reconnected=reconnected, truncated=truncated)
  474. if not await session.attach(ws, initial_text=initial_text):
  475. if session._ws is None:
  476. await _close_ws(ws, WS_CLOSE_VIEWER_STALLED, WS_CLOSE_VIEWER_STALLED_REASON)
  477. return
  478. await _pump_input(ws, registry, token, session, owner)
  479. except TerminalDenied:
  480. await ws.close(code=4403, reason="Terminal belongs to another identity or profile")
  481. except TerminalExited:
  482. # The same close an attached tab gets when its shell exits: the tab closes too.
  483. await ws.close(code=WS_CLOSE_PROCESS_EXITED, reason=WS_CLOSE_PROCESS_EXITED_REASON)
  484. except (TerminalExpired, FileNotFoundError, HTTPException):
  485. await ws.close(code=4410, reason="Terminal or profile expired; open a new terminal")
  486. except RegistryFull:
  487. await ws.close(code=1013, reason="Terminal capacity reached; close a terminal and retry")
  488. except WebSocketDisconnect:
  489. pass
  490. except (OSError, RuntimeError) as exc:
  491. await _pty_fail(ws, exc, surface="Terminal")
  492. finally:
  493. if session is not None:
  494. session.detach(ws)