Files
MeshTerm/meshterm/core/events.py
T
Jean-Pierre MartineauandClaude Opus 5.5 88d0d94ca7 The radio's route to each contact can be set, kept per site, and saved across sites
The companion holds one device route per contact and replaces it with every
path return, good or bad. MeshTerm can now write that route, keep it, and
make the routes follow the user from site to site.

- Device.set_route reads the radio's own record and writes it back with only
  the route changed, at the radio's hash width. Device.discover_route sends one
  path discovery and returns the route each way. The radio's PATH_UPDATE is a
  new hub event, EventKind.ROUTE.
- The outbound store keeps device routes per site and per fixed device (kept),
  and the routes a site learned (saved). Keep needs a site or a fixed device.
- services/device_routes.RouteKeeper (ctx.routes): forget, set, keep, unkeep,
  discover, and the status the pages show. At each connection and after each
  site change it reconciles: routes that start on another site's first hop are
  saved for that site and cleared, the new site's saved routes come back, and
  kept routes are written back. A silent first hop is skipped. A route change
  that the radio pushes gets the kept route written back.
- A site change on the Outbound paths page, its suggestion, and
  `meshterm outbound use` go through the reconcile and say what changed.
- New preference auto_route (off): before a DM, set the suggested route when
  the radio has none, or one from another site.

Refs: #34

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-08 00:19:20 -05:00

120 lines
4.7 KiB
Python

# SPDX-License-Identifier: Apache-2.0
"""Typed events that the always-on mesh event hub carries.
These are the domain-level events that go from the connected device to all the
subscribers that want them (refer to :class:`~meshterm.services.event_hub.EventHub`).
They are plain dataclasses with no I/O dependencies, and they are in this module with the
other domain models. Thus the hub, its subscribers, and the tests all use the same types,
and they do not import the device layer.
The hub carries the unrequested inbound streams to which a client reacts: overheard
packets (:class:`~meshterm.core.models.Observation`), inbound text messages
(:class:`~meshterm.core.models.Message`), and delivery acknowledgements
(:class:`~meshterm.core.models.Ack`). To add a new kind (contact updates, path changes),
add an :class:`EventKind` member and put the payload into a :class:`MeshEvent`. A
subscriber that does not ask for the new kind does not change.
This module does not carry the replies that match a request (the ``TRACE_DATA`` of a
trace, the result of a login). The command that sent the request waits for its reply
directly. Thus these replies work when the hub runs and also when it does not run.
"""
from __future__ import annotations
from dataclasses import dataclass, field
from datetime import datetime
from enum import Enum
from .models import Ack, Message, Observation, utcnow
class EventKind(str, Enum):
"""The classes of event that the hub can send to its subscribers.
It is a ``str`` enum, so that the values are easy to read in the log and when they are
serialized. New client features add their own members here.
"""
OBSERVATION = "observation"
MESSAGE = "message"
ACK = "ack"
ROUTE = "route"
@dataclass(frozen=True, slots=True)
class RouteChange:
"""The radio replaced its device route to one contact.
The companion tells the app each time that a path return gives it a new route. It does
not tell the app about a route that the app writes itself (refer to
:meth:`~meshterm.core.connection.Device.set_route`). Thus each event is a route that
the radio learned.
Attributes:
public_key: The public key of the contact, in lowercase hex.
"""
public_key: str
@dataclass(slots=True)
class MeshEvent:
"""One event that the hub gives to its subscribers.
It is a thin envelope. :attr:`kind` selects which subscribers receive it, and
:attr:`payload` carries the data for that kind (an
:class:`~meshterm.core.models.Observation` for :attr:`EventKind.OBSERVATION`). An
accessor for each kind, such as :attr:`observation`, gives callers a typed value. Thus
the callers do not have to match on ``kind`` themselves.
Attributes:
kind: The class of this event. It sets the payload type and the subscribers that
receive the event.
payload: The data object for the kind.
received_at: The time when the hub sent the event (UTC).
"""
kind: EventKind
payload: object = None
received_at: datetime = field(default_factory=utcnow)
@property
def observation(self) -> Observation | None:
"""The carried :class:`Observation`, or ``None`` if this event is not an observation."""
return self.payload if isinstance(self.payload, Observation) else None
@property
def message(self) -> Message | None:
"""The carried :class:`Message`, or ``None`` if this event is not a message."""
return self.payload if isinstance(self.payload, Message) else None
@property
def ack(self) -> Ack | None:
"""The carried :class:`Ack`, or ``None`` if this event is not an acknowledgement."""
return self.payload if isinstance(self.payload, Ack) else None
@property
def route(self) -> RouteChange | None:
"""The carried :class:`RouteChange`, or ``None`` if this event is not a route change."""
return self.payload if isinstance(self.payload, RouteChange) else None
@classmethod
def route_event(cls, change: RouteChange) -> MeshEvent:
"""Wrap a :class:`RouteChange` as an :attr:`EventKind.ROUTE` event."""
return cls(kind=EventKind.ROUTE, payload=change)
@classmethod
def observation_event(cls, obs: Observation) -> MeshEvent:
"""Wrap an :class:`Observation` as an :attr:`EventKind.OBSERVATION` event."""
return cls(kind=EventKind.OBSERVATION, payload=obs)
@classmethod
def message_event(cls, message: Message) -> MeshEvent:
"""Wrap a :class:`Message` as an :attr:`EventKind.MESSAGE` event."""
return cls(kind=EventKind.MESSAGE, payload=message)
@classmethod
def ack_event(cls, ack: Ack) -> MeshEvent:
"""Wrap an :class:`Ack` as an :attr:`EventKind.ACK` event."""
return cls(kind=EventKind.ACK, payload=ack)