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