Courier: a store-and-forward outbox that delivers when the node shows up

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 <node> <text…> [--at HH:MM]` queues without
transmitting anything.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Fable 5 committed 2026-07-11 05:52:51 -04:00
1 parent 908696a2d2
commit d75a9aa2db
8 files changed
+1255

No files matched your search

+24
View File
@@ -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 ``<config_dir>/remote.json`` when not injected).
watch_store: Store for the Watchtower — watched nodes, rules, and the alert
log (defaults to ``<config_dir>/watchtower.json`` when not injected).
courier_store: Store for the Courier's outbox — queued, delivered, and
given-up messages (defaults to ``<config_dir>/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:
+269
View File
@@ -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 (``<config_dir>/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
+260
View File
@@ -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)
+123
View File
@@ -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 <node> <text…> [--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)
+350
View File
@@ -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"
)
+3
View File
@@ -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:
+1
View File
@@ -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).
+225
View File
@@ -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