diff --git a/meshterm/cli.py b/meshterm/cli.py index b407f36..8444eaa 100644 --- a/meshterm/cli.py +++ b/meshterm/cli.py @@ -18,7 +18,7 @@ import typer from .context import AppContext from .core.admin_store import AdminStore from .core.config import Settings -from .core.connection import DeviceCommandError +from .core.connection import DeviceCommandError, is_connection_lost from .core.device_config import DeviceConfigError from .core.device_store import DeviceStore from .core.selection import DeviceSelectionError @@ -110,6 +110,17 @@ def run_tool_command(tool: Tool, params: dict) -> None: # transient command failure): show the message, not a traceback. _state.console.print(f"[err]✗[/err] {exc}") raise typer.Exit(1) from exc + except Exception as exc: + # A dropped serial link (device unplugged/powered off mid-command) can't be recovered + # from in a one-shot scripted run the way the interactive menu offers — but it should + # still read as a clean message, not a traceback. Anything else propagates as before. + if not is_connection_lost(exc): + raise + _state.console.print( + "[err]✗[/err] the connection to your device was lost " + "(it may have been unplugged or powered off)." + ) + raise typer.Exit(1) from exc async def _drive(coro, ctx: AppContext) -> None: @@ -123,7 +134,10 @@ async def _drive(coro, ctx: AppContext) -> None: await coro finally: if ctx._device is not None: - await ctx._device.disconnect() + try: + await ctx._device.disconnect() + except Exception: # noqa: BLE001 - a dead/lost link must not crash teardown + pass ctx._device = None diff --git a/meshterm/context.py b/meshterm/context.py index 9b2c2aa..5a18237 100644 --- a/meshterm/context.py +++ b/meshterm/context.py @@ -61,6 +61,10 @@ class AppContext: selected_device: Optional[DiscoveredDevice] = None explicit_selection: bool = False _device: Optional[Device] = field(default=None, init=False, repr=False) + _active_port: Optional[str] = field(default=None, init=False, repr=False) + _resume_intent: Optional[tuple[bool, bool, bool]] = field( + default=None, init=False, repr=False + ) _events: "Optional[EventHub]" = field(default=None, init=False, repr=False) _monitor: "Optional[MonitorService]" = field(default=None, init=False, repr=False) _chat: "Optional[ChatService]" = field(default=None, init=False, repr=False) @@ -71,6 +75,23 @@ class AppContext: """Name of the active profile, if any.""" return self.profile.name if self.profile else None + @property + def is_connected(self) -> bool: + """Whether a device connection is currently open.""" + return self._device is not None + + @property + def active_port(self) -> Optional[str]: + """The serial port the current connection is open on, if any (``None`` for --mock). + + Set when a real connection is opened so the liveness watcher knows which OS port to + poll for a mid-session unplug. Falls back to an explicit ``--port`` override when a + connection hasn't recorded one yet. + """ + if self.mock: + return None + return self._active_port or self.port_override + @property def ui(self) -> "Ui": """The active UI surface, defaulting to the plain console surface for the CLI. @@ -153,6 +174,9 @@ class AppContext: device: A connected :class:`Device` to serve as this session's radio. """ self._device = device + # Record the port so the liveness watcher knows which OS port to poll (the picker + # opened it directly, bypassing the resolution in ``device()`` that normally sets it). + self._active_port = getattr(device, "_port", None) async def device(self) -> Device: """Return a connected :class:`Device`, opening the connection on first use. @@ -173,6 +197,7 @@ class AppContext: if self.mock: self._device = make_device(mock=True, port=None) + self._active_port = None await self._device.connect() return self._device @@ -186,6 +211,7 @@ class AppContext: self.selected_device = resolution.device baudrate = self.profile.baudrate if self.profile else 115200 self._device = make_device(mock=False, port=resolution.port, baudrate=baudrate) + self._active_port = resolution.port await self._device.connect() # Connection succeeded: this is now the last known good device. Learn its mesh node # name (best-effort — a probe failure must not block a good connection). @@ -195,6 +221,60 @@ class AppContext: ) return self._device + async def reconnect(self) -> None: + """Drop a lost device connection and rebuild it, restoring live services. + + Called after the companion link is detected as gone (see + :func:`~meshterm.core.connection.is_connection_lost`). Tears down the dead + connection and the services riding on it, opens a fresh connection to the same + device, then restarts whatever was running before — so passive monitoring and chat + recording resume transparently across a replug. + + Raises: + Exception: If a new connection could not be opened (e.g. the device is still + absent); the caller can surface it and offer to retry. + """ + # Remember what was live so it can be restored after the reconnect — but capture it + # only *once*, and hold it across retries. The teardown below stops the services, so + # a second attempt (after the first failed because the device wasn't back yet) would + # otherwise read the now-idle flags and restore nothing. The intent is cleared only + # after a reconnect actually succeeds. + if self._resume_intent is None: + self._resume_intent = ( + self._events is not None and self._events.active, + self._monitor is not None and self._monitor.active, + self._chat is not None and self._chat.active, + ) + resume_events, resume_monitor, resume_chat = self._resume_intent + + # Release the stale hub/service subscriptions and discard the dead device. The + # subscriptions are in-process (to the hub), so they survive the link drop and must + # be torn down explicitly before a fresh connection is opened underneath them. + if self._monitor is not None: + await self._monitor.stop() + if self._chat is not None: + await self._chat.stop() + if self._events is not None: + await self._events.stop() + if self._device is not None: + try: + await self._device.disconnect() + except Exception: # noqa: BLE001 - the link is already gone; best-effort + pass + self._device = None + + # Open a fresh connection (raises if the device still can't be reached, leaving the + # remembered intent in place for the next attempt), then restart whatever was running + # before it dropped and clear the intent now that we're back. + await self.device() + if resume_events: + await self.events.start() + if resume_monitor: + await self.monitor.start() + if resume_chat: + await self.chat.start() + self._resume_intent = None + async def _node_name(self) -> str: """Return the connected device's own mesh node name, or ``""`` if unavailable.""" try: @@ -212,6 +292,9 @@ class AppContext: if self._events is not None: await self._events.aclose() if self._device is not None: - await self._device.disconnect() + try: + await self._device.disconnect() + except Exception: # noqa: BLE001 - a dead/lost link must not crash teardown + pass self._device = None self.repo.close() diff --git a/meshterm/core/connection.py b/meshterm/core/connection.py index 7286bd6..8c4fcee 100644 --- a/meshterm/core/connection.py +++ b/meshterm/core/connection.py @@ -75,6 +75,98 @@ class DeviceCommandError(RuntimeError): """ +#: Exception class names that signal the serial link to the companion has dropped — the +#: device was unplugged, powered off, or its port otherwise vanished — as opposed to an +#: ordinary command-level failure. Matched by name in :func:`is_connection_lost` so the +#: optional ``pyserial`` dependency need not be imported here (it isn't installed on the +#: ``--mock`` path). ``SerialException`` covers pyserial's read/write failures (including the +#: Windows ``ClearCommError``/``WriteFile`` variants); the ``OSError`` subclasses cover a +#: link torn down at the OS layer. +_CONNECTION_LOST_TYPES = frozenset( + { + "SerialException", + "PortNotOpenError", + "ConnectionResetError", + "ConnectionAbortedError", + "BrokenPipeError", + } +) + +#: Lowercase message fragments that also indicate a dropped link, for exceptions raised as a +#: plain ``OSError``/``RuntimeError`` (whose type name alone isn't conclusive). Kept specific +#: enough not to fire on ordinary command timeouts. +_CONNECTION_LOST_HINTS = ( + "device disconnected", + "device not configured", + "clearcommerror", + "the handle is invalid", + "the device does not recognize the command", + "readfile failed", + "writefile failed", + "port is closed", + "no such device", + "input/output error", +) + + +def is_connection_lost(exc: BaseException) -> bool: + """Return whether ``exc`` means the companion serial link has dropped. + + Distinguishes a *lost connection* (the device was unplugged, powered off, or its serial + port vanished) from an ordinary command failure, so the interactive session can offer to + reconnect rather than merely report an error. The whole exception chain + (``__cause__``/``__context__``) is walked, matching by exception type name and message + text — see :data:`_CONNECTION_LOST_TYPES` / :data:`_CONNECTION_LOST_HINTS` — so the + optional ``pyserial`` dependency need not be imported here. + + Args: + exc: The exception raised by a device operation. + + Returns: + ``True`` if the exception (or any it was raised from) looks like a dropped link. + """ + seen: set[int] = set() + current: Optional[BaseException] = exc + while current is not None and id(current) not in seen: + seen.add(id(current)) + if type(current).__name__ in _CONNECTION_LOST_TYPES: + return True + text = str(current).lower() + if any(hint in text for hint in _CONNECTION_LOST_HINTS): + return True + current = current.__cause__ or current.__context__ + return False + + +def serial_port_present(port: str) -> bool: + """Return whether a serial port named ``port`` is currently enumerated by the OS. + + This is the primary liveness signal for a mid-session unplug: the ``meshcore`` client + keeps serving cached data after the cable is pulled and never raises (verified on + hardware — a command still "succeeds", merely returning ``None``), so a failed command + can't be relied on to notice. The OS port list, by contrast, drops the device the moment + it is removed. Enumerating ports only reads the OS device table; it never opens the port, + so it is safe to poll against a companion another handle already holds open. + + Args: + port: The serial port name the device was opened on (e.g. ``COM11`` or + ``/dev/ttyUSB0``). + + Returns: + ``True`` if a port by that exact name is present (or if presence can't be + determined — pyserial missing or the query failed — so a mere lookup hiccup never + raises a false "disconnected" alarm). + """ + try: + from serial.tools import list_ports + except Exception: # noqa: BLE001 - pyserial absent (e.g. --mock env); can't tell, assume up + return True + try: + return any(info.device == port for info in list_ports.comports()) + except Exception: # noqa: BLE001 - an enumeration failure must not fake a disconnect + return True + + class Device(ABC): """Abstract companion device exposing the operations MeshTerm needs. diff --git a/meshterm/ui/menu.py b/meshterm/ui/menu.py index a1a2b6e..f5aff15 100644 --- a/meshterm/ui/menu.py +++ b/meshterm/ui/menu.py @@ -27,7 +27,15 @@ from ..persistence.logging import get_logger from ..tools import all_tools from .surface import TuiUi from .theme import make_console -from .tui import CANCEL, Choice, SelectScreen, Separator, TuiSession +from .tui import ( + CANCEL, + Choice, + ReconnectDialog, + ScrollScreen, + SelectScreen, + Separator, + TuiSession, +) from .tui.emoji_width import calibrate as calibrate_emoji_width @@ -37,6 +45,20 @@ from .tui.emoji_width import calibrate as calibrate_emoji_width #: ever fires when exit has genuinely wedged. _EXIT_WATCHDOG_S = 5.0 +#: How often the liveness watcher checks that the connected companion's serial port is still +#: present while the menu sits idle (seconds). The ``meshcore`` client serves cached data and +#: never raises on an unplug, so this OS-level port poll — not a failed command — is what +#: actually notices a pulled cable (see :func:`~meshterm.core.connection.serial_port_present`). +_LIVENESS_POLL_S = 2.0 + +#: Debounce: after the port first appears to be gone, wait this long and re-check before +#: declaring the link lost, so a momentary enumeration gap (driver churn during a replug) +#: can't fire a false "disconnected" prompt (seconds). +_LIVENESS_CONFIRM_S = 0.4 + +#: Seconds between frames of the reconnect dialog's spinner while it waits for the device. +_RECONNECT_SPINNER_S = 0.12 + def _arm_exit_watchdog(seconds: float = _EXIT_WATCHDOG_S) -> None: """Guarantee the process terminates even if the exit path wedges. @@ -145,7 +167,7 @@ async def run_menu(ctx: AppContext) -> None: async def main() -> None: try: if await _startup(ctx): - await _menu_loop(ctx, session) + await _session_loop(ctx, session) finally: # Stop history + chat recording (closing their run records) and the always-on # event hub, even on an unexpected exit. @@ -210,7 +232,7 @@ async def _menu_loop(ctx: AppContext, session: TuiSession) -> None: default=1, footer_hint="Esc cancel · Enter quit", prompt_style="warn", - button_style="brand", + button_style="selected", button_idle_style="muted", border_style="warn", ) @@ -306,10 +328,16 @@ async def _resume_monitor(ctx: AppContext) -> None: async def _run_selection(ctx: AppContext, name: str) -> None: """Gather parameters for, execute, and present a single tool from the menu. + A dropped device link is not handled here: the session-wide watcher (see + :func:`_session_loop`) polls independently and raises the reconnect dialog wherever the + session is, so on a connection-lost error we simply drop the tool's half-built output and + return — the watcher takes it from there within a poll interval. + Args: ctx: The shared application context. name: The selected tool's name. """ + from ..core.connection import is_connection_lost from ..tools import get_tool tool = get_tool(name) @@ -325,6 +353,9 @@ async def _run_selection(ctx: AppContext, name: str) -> None: return result = await tool.execute(ctx, params) except Exception as exc: # noqa: BLE001 - surface errors without crashing the menu + if is_connection_lost(exc): + ctx.ui.discard() # drop the half-built output; the watcher will prompt to reconnect + return ctx.ui.note(f"[err]✗ {tool.name} failed:[/err] {exc}") await ctx.ui.present(title=tool.name) return @@ -336,5 +367,162 @@ async def _run_selection(ctx: AppContext, name: str) -> None: await ctx.ui.present(title=tool.name) +async def _session_loop(ctx: AppContext, session: TuiSession) -> None: + """Run the menu with a single always-on watcher that handles a disconnect anywhere. + + The menu loop runs as a cancellable worker alongside one session-wide liveness watcher. + Whichever finishes first wins: if the user quits, the menu loop returns and the watcher is + stopped; if the device is unplugged — no matter which screen is up (a tool prompt, the + chat view, the map, or the idle menu) — the watcher fires, the in-flight work is cancelled, + the screen stack is unwound, and the reconnect dialog is shown. On a successful reconnect + the loop starts a fresh menu; on quit it returns. + + Args: + ctx: The shared application context. + session: The running TUI session. + """ + while True: + worker = asyncio.ensure_future(_menu_loop(ctx, session)) + watcher = asyncio.ensure_future(_wait_for_disconnect(ctx)) + done, _ = await asyncio.wait( + {worker, watcher}, return_when=asyncio.FIRST_COMPLETED + ) + if worker in done: + await _cancel_and_wait(watcher) + worker.result() # user quit (or re-raise a menu-loop error) + return + # The device link dropped. Abandon whatever the menu was doing, clear any screens it + # left, and prompt to reconnect or quit over a clean frame. + await _cancel_and_wait(worker) + session.reset() + if await _handle_disconnect(ctx, session): + return # user chose to quit + # Reconnected — loop and start a fresh menu (with a fresh watcher). + + +async def _cancel_and_wait(task: "asyncio.Future") -> None: + """Cancel ``task`` and await its unwind, swallowing the cancellation and any error. + + Used to stop the sibling menu-worker or watcher: awaiting the cancelled task lets its + ``finally`` blocks run (popping any screens it pushed) before we continue, and its now-moot + error — the link is gone — is intentionally discarded. Awaiting also consumes the result + of an already-finished task, so no stray "exception never retrieved" warning is logged. + """ + task.cancel() + try: + await task + except asyncio.CancelledError: + pass + except Exception: # noqa: BLE001 - a cancelled worker's error is moot; move on + pass + + +async def _wait_for_disconnect(ctx: AppContext) -> None: + """Resolve once the connected companion's serial port disappears from the OS. + + Polls the OS serial-port enumeration rather than watching for a failed command: the + ``meshcore`` client keeps serving cached data after an unplug and never raises (confirmed + on hardware), so an *active* liveness check is the only thing that reliably notices a + pulled cable. Never resolves for the simulator (it can't be unplugged) or before a real + device has actually been opened. + + Args: + ctx: The shared application context (read for the active port and connection state). + """ + from ..core.connection import serial_port_present + + if ctx.mock: + await asyncio.Event().wait() # the simulator is never "unplugged"; wait forever + return + while True: + await asyncio.sleep(_LIVENESS_POLL_S) + port = ctx.active_port + if port is None or not ctx.is_connected: + continue # nothing connected to watch yet (deferred connect / no device) + if serial_port_present(port): + continue + await asyncio.sleep(_LIVENESS_CONFIRM_S) # debounce a transient enumeration gap + if not serial_port_present(port): + return + + +async def _handle_disconnect(ctx: AppContext, session: TuiSession) -> bool: + """Show a reconnect popup and watch for the device to return, auto-resuming on replug. + + Presents a centered, warn-styled dialog (:class:`~meshterm.ui.tui.prompt.ReconnectDialog`) + with an animated spinner and a single Quit button. Two background tasks run behind it: one + animates the spinner, the other polls for the device's port to re-enumerate and, once it + does, keeps attempting :meth:`~meshterm.context.AppContext.reconnect` until one succeeds — + a board can re-enumerate a moment before it will answer, so a failed attempt just retries. + Whichever resolves first wins: a successful reconnect dismisses the dialog and resumes the + session; the user pressing Quit (or Enter) leaves. The spinner stays up the whole time. + + Args: + ctx: The shared application context. + session: The running TUI session. + + Returns: + ``True`` if the user chose to quit; ``False`` once the device reconnected. + """ + dialog = ReconnectDialog("Waiting for your device — reconnect it to resume.") + dialog.future = asyncio.get_running_loop().create_future() + # The session stack was cleared before we were called (see _session_loop), so push a + # clean, empty base frame for the popup to float over. A lone floating screen with nothing + # beneath it is drawn as the *base* (framed chrome, no centered panel) rather than as a + # window — the base gives it something to center over, both horizontally and vertically. + base = ScrollScreen("", floating=False, footer_hint="") + session.push(base) + session.push(dialog) + animator = asyncio.ensure_future(_animate_dialog(session, dialog)) + reconnector = asyncio.ensure_future(_auto_reconnect(ctx, dialog)) + try: + result = await dialog.future + finally: + await _cancel_and_wait(reconnector) + await _cancel_and_wait(animator) + session.pop(dialog) + session.pop(base) + return result == "quit" + + +async def _animate_dialog(session: TuiSession, dialog: ReconnectDialog) -> None: + """Advance the reconnect dialog's spinner and repaint on a steady cadence, until cancelled.""" + while True: + await asyncio.sleep(_RECONNECT_SPINNER_S) + dialog.tick() + session.invalidate() + + +async def _auto_reconnect(ctx: AppContext, dialog: ReconnectDialog) -> None: + """Poll for the device to return, reconnect when it does, then dismiss ``dialog``. + + Waits for the OS to re-enumerate the port the connection was opened on before each + attempt, so a reconnect is only tried once there's a device to reach; a failed attempt + (the port is back but the board isn't ready yet, or it dropped again) simply loops and + retries. On the first success the dialog's future is resolved with ``"reconnected"``, + which dismisses the popup. Runs until it succeeds or the task is cancelled (the user quit). + + Args: + ctx: The shared application context. + dialog: The reconnect dialog to dismiss once the link is back. + """ + from ..core.connection import serial_port_present + + while True: + port = ctx.active_port + # Wait for the port to re-appear before touching the radio (skip the wait when there's + # no port to poll — e.g. an unknown/deferred port — and just retry on the interval). + if port is not None and not serial_port_present(port): + await asyncio.sleep(_LIVENESS_POLL_S) + continue + try: + await ctx.reconnect() + except Exception: # noqa: BLE001 - not reachable yet; keep the popup up and retry + await asyncio.sleep(_LIVENESS_POLL_S) + continue + dialog.resolve("reconnected") + return + + # Exposed for tools that need a standalone console outside a context (rare). default_console = make_console diff --git a/meshterm/ui/theme.py b/meshterm/ui/theme.py index 3ae45f1..6b58b48 100644 --- a/meshterm/ui/theme.py +++ b/meshterm/ui/theme.py @@ -9,6 +9,14 @@ MESH_THEME = Theme( { "brand": "bold #5eead4", "accent": "bold #818cf8", + # The highlighted-button fill (cyan block, dark text) shared by every popup dialog. + # It must be a *single* theme name: Rich silently drops a style string that mixes a + # theme name with an attribute (e.g. "reverse brand" renders as plain text), so the + # reverse is baked into the definition here rather than tacked on at the call site. + "selected": "reverse bold #5eead4", + # Reversed error (the text-editor cursor sitting on an over-budget character). Baked + # in for the same reason as ``selected`` — "reverse err" would render as plain text. + "err.reverse": "reverse bold #f87171", # Our own messages in a chat: pure white, deliberately outside the per-sender hue # palette (see meshterm.ui.chat._SENDER_COLORS) so "you" is always easy to spot. "you": "bold #ffffff", diff --git a/meshterm/ui/tui/__init__.py b/meshterm/ui/tui/__init__.py index c386cd0..c1f06ee 100644 --- a/meshterm/ui/tui/__init__.py +++ b/meshterm/ui/tui/__init__.py @@ -15,7 +15,7 @@ Public API: from __future__ import annotations from .progress import ProgressScreen -from .prompt import AutocompleteScreen, ConfirmScreen, TextScreen +from .prompt import AutocompleteScreen, ConfirmScreen, ReconnectDialog, TextScreen from .screen import CANCEL, BusyScreen, Screen, ScrollScreen from .select import Choice, SelectScreen, Separator from .session import TuiSession @@ -32,6 +32,7 @@ __all__ = [ "TextScreen", "ConfirmScreen", "AutocompleteScreen", + "ReconnectDialog", "ProgressScreen", "Spinner", "CANCEL", diff --git a/meshterm/ui/tui/prompt.py b/meshterm/ui/tui/prompt.py index b31f0e0..940f0cc 100644 --- a/meshterm/ui/tui/prompt.py +++ b/meshterm/ui/tui/prompt.py @@ -15,11 +15,29 @@ from rich.text import Text from .render import render_lines from .screen import Screen +from .spinner import Spinner #: A validator returns ``True`` when the input is acceptable, or an error message to show. Validator = Callable[[str], "bool | str"] +def _center(content: Text, width: int) -> Text: + """Center ``content`` in ``width`` with plain padding on both sides. + + Used instead of ``Text(justify="center")`` for lines that hold a reverse-video button + chip: Rich strips a styled span's *trailing* whitespace when it sits directly against + justify padding, which would shave the right edge off the chip (``" Quit"`` instead of + ``" Quit "``) and leave the label hugging the left of the fill. Padding manually keeps + a real segment after the chip, so its trailing cells survive and the fill stays symmetric. + """ + pad = max(0, width - content.cell_len) + left = pad // 2 + line = Text(" " * left) + line.append_text(content) + line.append(" " * (pad - left)) + return line + + class _LineEditor: """A minimal single-line text editor (insert, delete, and cursor movement). @@ -108,7 +126,7 @@ class _LineEditor: for i, ch in enumerate(shown): over = overflow_at is not None and i >= overflow_at if i == self.cursor: - text.append(ch, style="reverse err" if over else "reverse") + text.append(ch, style="err.reverse" if over else "reverse") else: text.append(ch, style="err" if over else None) if self.cursor >= len(shown): # cursor past the last character → trailing block @@ -200,9 +218,9 @@ class ConfirmScreen(Screen): def render_body(self, width: int) -> list[str]: """Render the Yes / No options with the current choice highlighted.""" text = Text() - text.append(" Yes ", style="reverse brand" if self._value else "muted") + text.append(" Yes ", style="selected" if self._value else "muted") text.append(" ") - text.append(" No ", style="muted" if self._value else "reverse brand") + text.append(" No ", style="muted" if self._value else "selected") return render_lines(text, width) def handle(self, action: str, data: str = "") -> None: @@ -237,7 +255,7 @@ class ButtonDialog(Screen): keys: Optional[dict[str, object]] = None, footer_hint: str = "←→ choose · Enter select · Esc cancel", prompt_style: str = "", - button_style: str = "reverse brand", + button_style: str = "selected", button_idle_style: str = "muted", border_style: str = "accent", ) -> None: @@ -294,14 +312,14 @@ class ButtonDialog(Screen): def render_body(self, width: int) -> list[str]: """Render the prompt centered above a centered row of buttons.""" - row = Text(justify="center") + row = Text() for i, (label, _value) in enumerate(self._buttons): if i: row.append(" ") style = self._button_style if i == self._index else self._button_idle_style row.append(f" {label} ", style=style) - prompt = Text(self._prompt, style=self._prompt_style, justify="center") - return render_lines(Group(prompt, Text(""), row), width) + prompt = Text(self._prompt, style=self._prompt_style) + return render_lines(Group(_center(prompt, width), Text(""), _center(row, width)), width) def handle(self, action: str, data: str = "") -> None: """Move the highlight, commit on Enter or a shortcut key, or cancel on Esc.""" @@ -316,6 +334,80 @@ class ButtonDialog(Screen): super().handle("escape") +class ReconnectDialog(Screen): + """A centered dialog shown when the companion link drops mid-session. + + An animated spinner and message sit above a single ``Abort`` button. Unlike the other + dialogs there is nothing to *choose*: the app watches for the device to return and + dismisses this screen itself (resolving its future) the moment the reconnect succeeds, so + the user's only action is to give up and abort. Only Enter resolves ``"quit"``; Esc is + deliberately inert, so an idle habit of pressing Esc can't drop the session while a replug + may be a second away. The button uses the shared ``selected`` highlight style (the theme's + cyan) — the same fill as the quit-confirmation dialog — so every popup dialog reads alike. + The animation is the reusable :class:`~meshterm.ui.tui.spinner.Spinner`, advanced by + :meth:`tick` from the session's animation timer. + """ + + def __init__( + self, + message: str, + *, + title: str = "Device disconnected", + footer_hint: str = "Enter abort", + prompt_style: str = "warn", + border_style: str = "warn", + ) -> None: + """Build the reconnect dialog. + + Args: + message: The line shown beside the spinner (e.g. "Waiting for your device…"). + title: Dialog heading. + footer_hint: Footer key hint (only Abort is offered). + prompt_style: Rich style for the message (``"warn"`` for the cautionary tone). + border_style: Rich style for the dialog border (read by the frame compositor). + """ + super().__init__() + self.title = title + self.footer_hint = footer_hint + self.border_style = border_style + self._message = message + self._prompt_style = prompt_style + self._spinner = Spinner() + + @property + def dialog_width(self) -> int: + """Natural outer width so the frame sizes the box to its content (see ButtonDialog).""" + inner = max( + cell_len(self._message), + cell_len(self.title), + cell_len(self.footer_hint), + len(" Abort "), + ) + return inner + 12 # panel padding + border, plus horizontal breathing room + + def set_message(self, message: str) -> None: + """Replace the line shown beside the spinner (e.g. to note a stalled retry).""" + self._message = message + + def tick(self) -> None: + """Advance the spinner to its next frame (driven by the session's animation timer).""" + self._spinner.tick() + + def render_body(self, width: int) -> list[str]: + """Render the spinner and message centered above a single Abort button.""" + line = self._spinner.text() + line.append(" ") + line.append(self._message, style=self._prompt_style) + row = Text() + row.append(" Abort ", style="selected") + return render_lines(Group(_center(line, width), Text(""), _center(row, width)), width) + + def handle(self, action: str, data: str = "") -> None: + """Abort only on Enter; ignore everything else, Esc included (the app auto-dismisses).""" + if action == "enter": + self.resolve("quit") + + class AutocompleteScreen(Screen): """A free-text field with a live suggestion list (``questionary.autocomplete``). diff --git a/meshterm/ui/tui/session.py b/meshterm/ui/tui/session.py index f90d20a..4a214be 100644 --- a/meshterm/ui/tui/session.py +++ b/meshterm/ui/tui/session.py @@ -107,6 +107,17 @@ class TuiSession: self._stack.remove(screen) self.invalidate() + def reset(self) -> None: + """Clear the whole screen stack and repaint. + + Used to unwind to a blank frame after a cancelled activity — e.g. when a mid-session + device disconnect abandons whatever screens the interrupted work had pushed, before + the reconnect dialog is shown over a clean slate. Screens hold no external resources + (their callers pop them in ``finally``), so dropping any stragglers here is safe. + """ + self._stack.clear() + self.invalidate() + def invalidate(self) -> None: """Request a repaint if the application is running.""" if self._app is not None: @@ -339,7 +350,7 @@ class TuiSession: keys: Optional[dict[str, Any]] = None, footer_hint: str = "←→ choose · Enter select · Esc cancel", prompt_style: str = "", - button_style: str = "reverse brand", + button_style: str = "selected", button_idle_style: str = "muted", border_style: str = "accent", ) -> Any: diff --git a/tests/test_disconnect.py b/tests/test_disconnect.py new file mode 100644 index 0000000..2be3f20 --- /dev/null +++ b/tests/test_disconnect.py @@ -0,0 +1,396 @@ +"""Tests for graceful handling of a lost device connection. + +Covers the exception classifier that distinguishes a dropped serial link from an ordinary +command failure, and :meth:`AppContext.reconnect`, which rebuilds the connection and restores +the services (event hub, passive monitor, chat) that were running before the drop. All run +against the :class:`MockDevice` simulator; no hardware required. +""" + +from __future__ import annotations + +import asyncio +import io +from pathlib import Path +from types import SimpleNamespace + +import pytest +from rich.console import Console + +from meshterm.context import AppContext +from meshterm.core import connection +from meshterm.core.admin_store import AdminStore +from meshterm.core.config import Settings +from meshterm.core.connection import DeviceCommandError, is_connection_lost +from meshterm.core.device_store import DeviceStore +from meshterm.persistence.repository import Repository +from meshterm.ui import menu + + +class _SerialException(Exception): + """A stand-in for ``serial.SerialException`` (matched by type name, not import).""" + + +def test_is_connection_lost_matches_serial_exception() -> None: + """A pyserial-style read/write failure is classified as a dropped link.""" + assert is_connection_lost(_SerialException("ClearCommError failed (Access is denied.)")) + + +def test_is_connection_lost_walks_the_exception_chain() -> None: + """A link error wrapped in a higher-level error is still detected via its cause.""" + try: + try: + raise _SerialException("WriteFile failed") + except Exception as cause: + raise RuntimeError("device write failed") from cause + except Exception as exc: + assert is_connection_lost(exc) + + +def test_is_connection_lost_matches_os_level_drops() -> None: + """OS-layer connection teardown and telltale I/O messages count as a lost link.""" + assert is_connection_lost(ConnectionResetError("reset")) + assert is_connection_lost(OSError("input/output error")) + + +def test_is_connection_lost_ignores_ordinary_failures() -> None: + """A transient command timeout or a generic error is not a dropped link.""" + assert not is_connection_lost(DeviceCommandError("the companion didn't respond in time")) + assert not is_connection_lost(ValueError("bad value")) + + +def _make_ctx(tmp_path: Path) -> AppContext: + """Build a real, mock-backed application context for reconnect tests.""" + settings = Settings(config_dir=tmp_path, db_path=tmp_path / "disc.db") + return AppContext( + console=Console(file=io.StringIO()), + settings=settings, + repo=Repository(settings.db_path), + device_store=DeviceStore(tmp_path / "devices.json"), + admin_store=AdminStore(tmp_path / "admin.json"), + mock=True, + ) + + +async def test_reconnect_rebuilds_device_and_restores_services(tmp_path: Path) -> None: + """Reconnect opens a fresh connection and resumes the hub, monitor, and chat.""" + ctx = _make_ctx(tmp_path) + try: + await ctx.events.start() + await ctx.monitor.enable() # start recording (also starts the hub) + await ctx.chat.start() + original = await ctx.device() + assert ctx.events.active and ctx.monitor.active and ctx.chat.active + + await ctx.reconnect() + + # A brand-new connection replaced the dead one, and everything that was running + # before the drop is running again. + rebuilt = await ctx.device() + assert rebuilt is not original + assert ctx.events.active + assert ctx.monitor.active + assert ctx.chat.active + finally: + await ctx.aclose() + + +async def test_reconnect_leaves_idle_services_idle(tmp_path: Path) -> None: + """Reconnect only restores what was live: idle services stay idle afterward.""" + ctx = _make_ctx(tmp_path) + try: + original = await ctx.device() # a tool opened the radio lazily; nothing subscribed + + await ctx.reconnect() + + rebuilt = await ctx.device() + assert rebuilt is not original + assert not ctx.events.active + assert not ctx.monitor.active + assert not ctx.chat.active + finally: + await ctx.aclose() + + +async def test_reconnect_restores_services_after_failed_attempts( + tmp_path: Path, monkeypatch +) -> None: + """Resume intent survives retries: services restore even if early reconnects fail. + + Reproduces the real-hardware bug where the first (failed) reconnect attempt tore the + services down, so later attempts read the now-idle flags and restored nothing. The + mock never fails ``device()``, so we force the first two ``device()`` calls to raise — + as an absent port does — before letting the third (and the restore calls) succeed. + """ + ctx = _make_ctx(tmp_path) + try: + await ctx.events.start() + await ctx.monitor.enable() + await ctx.chat.start() + await ctx.device() + assert ctx.events.active and ctx.monitor.active and ctx.chat.active + + real_device = AppContext.device + attempts = {"n": 0} + + async def flaky_device(self: AppContext): + attempts["n"] += 1 + if attempts["n"] <= 2: # the device isn't back yet on the first two tries + raise _SerialException("could not open port 'COM_TEST'") + return await real_device(self) + + monkeypatch.setattr(AppContext, "device", flaky_device) + + # Two failed reconnects (device still absent), then a success — like a slow replug. + for _ in range(2): + try: + await ctx.reconnect() + except _SerialException: + pass + await ctx.reconnect() # the third device() call succeeds; services restore + + assert ctx.events.active + assert ctx.monitor.active + assert ctx.chat.active + finally: + monkeypatch.undo() + await ctx.aclose() + + +def test_serial_port_present_reflects_os_enumeration(monkeypatch) -> None: + """A port is 'present' iff it appears in the OS enumeration; the primary unplug signal.""" + pytest.importorskip("serial") + from serial.tools import list_ports + + monkeypatch.setattr( + list_ports, "comports", lambda: [SimpleNamespace(device="COM11")] + ) + assert connection.serial_port_present("COM11") + assert not connection.serial_port_present("COM99") + + +def test_serial_port_present_assumes_up_on_enumeration_error(monkeypatch) -> None: + """A failed port query must never fake a disconnect — it reports 'present'.""" + pytest.importorskip("serial") + from serial.tools import list_ports + + def boom(): + raise OSError("enumeration failed") + + monkeypatch.setattr(list_ports, "comports", boom) + assert connection.serial_port_present("COM11") + + +async def test_wait_for_disconnect_fires_when_port_vanishes( + tmp_path: Path, monkeypatch +) -> None: + """The liveness watcher resolves once the connected device's port leaves enumeration.""" + ctx = _make_ctx(tmp_path) + # Pose as a live real-hardware session on COM_TEST (the mock can't be unplugged). + ctx.mock = False + ctx._device = object() # stand-in for a connected device; is_connected -> True + ctx._active_port = "COM_TEST" + + checks = {"n": 0} + + def fake_present(port: str) -> bool: + checks["n"] += 1 + return checks["n"] < 2 # present on the first poll, gone thereafter + + monkeypatch.setattr(connection, "serial_port_present", fake_present) + monkeypatch.setattr(menu, "_LIVENESS_POLL_S", 0.0) + monkeypatch.setattr(menu, "_LIVENESS_CONFIRM_S", 0.0) + try: + await asyncio.wait_for(menu._wait_for_disconnect(ctx), timeout=2.0) + finally: + ctx.repo.close() + + +async def test_wait_for_disconnect_ignores_the_simulator(tmp_path: Path) -> None: + """The watcher never fires for --mock: the simulator has no port to lose.""" + ctx = _make_ctx(tmp_path) # mock=True + try: + with pytest.raises(asyncio.TimeoutError): + await asyncio.wait_for(menu._wait_for_disconnect(ctx), timeout=0.2) + finally: + ctx.repo.close() + + +class _FakeSession: + """A minimal stand-in for :class:`TuiSession` recording pushes/pops for dialog tests.""" + + def __init__(self) -> None: + self.stack: list = [] + + def push(self, screen) -> None: + self.stack.append(screen) + + def pop(self, screen=None) -> None: + if self.stack: + self.stack.pop() + + def invalidate(self) -> None: + pass + + +async def test_handle_disconnect_auto_reconnects_when_port_returns( + tmp_path: Path, monkeypatch +) -> None: + """The popup dismisses itself (no keypress) once the device's port re-appears.""" + ctx = _make_ctx(tmp_path) + ctx.mock = False + ctx._device = object() # a connected stand-in + ctx._active_port = "COM_TEST" + + polls = {"n": 0} + + def fake_present(port: str) -> bool: + polls["n"] += 1 + return polls["n"] >= 2 # absent on the first poll, back thereafter + + async def fake_reconnect(self: AppContext) -> None: + self._device = object() # a fresh connection + + monkeypatch.setattr(connection, "serial_port_present", fake_present) + monkeypatch.setattr(AppContext, "reconnect", fake_reconnect) + monkeypatch.setattr(menu, "_LIVENESS_POLL_S", 0.0) + monkeypatch.setattr(menu, "_RECONNECT_SPINNER_S", 0.0) + + session = _FakeSession() + try: + quit_chosen = await asyncio.wait_for( + menu._handle_disconnect(ctx, session), timeout=2.0 + ) + assert quit_chosen is False # reconnected, not quit + assert session.stack == [] # the popup was cleaned up + finally: + ctx.repo.close() + + +async def test_handle_disconnect_quits_when_user_presses_quit( + tmp_path: Path, monkeypatch +) -> None: + """Pressing Enter (the Abort button) leaves, even while the device is still gone.""" + ctx = _make_ctx(tmp_path) + ctx.mock = False + ctx._device = object() + ctx._active_port = "COM_TEST" + + # The port never comes back, so the only way out is the Quit button. + monkeypatch.setattr(connection, "serial_port_present", lambda port: False) + monkeypatch.setattr(menu, "_LIVENESS_POLL_S", 0.0) + monkeypatch.setattr(menu, "_RECONNECT_SPINNER_S", 0.0) + + session = _FakeSession() + + async def press_quit() -> None: + # Once the dialog is on the stack, deliver Enter to its Abort button. + while not session.stack: + await asyncio.sleep(0) + session.stack[-1].handle("enter") + + try: + _, quit_chosen = await asyncio.wait_for( + asyncio.gather(press_quit(), menu._handle_disconnect(ctx, session)), + timeout=2.0, + ) + assert quit_chosen is True + assert session.stack == [] + finally: + ctx.repo.close() + + +async def test_reconnect_dialog_aborts_on_enter_and_ignores_escape() -> None: + """Enter aborts (resolves ``"quit"``); Esc is inert so a stray keypress can't drop us.""" + from meshterm.ui.tui import ReconnectDialog + + dialog = ReconnectDialog("Waiting…") + dialog.future = asyncio.get_running_loop().create_future() + + dialog.handle("escape") + assert not dialog.future.done() # Esc does nothing + + dialog.handle("enter") + assert dialog.future.result() == "quit" + + +async def _never() -> None: + """An awaitable that blocks forever (a stand-in for an idle worker/watcher).""" + await asyncio.Event().wait() + + +async def test_session_loop_quits_without_touching_the_disconnect_path(monkeypatch) -> None: + """When the menu loop returns (user quit), the watcher is stopped and no dialog shows.""" + handled = {"n": 0} + + async def fake_menu(ctx, session): + return None # user quit at the menu + + async def fake_handle(ctx, session): + handled["n"] += 1 + return True + + monkeypatch.setattr(menu, "_menu_loop", fake_menu) + monkeypatch.setattr(menu, "_wait_for_disconnect", lambda ctx: _never()) + monkeypatch.setattr(menu, "_handle_disconnect", fake_handle) + + session = SimpleNamespace(reset=lambda: None) + await asyncio.wait_for(menu._session_loop(object(), session), timeout=2) + assert handled["n"] == 0 # the disconnect path was never entered + + +async def test_session_loop_cancels_worker_and_prompts_on_disconnect(monkeypatch) -> None: + """A disconnect while the menu is busy cancels the worker, clears the stack, and prompts.""" + resets = {"n": 0} + cancelled = {"seen": False} + + async def busy_menu(ctx, session): + try: + await asyncio.Event().wait() # a tool is mid-flight; it must be cancelled + except asyncio.CancelledError: + cancelled["seen"] = True + raise + + async def fires_now(ctx): + return None # the port vanished + + async def quit_at_dialog(ctx, session): + return True + + monkeypatch.setattr(menu, "_menu_loop", busy_menu) + monkeypatch.setattr(menu, "_wait_for_disconnect", fires_now) + monkeypatch.setattr(menu, "_handle_disconnect", quit_at_dialog) + + session = SimpleNamespace(reset=lambda: resets.__setitem__("n", resets["n"] + 1)) + await asyncio.wait_for(menu._session_loop(object(), session), timeout=2) + assert cancelled["seen"] # the in-flight worker was cancelled + assert resets["n"] == 1 # the stack was unwound before the dialog + + +async def test_session_loop_resumes_a_fresh_menu_after_reconnect(monkeypatch) -> None: + """After a reconnect the loop starts a new menu (and re-arms the watcher).""" + state = {"menu": 0, "watch": 0, "handle": 0} + + async def flaky_menu(ctx, session): + state["menu"] += 1 + if state["menu"] == 1: + await asyncio.Event().wait() # first pass: interrupted by the disconnect + return None # second pass: user quits + + async def watch(ctx): + state["watch"] += 1 + if state["watch"] == 1: + return None # fire once + await asyncio.Event().wait() # never fire again + + async def reconnected(ctx, session): + state["handle"] += 1 + return False # the device came back + + monkeypatch.setattr(menu, "_menu_loop", flaky_menu) + monkeypatch.setattr(menu, "_wait_for_disconnect", watch) + monkeypatch.setattr(menu, "_handle_disconnect", reconnected) + + session = SimpleNamespace(reset=lambda: None) + await asyncio.wait_for(menu._session_loop(object(), session), timeout=2) + assert state["handle"] == 1 # one disconnect handled + assert state["menu"] == 2 # a fresh menu ran after reconnect