From d75a9aa2db513550bd88f2c99b5cff12b32af1e1 Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Sat, 11 Jul 2026 05:52:51 -0400 Subject: [PATCH] Courier: a store-and-forward outbox that delivers when the node shows up MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Queue a direct message for a node that isn't reachable right now and a session-long background loop delivers it when the recipient is next heard — or at a scheduled local time ("next 07:00", "in 3 h", any HH:MM). Each attempt is an ordinary chat send (it lands in the conversation history with its ack state, exactly as if typed); failures back off exponentially and, after the first shot, wait until the node is heard again, so an absent node is never hammered on faith. One attempt per pass keeps a backlog draining politely, and after five unacknowledged tries the courier gives up and says so. Outcomes raise Watchtower alerts, so the header's badge lights when an overnight delivery finally lands. The outbox persists in courier.json (a queued message must survive restarts or the promise is hollow), a Mesh-section screen carries the queueing flow, per-entry Send now / Cancel, and the finished history, and a scripted `courier [--at HH:MM]` queues without transmitting anything. Co-Authored-By: Claude Fable 5 --- meshterm/context.py | 24 +++ meshterm/core/courier_store.py | 269 ++++++++++++++++++++++++ meshterm/services/courier.py | 260 +++++++++++++++++++++++ meshterm/tools/courier.py | 123 +++++++++++ meshterm/ui/courier_screen.py | 350 +++++++++++++++++++++++++++++++ meshterm/ui/menu.py | 3 + meshterm/ui/watchtower_screen.py | 1 + tests/test_courier.py | 225 ++++++++++++++++++++ 8 files changed, 1255 insertions(+) create mode 100644 meshterm/core/courier_store.py create mode 100644 meshterm/services/courier.py create mode 100644 meshterm/tools/courier.py create mode 100644 meshterm/ui/courier_screen.py create mode 100644 tests/test_courier.py diff --git a/meshterm/context.py b/meshterm/context.py index 68c3339..fb2a63c 100644 --- a/meshterm/context.py +++ b/meshterm/context.py @@ -15,6 +15,7 @@ from rich.console import Console from .core.admin_store import AdminStore from .core.advert_store import AdvertStore from .core.config import DeviceProfile, Settings +from .core.courier_store import CourierStore from .core.remote_store import RemoteStore from .core.watch_store import WatchStore from .core.connection import Device, make_device @@ -28,6 +29,7 @@ if TYPE_CHECKING: from .services.advert_scheduler import AdvertScheduler from .services.chat_service import ChatService from .services.event_hub import EventHub + from .services.courier import CourierService from .services.monitor_service import MonitorService from .services.watchtower import WatchtowerService from .ui.surface import Ui @@ -50,6 +52,8 @@ class AppContext: history (defaults to ``/remote.json`` when not injected). watch_store: Store for the Watchtower — watched nodes, rules, and the alert log (defaults to ``/watchtower.json`` when not injected). + courier_store: Store for the Courier's outbox — queued, delivered, and + given-up messages (defaults to ``/courier.json``). mock: Whether the simulator device is in use. port_override: Explicit serial port (from ``--port`` or the interactive picker), overriding the profile. @@ -71,6 +75,7 @@ class AppContext: advert_store: Optional[AdvertStore] = None remote_store: Optional[RemoteStore] = None watch_store: Optional[WatchStore] = None + courier_store: Optional[CourierStore] = None profile: Optional[DeviceProfile] = None mock: bool = False port_override: Optional[str] = None @@ -97,6 +102,7 @@ class AppContext: _chat: "Optional[ChatService]" = field(default=None, init=False, repr=False) _adverts: "Optional[AdvertScheduler]" = field(default=None, init=False, repr=False) _watchtower: "Optional[WatchtowerService]" = field(default=None, init=False, repr=False) + _courier: "Optional[CourierService]" = field(default=None, init=False, repr=False) _ui: "Optional[Ui]" = field(default=None, init=False, repr=False) def __post_init__(self) -> None: @@ -107,6 +113,8 @@ class AppContext: self.remote_store = RemoteStore(self.settings.config_dir / "remote.json") if self.watch_store is None: self.watch_store = WatchStore(self.settings.config_dir / "watchtower.json") + if self.courier_store is None: + self.courier_store = CourierStore(self.settings.config_dir / "courier.json") @property def profile_name(self) -> Optional[str]: @@ -263,6 +271,20 @@ class AppContext: self._watchtower = WatchtowerService(self) return self._watchtower + @property + def courier(self) -> "CourierService": + """Return the session's store-and-forward courier, creating it on first use. + + Created idle here; the interactive session starts it alongside the other + always-on services. Scripted CLI runs never start the loop, so queueing a + message from a script transmits nothing until an interactive session runs. + """ + if self._courier is None: + from .services.courier import CourierService + + self._courier = CourierService(self) + return self._courier + @property def log(self): # type: ignore[no-untyped-def] """The application logger.""" @@ -476,6 +498,8 @@ class AppContext: async def aclose(self) -> None: """Stop monitoring and chat, stop the event hub, disconnect, and close the repo.""" + if self._courier is not None: + await self._courier.aclose() if self._watchtower is not None: await self._watchtower.aclose() if self._adverts is not None: diff --git a/meshterm/core/courier_store.py b/meshterm/core/courier_store.py new file mode 100644 index 0000000..a2df106 --- /dev/null +++ b/meshterm/core/courier_store.py @@ -0,0 +1,269 @@ +"""Persistence for the Courier: the store-and-forward outbox. + +The Courier (see :mod:`meshterm.services.courier`) queues direct messages for nodes +that aren't reachable right now and delivers them when the node is next heard — or at +a scheduled time. This store is the outbox itself: queued messages with their schedule +and attempt history, plus the finished ones (delivered or given-up) kept around, capped, +so the morning after tells the story. + +Like the remembered devices (:mod:`meshterm.core.device_store`), this is global machine +state in a small JSON file (``/courier.json``) rather than the +per-invocation SQLite database — a queued message must survive restarts, or the whole +promise ("it'll go out when the node shows up") is hollow. +""" + +from __future__ import annotations + +import json +from dataclasses import dataclass +from datetime import datetime +from pathlib import Path +from typing import Optional + +from .models import utcnow + +#: Message states: waiting in the outbox, landed, or abandoned after the retry budget. +QUEUED = "queued" +DELIVERED = "delivered" +GAVE_UP = "gave-up" + +#: How many finished (delivered / given-up) entries are kept for the screen's history. +DONE_CAP = 100 + + +@dataclass(slots=True) +class QueuedMessage: + """One outbox entry, from queueing through delivery (or defeat). + + Attributes: + ident: Monotonic id (stable across restarts), used to address the entry. + node_key: The recipient's canonical 12-hex id (what observations carry), + matched against the contact list at send time and against overheard + packets for reachability. + node_name: The recipient's display name, snapshotted at queue time. + text: The message body. + created: When it was queued. + not_before: Hold until this time (a scheduled send); ``None`` sends on the + next sign of life instead. + attempts: Delivery attempts made so far (each is one full chat send, with + the chat service's own soft-retry budget inside it). + last_attempt: When the latest attempt ran (drives the retry backoff). + status: :data:`QUEUED`, :data:`DELIVERED`, or :data:`GAVE_UP`. + finished: When the entry left the queue (delivered or given up). + """ + + ident: int + node_key: str + node_name: str + text: str + created: datetime + not_before: Optional[datetime] = None + attempts: int = 0 + last_attempt: Optional[datetime] = None + status: str = QUEUED + finished: Optional[datetime] = None + + +class CourierStore: + """Reads and writes the outbox, memory-first (loaded once, persisted on change).""" + + def __init__(self, path: Path) -> None: + """Open the store against a JSON file location. + + Args: + path: Path to the JSON state file (created lazily on first write). + """ + self._path = path + self._messages: Optional[list[QueuedMessage]] = None + self._next_id = 1 + + # --- state --------------------------------------------------------------------- + + def _load(self) -> list[QueuedMessage]: + """Parse the file, tolerating absence and corruption (an empty outbox).""" + if self._messages is not None: + return self._messages + try: + data = json.loads(self._path.read_text(encoding="utf-8")) + except (OSError, ValueError): + data = {} + if not isinstance(data, dict): + data = {} + self._next_id = max(1, _as_int(data.get("next_id"), 1)) + messages: list[QueuedMessage] = [] + for record in data.get("messages", []): + if not isinstance(record, dict): + continue + created = _as_time(record.get("created")) + if created is None: + continue + messages.append( + QueuedMessage( + ident=_as_int(record.get("ident"), 0), + node_key=str(record.get("node_key") or ""), + node_name=str(record.get("node_name") or "?"), + text=str(record.get("text") or ""), + created=created, + not_before=_as_time(record.get("not_before")), + attempts=_as_int(record.get("attempts"), 0), + last_attempt=_as_time(record.get("last_attempt")), + status=str(record.get("status") or QUEUED), + finished=_as_time(record.get("finished")), + ) + ) + self._messages = messages + return messages + + # --- the queue ----------------------------------------------------------------- + + def queue( + self, + node_key: str, + node_name: str, + text: str, + *, + not_before: Optional[datetime] = None, + ) -> QueuedMessage: + """Add a message to the outbox. + + Args: + node_key: The recipient's canonical 12-hex id. + node_name: The recipient's display name. + text: The message body. + not_before: Hold until this time; ``None`` sends on next sign of life. + + Returns: + The stored :class:`QueuedMessage`. + """ + messages = self._load() + message = QueuedMessage( + ident=self._next_id, node_key=node_key, node_name=node_name, + text=text, created=utcnow(), not_before=not_before, + ) + self._next_id += 1 + messages.append(message) + self._save() + return message + + def pending(self) -> list[QueuedMessage]: + """The waiting messages, oldest first (first queued, first delivered).""" + return [m for m in self._load() if m.status == QUEUED] + + def entries(self) -> list[QueuedMessage]: + """Every entry — waiting and finished — newest first (the screen's order).""" + return sorted(self._load(), key=lambda m: m.created, reverse=True) + + def get(self, ident: int) -> Optional[QueuedMessage]: + """One entry by id, or ``None``.""" + return next((m for m in self._load() if m.ident == ident), None) + + def pending_count(self) -> int: + """How many messages are waiting in the outbox.""" + return len(self.pending()) + + # --- attempt bookkeeping ----------------------------------------------------------- + + def note_attempt(self, ident: int, *, when: Optional[datetime] = None) -> None: + """Record that a delivery attempt is being made (written *before* the send, + so a crash mid-transmission can never spend the retry budget twice).""" + message = self.get(ident) + if message is not None: + message.attempts += 1 + message.last_attempt = when or utcnow() + self._save() + + def mark_delivered(self, ident: int, *, when: Optional[datetime] = None) -> None: + """Move an entry to :data:`DELIVERED`.""" + self._finish(ident, DELIVERED, when) + + def mark_gave_up(self, ident: int, *, when: Optional[datetime] = None) -> None: + """Move an entry to :data:`GAVE_UP` (the retry budget is spent).""" + self._finish(ident, GAVE_UP, when) + + def _finish(self, ident: int, status: str, when: Optional[datetime]) -> None: + """Finish one entry and trim the done history to its cap.""" + message = self.get(ident) + if message is None: + return + message.status = status + message.finished = when or utcnow() + messages = self._load() + done = [m for m in messages if m.status != QUEUED] + if len(done) > DONE_CAP: + done.sort(key=lambda m: m.finished or m.created) + drop = {m.ident for m in done[: len(done) - DONE_CAP]} + self._messages = [m for m in messages if m.ident not in drop] + self._save() + + def cancel(self, ident: int) -> bool: + """Remove a *waiting* entry outright (finished ones use :meth:`clear_done`). + + Returns: + Whether an entry was removed. + """ + messages = self._load() + kept = [m for m in messages if not (m.ident == ident and m.status == QUEUED)] + if len(kept) == len(messages): + return False + self._messages = kept + self._save() + return True + + def clear_done(self) -> None: + """Drop every finished entry, leaving the waiting queue untouched.""" + messages = self._load() + kept = [m for m in messages if m.status == QUEUED] + if len(kept) != len(messages): + self._messages = kept + self._save() + + # --- persistence ----------------------------------------------------------------- + + def _save(self) -> None: + """Persist the whole outbox atomically (crash mid-write keeps the old file).""" + data = { + "next_id": self._next_id, + "messages": [ + { + "ident": m.ident, + "node_key": m.node_key, + "node_name": m.node_name, + "text": m.text, + "created": m.created.isoformat(), + "not_before": m.not_before.isoformat() if m.not_before else None, + "attempts": m.attempts, + "last_attempt": m.last_attempt.isoformat() if m.last_attempt else None, + "status": m.status, + "finished": m.finished.isoformat() if m.finished else None, + } + for m in self._load() + ], + } + self._path.parent.mkdir(parents=True, exist_ok=True) + tmp = self._path.with_suffix(self._path.suffix + ".tmp") + tmp.write_text(json.dumps(data, indent=2), encoding="utf-8") + tmp.replace(self._path) + + +def _as_int(value: object, default: int) -> int: + """Coerce a stored number to a non-negative int, falling back to ``default``.""" + try: + number = int(value) # type: ignore[arg-type] + except (TypeError, ValueError): + return default + return number if number >= 0 else default + + +def _as_time(value: object) -> Optional[datetime]: + """Parse a stored ISO-8601 timestamp, or ``None`` if absent/corrupt. + + A timestamp without a zone is treated as corrupt too: the store only ever writes + aware UTC stamps, and a naive one would poison the schedule arithmetic. + """ + if not isinstance(value, str): + return None + try: + parsed = datetime.fromisoformat(value) + except ValueError: + return None + return parsed if parsed.tzinfo is not None else None diff --git a/meshterm/services/courier.py b/meshterm/services/courier.py new file mode 100644 index 0000000..e7f03b4 --- /dev/null +++ b/meshterm/services/courier.py @@ -0,0 +1,260 @@ +"""The Courier: store-and-forward delivery for the outbox. + +A session-long background loop over the :class:`~meshterm.core.courier_store. +CourierStore`. Messages queue for nodes that aren't reachable right now; the courier +listens to the hub for signs of life and delivers when the recipient is *fresh* — +heard within the last few minutes — or when a scheduled entry's time arrives. Each +attempt is one ordinary chat send (:meth:`~meshterm.services.chat_service.ChatService. +send_direct`, so it lands in the conversation history with its delivery state, exactly +as if typed), and an acknowledgement settles the entry as delivered. + +Deliberately transmission-shy, like the advert scheduler: + +* At most **one** delivery attempt per pass, so a backlog drains politely instead of + bursting onto a shared mesh. +* Failed attempts back off exponentially (5 min doubling to an hour) and — after the + first shot — wait until the node has been heard *again*, so an absent node is never + hammered on faith alone. Only a scheduled entry's first attempt fires blind: the + schedule was an explicit instruction. +* After :data:`MAX_ATTEMPTS` unacknowledged tries the courier gives up and says so. + +Outcomes (delivered, given-up) are also raised as Watchtower alerts, so the header's +``▲`` badge lights when an overnight delivery finally lands. +""" + +from __future__ import annotations + +import asyncio +from datetime import datetime +from typing import TYPE_CHECKING, Optional + +from ..core.connection import Unsubscribe +from ..core.courier_store import QUEUED, QueuedMessage +from ..core.events import EventKind, MeshEvent +from ..core.models import Contact, utcnow + +if TYPE_CHECKING: + from ..context import AppContext + +#: Seconds between courier passes. +POLL_S = 30.0 + +#: How recently (seconds) a node must have been heard to count as reachable. +FRESH_S = 600.0 + +#: Delivery attempts before the courier gives up on an entry. +MAX_ATTEMPTS = 5 + +#: Backoff after a failed attempt: this base doubling per failure, capped below. +BACKOFF_BASE_S = 300.0 +BACKOFF_CAP_S = 3600.0 + + +def _preview(text: str, width: int = 32) -> str: + """The message body shortened for alert/log one-liners.""" + return text if len(text) <= width else text[: width - 1] + "…" + + +class CourierService: + """Owns the store-and-forward loop for an interactive session. + + Interact through the async lifecycle methods (:meth:`start`, :meth:`stop`, + :meth:`aclose`) and :meth:`attempt_now`; eligibility lives in the synchronous + :meth:`eligible` so tests can drive it directly. + """ + + def __init__(self, ctx: "AppContext") -> None: + """Initialize the (idle) service. + + Args: + ctx: The shared application context (store, chat service, event hub). + """ + self._ctx = ctx + self._task: Optional[asyncio.Task] = None + self._unsubscribe: Optional[Unsubscribe] = None + #: When each node id was last overheard this session (the freshness map). + self._heard: dict[str, datetime] = {} + #: Re-entry guard: one attempt in flight at a time, pass or forced. + self._sending = False + + @property + def active(self) -> bool: + """Whether the courier loop is running.""" + return self._task is not None and not self._task.done() + + def pending_count(self) -> int: + """How many messages wait in the outbox.""" + return self._ctx.courier_store.pending_count() + + # --- lifecycle --------------------------------------------------------------------- + + async def start(self) -> None: + """Start the loop and the freshness subscription. Idempotent, device-free.""" + if self.active: + return + + def on_event(event: MeshEvent) -> None: + obs = event.observation + if obs is not None and obs.node: + self._heard[obs.node] = obs.observed_at or utcnow() + + self._unsubscribe = self._ctx.events.subscribe(on_event, EventKind.OBSERVATION) + self._task = asyncio.ensure_future(self._run()) + self._ctx.log.info( + "courier started (%d queued)", self._ctx.courier_store.pending_count() + ) + + async def stop(self) -> None: + """Stop the loop and the subscription. Idempotent.""" + if self._unsubscribe is not None: + self._unsubscribe() + self._unsubscribe = None + task, self._task = self._task, None + if task is not None: + task.cancel() + try: + await task + except asyncio.CancelledError: + pass + + async def aclose(self) -> None: + """Stop the loop at session end (an alias for :meth:`stop`).""" + await self.stop() + + async def _run(self) -> None: + """Tick forever: sleep, then make one best-effort pass.""" + while True: + await asyncio.sleep(POLL_S) + try: + await self._pass() + except asyncio.CancelledError: + raise + except Exception as exc: # noqa: BLE001 - a bad pass must not kill the loop + self._ctx.log.debug("courier: pass failed: %s", exc) + + # --- eligibility --------------------------------------------------------------------- + + def heard_recently(self, node_key: str, now: Optional[datetime] = None) -> bool: + """Whether ``node_key`` was overheard within the freshness window.""" + heard = self._heard.get(node_key) + if heard is None: + return False + return ((now or utcnow()) - heard).total_seconds() <= FRESH_S + + def eligible(self, message: QueuedMessage, now: Optional[datetime] = None) -> bool: + """Whether one queued entry may be attempted right now. + + The rules, in order: only queued entries; a schedule holds until its time; + failed attempts wait out an exponential backoff; and — except for a scheduled + entry's first, explicitly-timed shot — the recipient must have been heard + within the freshness window. + + Args: + message: The outbox entry. + now: The evaluation time (defaults to the current time; tests inject). + + Returns: + ``True`` when an attempt is allowed. + """ + now = now or utcnow() + if message.status != QUEUED: + return False + if message.not_before is not None and now < message.not_before: + return False + if message.last_attempt is not None and message.attempts > 0: + backoff = min(BACKOFF_CAP_S, BACKOFF_BASE_S * 2 ** (message.attempts - 1)) + if (now - message.last_attempt).total_seconds() < backoff: + return False + scheduled_first_shot = message.not_before is not None and message.attempts == 0 + if not scheduled_first_shot and not self.heard_recently(message.node_key, now): + return False + return True + + def next_retry_s(self, message: QueuedMessage, now: Optional[datetime] = None) -> Optional[float]: + """Seconds until the backoff releases a failed entry, or ``None`` if free now.""" + if message.last_attempt is None or message.attempts == 0: + return None + backoff = min(BACKOFF_CAP_S, BACKOFF_BASE_S * 2 ** (message.attempts - 1)) + remaining = backoff - ((now or utcnow()) - message.last_attempt).total_seconds() + return remaining if remaining > 0 else None + + # --- delivery ------------------------------------------------------------------------ + + async def _pass(self) -> None: + """One pass: attempt the oldest eligible entry, if any (one per pass).""" + if not self._ctx.is_connected or self._sending: + return + now = utcnow() + for message in self._ctx.courier_store.pending(): + if self.eligible(message, now): + await self._attempt(message) + return + + async def attempt_now(self, ident: int) -> str: + """Force one delivery attempt for the screen's *Send now*, skipping eligibility. + + Args: + ident: The outbox entry's id. + + Returns: + A short outcome string: ``delivered``, ``no ack``, ``gave up``, + ``unknown contact``, ``busy``, or ``gone``. + """ + message = self._ctx.courier_store.get(ident) + if message is None or message.status != QUEUED: + return "gone" + if self._sending: + return "busy" + return await self._attempt(message) + + async def _attempt(self, message: QueuedMessage) -> str: + """Run one delivery attempt and settle the entry's state.""" + store = self._ctx.courier_store + self._sending = True + try: + contact = await self._resolve(message) + if contact is None: + # Not addressable (yet): the device doesn't know the contact. Leave the + # entry waiting — no budget spent on a send that can't happen. + self._ctx.log.debug( + "courier: no contact for %r; leaving queued", message.node_name + ) + return "unknown contact" + store.note_attempt(message.ident) + chat = await self._ctx.chat.send_direct(contact, message.text) + if chat.acked: + store.mark_delivered(message.ident) + self._ctx.watch_store.add_alert( + "courier", message.node_name, + f"delivered “{_preview(message.text)}” " + f"(attempt {message.attempts})", + ) + self._ctx.log.info("courier: delivered to %s", message.node_name) + return "delivered" + if message.attempts >= MAX_ATTEMPTS: + store.mark_gave_up(message.ident) + self._ctx.watch_store.add_alert( + "courier", message.node_name, + f"gave up on “{_preview(message.text)}” " + f"after {message.attempts} attempts", + ) + return "gave up" + self._ctx.log.debug( + "courier: no ack from %s (attempt %d/%d)", + message.node_name, message.attempts, MAX_ATTEMPTS, + ) + return "no ack" + finally: + self._sending = False + + async def _resolve(self, message: QueuedMessage) -> Optional[Contact]: + """Find the recipient in the device's contact list, by key then by name.""" + device = await self._ctx.device() + contacts = await device.get_contacts() + for contact in contacts: + ident = (contact.public_key or contact.key_prefix or "").lower() + ident = ident.removeprefix("0x")[:12] + if ident and ident == message.node_key: + return contact + needle = message.node_name.casefold() + return next((c for c in contacts if c.name.casefold() == needle), None) diff --git a/meshterm/tools/courier.py b/meshterm/tools/courier.py new file mode 100644 index 0000000..6ff53cb --- /dev/null +++ b/meshterm/tools/courier.py @@ -0,0 +1,123 @@ +"""The ``courier`` tool: store-and-forward messaging for nodes that aren't there yet. + +Interactively it opens the outbox screen (see :mod:`meshterm.ui.courier_screen`): +queued messages with their live state, the queueing flow (recipient → message → +when), forced sends, and the delivered/given-up history. Delivery runs in the +background for the whole session (see :mod:`meshterm.services.courier`): a queued +message goes out when its node is next heard — or at its scheduled time — as a normal +direct message with acknowledgement tracking and polite exponential backoff, and the +outcome lights the header's Watchtower badge. + +On the CLI it stays a scriptable one-shot: ``courier [--at HH:MM]`` +queues the message (reading the contact list to address it — nothing is transmitted) +and the next interactive session's courier delivers it. +""" + +from __future__ import annotations + +from typing import Any, Optional + +import typer + +from ..context import AppContext +from ..core.connection import DeviceCommandError +from .base import Tool, ToolResult, register + + +@register +class CourierTool(Tool): + """Queue messages for offline nodes; they go out when the node is next heard.""" + + name = "courier" + title = "Courier" + icon = "📨" + help = "Store-and-forward outbox — deliver when the node is next heard" + category = "Mesh" + order = 12 # right after Chat: the same conversation, minus the waiting around + + async def prompt_params(self, ctx: AppContext) -> Optional[dict[str, Any]]: + """Run the outbox screen; there are never parameters to collect. + + The screen presents everything itself and returns when dismissed, so + returning ``None`` tells the menu the invocation is complete (the same + pattern as the ``dashboard`` tool). + + Args: + ctx: Shared application context. + + Returns: + Always ``None``. + """ + from ..ui.courier_screen import open_courier + + await open_courier(ctx) + return None + + async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: + """Queue one message from the CLI (transmits nothing). + + Args: + ctx: Shared application context. + params: ``node`` (contact name), ``text`` (the message body), and an + optional local ``at`` clock time (``HH:MM``, next occurrence). + + Returns: + A :class:`ToolResult` describing the queued entry. + """ + from ..ui.courier_screen import parse_clock + from ..ui.watchtower_screen import contact_watch_key + + device = await ctx.device() + contacts = await device.get_contacts() + name = str(params["node"]) + needle = name.casefold() + contact = next((c for c in contacts if c.name.casefold() == needle), None) + if contact is None: + raise DeviceCommandError(f"unknown contact: {name!r}") + key = contact_watch_key(contact) + if key is None: + raise DeviceCommandError(f"{name!r} has no usable key to address") + + not_before = None + if params.get("at"): + not_before = parse_clock(str(params["at"])) + if not_before is None: + raise DeviceCommandError( + f"--at wants a clock time like 07:00, not {params['at']!r}" + ) + message = ctx.courier_store.queue( + key, contact.name, str(params["text"]), not_before=not_before + ) + when = ( + f"at {not_before.astimezone().strftime('%b %d %H:%M')}" + if not_before is not None + else "when the node is next heard" + ) + ctx.ui.note( + f"[ok]queued[/ok] #{message.ident} for [brand]{contact.name}[/brand] — " + f"delivers {when} (an interactive session's courier does the sending)" + ) + return ToolResult( + summary={"queued": message.ident, "node": contact.name, "at": params.get("at")} + ) + + def register_cli(self, app: typer.Typer) -> None: + """Register the ``courier`` subcommand. + + Args: + app: The Typer application. + """ + from ..cli import run_tool_command + + @app.command(name=self.name, help=self.help) + def _courier( + node: str = typer.Argument(..., help="The recipient contact's name"), + text: list[str] = typer.Argument(..., help="The message to queue"), + at: Optional[str] = typer.Option( + None, "--at", help="Hold until this local time (HH:MM, next occurrence)" + ), + ) -> None: + tool_params: dict[str, Any] = {"node": node, "text": " ".join(text)} + if at is not None: + tool_params["at"] = at + run_tool_command(self, tool_params) diff --git a/meshterm/ui/courier_screen.py b/meshterm/ui/courier_screen.py new file mode 100644 index 0000000..973873d --- /dev/null +++ b/meshterm/ui/courier_screen.py @@ -0,0 +1,350 @@ +"""The Courier screens: the outbox, queueing flow, and per-message actions. + +The interactive face of the ``courier`` tool. One select-list screen carries the whole +feature (the persistent-backdrop pattern): the waiting outbox — each entry with its +live state (waiting to hear the node, scheduled for a time, backing off between +retries) — the finished history (delivered / given-up), and the queueing flow: pick a +contact, write the message, choose when. Enter on a waiting entry offers *Send now* +(one forced attempt, outcome in a dialog) and *Cancel*. + +Delivery itself happens in the background service (:mod:`meshterm.services.courier`), +which the menu starts with the other always-on services — this screen never needs to +stay open for a queued message to go out. +""" + +from __future__ import annotations + +import asyncio +import re +from datetime import datetime, timedelta, timezone +from typing import TYPE_CHECKING, Any, Optional + +from rich.text import Text + +from ..core.courier_store import DELIVERED, GAVE_UP, QUEUED, QueuedMessage +from ..core.models import NODE_TYPE_REPEATER, Contact, utcnow +from .tui import Choice, Separator +from .watchtower_screen import contact_watch_key +from .widgets import _age_seconds, _format_age + +if TYPE_CHECKING: + from ..context import AppContext + +# Menu action sentinels (tuples so they never collide with entry ids). +_QUEUE = ("queue",) +_CLEAR = ("clear",) + +#: The widest a message body renders in a row before it is ellipsized. +_TEXT_W = 36 + + +def _shorten(text: str, width: int = _TEXT_W) -> str: + """The message body shortened for row display.""" + return text if len(text) <= width else text[: width - 1] + "…" + + +def _local_stamp(when: datetime) -> str: + """A compact local timestamp: ``Jul 12 07:00``.""" + return when.astimezone().strftime("%b %d %H:%M") + + +def parse_clock(text: str, now: Optional[datetime] = None) -> Optional[datetime]: + """Parse a local ``HH:MM`` into its *next* occurrence, as aware UTC. + + ``07:00`` typed at 23:40 means tomorrow morning; typed at 06:00 it means an hour + from now. Returns ``None`` for anything that isn't a plausible clock time. + + Args: + text: The typed time. + now: The reference time (defaults to the current time; tests inject). + + Returns: + The next occurrence as an aware UTC datetime, or ``None``. + """ + match = re.fullmatch(r"\s*(\d{1,2})[:h](\d{2})\s*", text) + if not match: + return None + hour, minute = int(match.group(1)), int(match.group(2)) + if hour > 23 or minute > 59: + return None + now = now or utcnow() + local = now.astimezone() + candidate = local.replace(hour=hour, minute=minute, second=0, microsecond=0) + if candidate <= local: + candidate += timedelta(days=1) + return candidate.astimezone(timezone.utc) + + +async def open_courier(ctx: "AppContext") -> Optional[dict[str, Any]]: + """Run the Courier screen until dismissed. + + Args: + ctx: The shared application context (must be running the interactive TUI). + + Returns: + A summary of what happened (for the tool's log), or ``None`` on plain exit. + + Raises: + RuntimeError: If called outside the interactive menu (no full-screen session). + """ + from .surface import TuiUi + from .tui import CANCEL, SelectScreen + + if not isinstance(ctx.ui, TuiUi): # pragma: no cover - guarded by the menu-only caller + raise RuntimeError("the courier is only available in the menu") + session = ctx.ui.session + await ctx.courier.start() # idempotent; normally already running + + contacts: list[Contact] = [] + try: + if ctx.is_connected or ctx.settings.connect_on_start: + device = await ctx.device() + contacts = await device.get_contacts() + except Exception: # noqa: BLE001 - the outbox renders fine without contacts + contacts = [] + + store = ctx.courier_store + loop = asyncio.get_running_loop() + cursor: Any = None + while True: + items = _menu_items(ctx, store.entries()) + menu = SelectScreen( + "📨 Courier — store-and-forward outbox", + items, + default=cursor, + wrap=False, + footer_hint="↑↓ move · Enter select · Esc back", + ) + menu.future = loop.create_future() + session.push(menu) + try: + choice = await menu.future + if choice in (None, CANCEL): + return {"queued": store.pending_count()} + cursor = choice + if choice == _QUEUE: + await _queue_flow(ctx, contacts) + elif choice == _CLEAR: + store.clear_done() + cursor = None # the row itself disappears + elif isinstance(choice, tuple) and choice[0] == "msg": + await _entry_actions(ctx, int(choice[1])) + finally: + session.pop(menu) + + +# --- the menu --------------------------------------------------------------------------- + + +def _menu_items(ctx: "AppContext", entries: list[QueuedMessage]) -> list: + """Build the screen's rows: the waiting outbox, then the finished history.""" + waiting = [m for m in entries if m.status == QUEUED] + done = [m for m in entries if m.status != QUEUED] + + items: list = [Separator("Outbox", style="accent")] + if not waiting: + items.append(Separator(" empty — queued messages wait here for their moment")) + for message in waiting: + items.append(Choice(_waiting_row(ctx, message), ("msg", message.ident))) + items.append(Choice("✉ Queue a message…", _QUEUE)) + + if done: + items.append(Separator("")) + items.append(Separator("Finished", style="accent")) + for message in done[:15]: + items.append(Choice(_done_row(message), ("msg", message.ident))) + items.append(Choice("🗑 Clear finished", _CLEAR)) + return items + + +def _waiting_row(ctx: "AppContext", message: QueuedMessage) -> Text: + """One waiting entry: recipient, body, and what it is waiting for.""" + row = Text() + row.append("⏳ ", style="warn") + row.append(message.node_name) + row.append(f' “{_shorten(message.text)}”', style="muted") + row.append(" · ", style="muted") + now = utcnow() + if message.not_before is not None and now < message.not_before: + row.append(f"scheduled {_local_stamp(message.not_before)}", style="brand") + else: + retry = ctx.courier.next_retry_s(message, now) + if retry is not None: + row.append( + f"try {message.attempts} · retry in ~{max(1, round(retry / 60))} m", + style="warn", + ) + elif message.attempts > 0: + row.append(f"try {message.attempts} · waiting to hear it again", style="muted") + elif ctx.courier.heard_recently(message.node_key, now): + row.append("node is fresh — next pass", style="ok") + else: + row.append("waiting to hear the node", style="muted") + return row + + +def _done_row(message: QueuedMessage) -> Text: + """One finished entry: outcome marker, recipient, body, and when it settled.""" + row = Text() + if message.status == DELIVERED: + row.append("✓ ", style="ok") + else: + row.append("✗ ", style="err") + row.append(message.node_name, style="muted") + row.append(f' “{_shorten(message.text)}”', style="muted") + when = message.finished or message.created + verb = "delivered" if message.status == DELIVERED else "gave up" + row.append( + f" · {verb} {_format_age(_age_seconds(when))} ago" + f" · {message.attempts} attempt{'s' if message.attempts != 1 else ''}", + style="muted", + ) + return row + + +# --- the flows -------------------------------------------------------------------------- + + +async def _queue_flow(ctx: "AppContext", contacts: list[Contact]) -> None: + """Float the queueing flow: recipient, message, schedule.""" + session = ctx.ui.session + if not contacts: + await session.message_dialog( + Text( + "No contacts available — connect a device that knows some nodes first.", + style="muted", + ), + title="queue a message", + ) + return + + def recency(contact: Contact) -> float: + seen = _age_seconds(contact.last_seen) + return seen if seen is not None else float("inf") + + items: list = [] + for contact in sorted(contacts, key=recency): + row = Text() + row.append("▲ " if contact.node_type == NODE_TYPE_REPEATER else "● ", style="brand") + row.append(contact.name) + row.append(f" heard {_format_age(_age_seconds(contact.last_seen))}", style="muted") + items.append(Choice(row, contact)) + contact = await session.select( + "✉ Courier — recipient", + items, + prompt="The message waits in the outbox until this node can take it:", + ) + if contact is None: + return + text = await session.text( + f"Message for {contact.name}", + prompt="Delivered as a normal direct message when its moment comes.", + ) + if not text: + return + not_before = await _pick_schedule(ctx, contact.name) + if not_before is CANCEL_SCHEDULE: + return + key = contact_watch_key(contact) + if key is None: + await session.message_dialog( + Text(f"{contact.name!r} has no usable key to address.", style="err"), + title="queue a message", + ) + return + ctx.courier_store.queue(key, contact.name, text, not_before=not_before) + + +#: Sentinel: the schedule picker was cancelled (distinct from "no schedule"). +CANCEL_SCHEDULE = object() + + +async def _pick_schedule(ctx: "AppContext", name: str): + """Float the when-to-send picker; return an aware UTC time, ``None``, or cancel.""" + session = ctx.ui.session + now = utcnow() + tomorrow_7 = parse_clock("07:00", now) + items = [ + Choice("When it's next heard (recommended)", None), + Choice("In 1 h", now + timedelta(hours=1)), + Choice("In 3 h", now + timedelta(hours=3)), + Choice("In 8 h", now + timedelta(hours=8)), + Choice(f"Next 07:00 ({_local_stamp(tomorrow_7)})", tomorrow_7), + Choice("At a time… (HH:MM, next occurrence)", "custom"), + ] + picked = await session.select( + f"When should {name} get it?", items, filterable=False, + footer_hint="↑↓ move · Enter choose · Esc cancel", + ) + if picked == "custom": + while True: + typed = await session.text( + "Send at (local HH:MM)", + prompt="A time already past today means tomorrow.", + ) + if not typed: + return CANCEL_SCHEDULE + when = parse_clock(typed) + if when is not None: + return when + if picked is None: + # Esc on the picker cancels the queueing; "when next heard" is the explicit + # first row, so backing out never silently queues something. + return CANCEL_SCHEDULE + return picked + + +async def _entry_actions(ctx: "AppContext", ident: int) -> None: + """Float one entry's action menu: send now, cancel, or just look at it.""" + session = ctx.ui.session + store = ctx.courier_store + message = store.get(ident) + if message is None: + return + if message.status != QUEUED: + # A finished entry has no actions; show its full text instead. + body = Text(message.text) + body.append( + f"\n\n{message.status} · {message.attempts} attempt" + f"{'s' if message.attempts != 1 else ''}", + style="muted", + ) + await session.message_dialog(body, title=f"📨 {message.node_name}") + return + items = [ + Choice("📤 Send now — one forced attempt", "send"), + Choice("✖ Cancel this message", "cancel"), + ] + picked = await session.select( + f"📨 {message.node_name} — “{_shorten(message.text, 28)}”", + items, filterable=False, + footer_hint="↑↓ move · Enter select · Esc back", + ) + if picked == "cancel": + store.cancel(ident) + elif picked == "send": + try: + async with ctx.ui.busy_overlay(f"sending to {message.node_name}…"): + outcome = await ctx.courier.attempt_now(ident) + except Exception as exc: # noqa: BLE001 - surface the failure, keep the queue + await session.message_dialog( + Text(f"send failed: {exc}", style="err"), title="courier" + ) + return + notes = { + "delivered": Text("✓ delivered — acknowledged by the node", style="ok"), + "no ack": Text( + "sent, but no acknowledgement — it stays queued and the courier " + "will retry with backoff", style="warn", + ), + "gave up": Text("no acknowledgement — the retry budget is spent", style="err"), + "unknown contact": Text( + "the device's contact list doesn't know this node yet; " + "it stays queued", style="warn", + ), + "busy": Text("another delivery is in flight — try again in a moment", style="muted"), + "gone": Text("this entry is no longer queued", style="muted"), + } + await session.message_dialog( + notes.get(outcome, Text(outcome)), title="courier" + ) diff --git a/meshterm/ui/menu.py b/meshterm/ui/menu.py index 5cd56a8..ddb9719 100644 --- a/meshterm/ui/menu.py +++ b/meshterm/ui/menu.py @@ -510,6 +510,9 @@ async def _resume_monitor(ctx: AppContext) -> None: await ctx.adverts.start() # The Watchtower only listens (rules over hub events), so it too is safe from launch. await ctx.watchtower.start() + # The courier drains the outbox on its own paced schedule; each pass checks for a + # connected device and skips quietly without one, exactly like the advert scheduler. + await ctx.courier.start() if not ctx.settings.connect_on_start: return try: diff --git a/meshterm/ui/watchtower_screen.py b/meshterm/ui/watchtower_screen.py index f43f2c2..f5a9b4d 100644 --- a/meshterm/ui/watchtower_screen.py +++ b/meshterm/ui/watchtower_screen.py @@ -34,6 +34,7 @@ _KIND_STYLES = { "snr": "warn", "new-node": "brand", "recovered": "ok", + "courier": "accent", # outbox outcomes (see services.courier) share the log } #: How many alerts the screen lists (the store keeps more; the tail rarely matters). diff --git a/tests/test_courier.py b/tests/test_courier.py new file mode 100644 index 0000000..d388168 --- /dev/null +++ b/tests/test_courier.py @@ -0,0 +1,225 @@ +"""Courier tests: the outbox store, delivery eligibility, and the attempt flow. + +The service is driven synchronously (eligibility) and through stubbed chat sends +(attempts), so no timers or hardware are involved. +""" + +from __future__ import annotations + +import logging +from datetime import timedelta +from pathlib import Path + +from meshterm.core.courier_store import DONE_CAP, QUEUED, CourierStore +from meshterm.core.models import ChatMessage, Contact, utcnow +from meshterm.core.watch_store import WatchStore +from meshterm.services.courier import FRESH_S, MAX_ATTEMPTS, CourierService +from meshterm.ui.courier_screen import parse_clock + +NODE = "3d" * 6 +CONTACT = Contact(name="YUL", public_key="3d" * 32) + + +class _StubChat: + """Scripted chat service: pops the next ack outcome per send.""" + + def __init__(self, outcomes: list[bool]) -> None: + self.outcomes = list(outcomes) + self.sent: list[tuple[str, str]] = [] + + async def send_direct(self, contact: Contact, text: str) -> ChatMessage: + self.sent.append((contact.name, text)) + acked = self.outcomes.pop(0) if self.outcomes else False + return ChatMessage(text=text, outbound=True, acked=acked) + + +class _StubDevice: + async def get_contacts(self) -> list[Contact]: + return [CONTACT] + + +class _StubContext: + """Minimal stand-in for :class:`~meshterm.context.AppContext`.""" + + def __init__(self, tmp_path: Path, outcomes: list[bool]) -> None: + self.courier_store = CourierStore(tmp_path / "courier.json") + self.watch_store = WatchStore(tmp_path / "watchtower.json") + self.chat = _StubChat(outcomes) + self.is_connected = True + self.log = logging.getLogger("test.courier") + self._device = _StubDevice() + + async def device(self) -> _StubDevice: + return self._device + + +def _service(tmp_path: Path, outcomes: list[bool]) -> CourierService: + return CourierService(_StubContext(tmp_path, outcomes)) + + +# --- the store -------------------------------------------------------------------------- + + +def test_store_queue_round_trips_and_persists(tmp_path: Path) -> None: + """Queued entries survive a fresh store instance with their schedule intact.""" + path = tmp_path / "courier.json" + store = CourierStore(path) + when = utcnow() + timedelta(hours=8) + queued = store.queue(NODE, "YUL", "hello there", not_before=when) + assert queued.ident == 1 and queued.status == QUEUED + + again = CourierStore(path) + entry = again.get(1) + assert entry is not None and entry.text == "hello there" + assert entry.not_before == when + assert again.pending_count() == 1 + + +def test_store_lifecycle_attempts_finish_cancel_clear(tmp_path: Path) -> None: + """Attempt marks, delivery, cancellation, and clearing all behave.""" + store = CourierStore(tmp_path / "courier.json") + a = store.queue(NODE, "YUL", "one") + b = store.queue(NODE, "YUL", "two") + store.note_attempt(a.ident) + assert store.get(a.ident).attempts == 1 + store.mark_delivered(a.ident) + assert store.pending() == [store.get(b.ident)] + assert store.cancel(b.ident) is True + assert store.pending_count() == 0 + assert store.get(a.ident) is not None # delivered history remains + store.clear_done() + assert store.entries() == [] + + +def test_store_caps_the_finished_history(tmp_path: Path) -> None: + """Old finished entries fall off; the waiting queue is never trimmed.""" + store = CourierStore(tmp_path / "courier.json") + keeper = store.queue(NODE, "YUL", "still waiting") + for i in range(DONE_CAP + 5): + entry = store.queue(NODE, "YUL", f"m{i}") + store.mark_delivered(entry.ident) + done = [m for m in store.entries() if m.status != QUEUED] + assert len(done) == DONE_CAP + assert store.get(keeper.ident) is not None + + +# --- eligibility ------------------------------------------------------------------------- + + +def test_eligibility_waits_for_freshness_and_schedule(tmp_path: Path) -> None: + """Plain entries need the node heard; scheduled ones hold until their time.""" + service = _service(tmp_path, []) + store = service._ctx.courier_store + now = utcnow() + + plain = store.queue(NODE, "YUL", "hi") + assert not service.eligible(plain, now) # never heard this session + service._heard[NODE] = now - timedelta(seconds=FRESH_S + 1) + assert not service.eligible(plain, now) # heard, but too long ago + service._heard[NODE] = now + assert service.eligible(plain, now) + + scheduled = store.queue(NODE, "YUL", "later", not_before=now + timedelta(hours=1)) + assert not service.eligible(scheduled, now) # the schedule holds it + # Past its time, a scheduled entry's *first* shot fires even unheard-of. + service._heard.clear() + assert service.eligible(scheduled, now + timedelta(hours=2)) + + +def test_eligibility_backs_off_after_failures(tmp_path: Path) -> None: + """A failed attempt waits out its (doubling) backoff even when the node is fresh.""" + service = _service(tmp_path, []) + store = service._ctx.courier_store + now = utcnow() + entry = store.queue(NODE, "YUL", "hi") + service._heard[NODE] = now + store.note_attempt(entry.ident, when=now) + entry = store.get(entry.ident) + assert not service.eligible(entry, now + timedelta(minutes=2)) + assert service.eligible(entry, now + timedelta(minutes=6)) # 5-min base elapsed + assert service.next_retry_s(entry, now + timedelta(minutes=2)) is not None + + +# --- the attempt flow --------------------------------------------------------------------- + + +async def test_attempt_delivers_and_raises_the_good_news(tmp_path: Path) -> None: + """An acknowledged send settles the entry and lights the Watchtower badge.""" + service = _service(tmp_path, [True]) + ctx = service._ctx + entry = ctx.courier_store.queue(NODE, "YUL", "hello") + service._heard[NODE] = utcnow() + + await service._pass() + assert ctx.chat.sent == [("YUL", "hello")] + settled = ctx.courier_store.get(entry.ident) + assert settled.status == "delivered" and settled.attempts == 1 + alerts = ctx.watch_store.alerts() + assert len(alerts) == 1 and alerts[0].kind == "courier" + assert "delivered" in alerts[0].message + + +async def test_attempt_gives_up_after_the_budget(tmp_path: Path) -> None: + """Unacknowledged attempts exhaust the budget and say so, exactly once.""" + service = _service(tmp_path, [False] * MAX_ATTEMPTS) + ctx = service._ctx + entry = ctx.courier_store.queue(NODE, "YUL", "hello") + for _ in range(MAX_ATTEMPTS): + message = ctx.courier_store.get(entry.ident) + await service._attempt(message) + settled = ctx.courier_store.get(entry.ident) + assert settled.status == "gave-up" and settled.attempts == MAX_ATTEMPTS + gave = [a for a in ctx.watch_store.alerts() if "gave up" in a.message] + assert len(gave) == 1 + + +async def test_pass_attempts_at_most_one_entry(tmp_path: Path) -> None: + """A backlog drains one message per pass — the courier never bursts.""" + service = _service(tmp_path, [True, True]) + ctx = service._ctx + ctx.courier_store.queue(NODE, "YUL", "first") + ctx.courier_store.queue(NODE, "YUL", "second") + service._heard[NODE] = utcnow() + await service._pass() + assert len(ctx.chat.sent) == 1 + await service._pass() + assert len(ctx.chat.sent) == 2 + assert [t for _n, t in ctx.chat.sent] == ["first", "second"] # oldest first + + +async def test_unknown_contact_spends_no_budget(tmp_path: Path) -> None: + """A recipient the device doesn't know yet stays queued, untouched.""" + service = _service(tmp_path, [True]) + ctx = service._ctx + entry = ctx.courier_store.queue("ff" * 6, "Stranger", "hello") + outcome = await service._attempt(ctx.courier_store.get(entry.ident)) + assert outcome == "unknown contact" + settled = ctx.courier_store.get(entry.ident) + assert settled.status == QUEUED and settled.attempts == 0 + assert ctx.chat.sent == [] + + +async def test_attempt_now_forces_a_send(tmp_path: Path) -> None: + """The screen's Send now works regardless of freshness or schedule.""" + service = _service(tmp_path, [True]) + ctx = service._ctx + entry = ctx.courier_store.queue( + NODE, "YUL", "hello", not_before=utcnow() + timedelta(hours=8) + ) + assert await service.attempt_now(entry.ident) == "delivered" + assert await service.attempt_now(entry.ident) == "gone" # already settled + + +# --- the clock parser --------------------------------------------------------------------- + + +def test_parse_clock_finds_the_next_occurrence() -> None: + """HH:MM resolves to the next future occurrence, local, returned as UTC.""" + now = utcnow() + when = parse_clock("07:00", now) + assert when is not None and when > now + assert (when - now) <= timedelta(days=1) + assert when.astimezone().hour == 7 and when.astimezone().minute == 0 + assert parse_clock("7h30", now) is not None + assert parse_clock("25:00", now) is None + assert parse_clock("soonish", now) is None