# SPDX-License-Identifier: Apache-2.0 """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 contacts 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 contact has been heard *again*, so an absent contact 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 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: asyncio.Task | None = None self._unsubscribe: Unsubscribe | None = 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: datetime | None = 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: datetime | None = 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: datetime | None = None) -> float | None: """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)}” (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)}” 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) -> Contact | None: """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)