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>
120 lines
4.7 KiB
Python
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)
|