Prompt to reconnect or abort when the device drops mid-session

Watch the companion link while the menu runs; if it disconnects, float a
centered dialog with a spinner and a single Abort button while a
background task retries the connection. The dialog dismisses itself the
moment the device returns, so the user's only action is to give up:
Enter aborts, and Esc is deliberately inert so a stray keypress can't
drop the session while a replug may be a second away.

Give every popup dialog the same cyan reverse-highlight button. This
adds a "selected" theme style (and "err.reverse"): Rich silently renders
a style string that mixes a theme name with an attribute ("reverse
brand") as plain text, so the reverse is baked into a single-name theme
entry instead. Center the button chips with manual padding rather than
Text(justify="center"), which strips a styled span's trailing whitespace
and left the label hugging the fill's left edge.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 4.8 committed 2026-07-09 00:07:45 -04:00
1 parent b02e3b9f4b
commit dd097e48e5
9 files changed
+900 -15

No files matched your search

+16 -2
View File
@@ -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
+84 -1
View File
@@ -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()
+92
View File
@@ -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.
+191 -3
View File
@@ -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
+8
View File
@@ -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",
+2 -1
View File
@@ -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",
+99 -7
View File
@@ -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``).
+12 -1
View File
@@ -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:
+396
View File
@@ -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