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>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5.5 committed 2026-11-08 00:19:20 -05:00
1 parent 73ae08b365
commit 88d0d94ca7
13 files changed
+1618 -15

No files matched your search

+21
View File
@@ -45,6 +45,7 @@ if TYPE_CHECKING:
from .services.chat_service import ChatService
from .services.clock_sync import ClockSync
from .services.courier import CourierService
from .services.device_routes import RouteKeeper
from .services.device_state import DeviceState
from .services.event_hub import EventHub
from .services.monitor_service import MonitorService
@@ -203,6 +204,7 @@ class AppContext:
_battery: BatteryService | None = field(default=None, init=False, repr=False)
_places: PlaceService | None = field(default=None, init=False, repr=False)
_site_suggest: SiteSuggester | None = field(default=None, init=False, repr=False)
_routes: RouteKeeper | None = field(default=None, init=False, repr=False)
_devstate: DeviceState | None = field(default=None, init=False, repr=False)
_basemap_source: BasemapSource | None = field(default=None, init=False, repr=False)
_ui: Ui | None = field(default=None, init=False, repr=False)
@@ -527,6 +529,21 @@ class AppContext:
self._site_suggest = SiteSuggester(self)
return self._site_suggest
@property
def routes(self) -> RouteKeeper:
"""Return the device-route service of the session, and create it at first use.
The actions (forget, set, keep) work at once. The interactive session also starts
the service with the other always-on services. Then it writes kept routes back when
the radio replaces them, and reconciles the routes at each connection (refer to
:mod:`meshterm.services.device_routes`). Scripted CLI runs never start it.
"""
if self._routes is None:
from .services.device_routes import RouteKeeper
self._routes = RouteKeeper(self)
return self._routes
@property
def battery(self) -> BatteryService:
"""Return the battery poller of the session, and create it at first use.
@@ -947,6 +964,8 @@ class AppContext:
await self._reconcile_channels()
if self._device is not None:
self.clock_sync.on_connected(self._device)
if self._device is not None and self._routes is not None:
self._routes.on_connected(self._device)
async def _reconcile_channels(self) -> None:
"""Replay the remembered channels that the device does not report.
@@ -1097,6 +1116,8 @@ class AppContext:
await self._places.aclose()
if self._site_suggest is not None:
await self._site_suggest.aclose()
if self._routes is not None:
await self._routes.aclose()
if self._watchtower is not None:
await self._watchtower.aclose()
if self._clock_sync is not None:
+231 -4
View File
@@ -32,15 +32,17 @@ from typing import TYPE_CHECKING, Any, ClassVar
from . import transmit_gate
from .channels import CHANNEL_SLOT_PROBE_CAP
from .events import MeshEvent
from .events import MeshEvent, RouteChange
from .frames import frame_addressing, trace_link_snrs
from .models import (
NODE_TYPE_CHAT,
NODE_TYPE_REPEATER,
NODE_TYPE_ROOM,
ROUTE_MAX_BYTES,
Ack,
Contact,
Delivery,
DiscoveredRoute,
Hop,
LoginResult,
Message,
@@ -1458,6 +1460,58 @@ class Device(ABC):
DeviceCommandError: If the radio refused for any other reason.
"""
@abstractmethod
async def set_route(self, node: Contact, hops: tuple[str, ...]) -> tuple[str, ...]:
"""Write the device route to ``node``, so that the radio sends to it on these hops.
The radio holds one route for each contact. It uses the route for each direct
message, login, request, and admin command to the contact. The radio replaces the
route each time that a path return gives it a new one. Thus a route that this method
writes stays only until the radio learns another one. The action is local (nothing
is transmitted).
The firmware writes a contact as one full record (the name, the flags, the location,
and the route). Thus the implementation reads the record that the radio has now,
and changes only the route in it. A record from an older read can contain old
values, and the write would put them back.
Each hop goes into the radio at the hash width that the radio uses now (its path
hash mode). A hop longer than the width is cut to the width.
Args:
node: The contact whose route to write.
hops: The relays, in order from us outward, as hex hashes or key prefixes. An
empty tuple means no relay: the radio sends direct to a neighbour.
Returns:
The hops as the radio holds them now, at its hash width.
Raises:
ContactNotOnDeviceError: If the radio has no contact for the node.
DeviceCommandError: If a hop is shorter than the hash width, if the route is
too long for the radio, or if the radio refused the write.
"""
@abstractmethod
async def discover_route(self, node: Contact) -> DiscoveredRoute | None:
"""Send one path discovery to ``node``, and get the route in each direction.
A path discovery is one flood request to the contact. The answer tells the route
on which the first copy reached the contact, and the route on which the first copy
of the answer came back. The radio does not change its device route for this
request. Thus the user can examine the routes before using one.
Args:
node: The contact to ask.
Returns:
The two routes, or ``None`` when no answer came before the timeout.
Raises:
ContactNotOnDeviceError: If the radio has no contact for the node.
DeviceCommandError: If the radio refused to send the request.
"""
@abstractmethod
async def send_remote_command(
self, node: Contact, command: str, *, timeout: float = 8.0
@@ -3589,6 +3643,79 @@ class MeshCoreDevice(Device):
f"couldn't reset the route to {node.name}: {reject_reason(result)}"
)
async def set_route( # noqa: D102 - inherited docstring
self, node: Contact, hops: tuple[str, ...]
) -> tuple[str, ...]:
mc = self._require()
pub = self._node_pubkey(node) # raises DeviceCommandError if it has no key
if len(pub) != 64:
raise DeviceCommandError(f"{node.name} is known only by a key prefix")
mode = max(int(await self.get_path_hash_mode()), 0)
route = route_at_width(hops, mode + 1, name=node.name)
# A new read of the record, written back with only the route changed. The firmware
# writes each field of the frame into the stored contact, so an older record would
# put old values back (refer to accept_adverts_again).
record = await self._contact_record(mc, pub)
if record is None:
raise ContactNotOnDeviceError(node)
result = await mc.commands.change_contact_path(record, "".join(route), path_hash_mode=mode)
if result is None or getattr(result, "is_error", lambda: False)():
if error_code(result) == _ERR_NOT_FOUND:
raise ContactNotOnDeviceError(node)
raise DeviceCommandError(
f"couldn't set the route to {node.name}: {reject_reason(result)}"
)
_log.debug("device route to %s set to %s", node.name, ",".join(route) or "no relays")
return route
async def discover_route( # noqa: D102 - inherited docstring
self, node: Contact
) -> DiscoveredRoute | None:
transmit_gate.mark()
from meshcore import EventType
mc = self._require()
pub = self._node_pubkey(node)
loop = asyncio.get_running_loop()
answer: asyncio.Future = loop.create_future()
def on_answer(event) -> None: # noqa: ANN001 - meshcore Event
payload = getattr(event, "payload", None) or {}
if str(payload.get("pubkey_pre") or "").lower() == pub[:12] and not answer.done():
answer.set_result(payload)
# Listen before the send, as for a login: the answer of a neighbour can arrive
# before the send returns.
subscription = mc.subscribe(EventType.PATH_RESPONSE, on_answer)
try:
send = getattr(mc.commands, "_send_path_discovery_raw", None)
async with self.transmitting():
if send is not None:
result = await send(bytes.fromhex(pub))
else: # pragma: no cover - an older library build
result = await mc.commands.send_path_discovery(bytes.fromhex(pub))
if result is None or getattr(result, "is_error", lambda: False)():
if error_code(result) == _ERR_NOT_FOUND:
raise ContactNotOnDeviceError(node)
raise DeviceCommandError(
f"couldn't send a path discovery to {node.name}: {reject_reason(result)}"
)
# The request is a flood, and the answer is a flood. The wait is the same as
# for a direct message sent by flood (refer to :meth:`send_direct_message`).
payload = getattr(result, "payload", None) or {}
suggested = float(payload.get("suggested_timeout") or 0) / 1000.0
budget = suggested * 1.25 + trace_timeout(0)
try:
found = await asyncio.wait_for(asyncio.shield(answer), budget)
except asyncio.TimeoutError:
_log.debug("path discovery to %s: no answer in %.1fs", node.name, budget)
return None
finally:
subscription.unsubscribe()
return DiscoveredRoute(
out_hops=_discovered_hops(found, "out"), in_hops=_discovered_hops(found, "in")
)
async def _login(self, node: Contact, password: str, *, what: str) -> _LoginExchange:
"""Run one login exchange with a remote node, and report how it ended.
@@ -4170,6 +4297,17 @@ class MeshCoreDevice(Device):
etype = getattr(EventType, "ACK", None)
if etype is not None:
subs.append(subscribe(etype, ack_handler))
# The radio says when a path return replaced its device route to a contact.
def route_handler(event) -> None: # noqa: ANN001
payload = getattr(event, "payload", None) or {}
key = str(payload.get("public_key") or "").lower()
if key:
on_event(MeshEvent.route_event(RouteChange(key)))
etype = getattr(EventType, "PATH_UPDATE", None)
if etype is not None:
subs.append(subscribe(etype, route_handler))
# Trace replies are not observations (the ``run_trace`` that sent the trace takes
# them by tag). But a log line for each reply that arrives lets us diagnose a "no
# reply". A reply logged here with no matching ``trace <tag>`` line means that the
@@ -5179,7 +5317,7 @@ class MockDevice(Device):
if flood:
# The answer to a flood brings a new route back with it, as on hardware.
self._stale_routes.discard(room.name)
self._set_route(key, self._LEARNED_ROUTE)
self._set_route(key, self._LEARNED_ROUTE, learned=True)
cfg = self._remote_config(room)
if password == self._admin_password:
access = RoomAccess.ADMIN
@@ -5208,11 +5346,45 @@ class MockDevice(Device):
#: The route that the simulator "learns" from the answer to a flood: one hop, through Yagi.
_LEARNED_ROUTE = ("a1b2c3d4",)
def _set_route(self, key: str, hops: tuple[str, ...] | None) -> None:
"""Give the contact with ``key`` a learned route, or forget its route (``None``)."""
async def set_route( # noqa: D102 - inherited docstring
self, node: Contact, hops: tuple[str, ...]
) -> tuple[str, ...]:
await asyncio.sleep(0)
route = route_at_width(hops, self._path_hash_mode + 1, name=node.name)
key = self._mock_key(node)
if not any(self._mock_key(c) == key for c in self._contacts):
raise ContactNotOnDeviceError(node)
self._set_route(key, route)
return route
async def discover_route( # noqa: D102 - inherited docstring
self, node: Contact
) -> DiscoveredRoute | None:
transmit_gate.mark()
async with self.transmitting():
await asyncio.sleep(0)
key = self._mock_key(node)
if not any(self._mock_key(c) == key for c in self._contacts):
raise ContactNotOnDeviceError(node)
if node.name in self._unreachable:
return None
route = route_at_width(self._LEARNED_ROUTE, self._path_hash_mode + 1, name=node.name)
return DiscoveredRoute(out_hops=route, in_hops=tuple(reversed(route)))
def _set_route(self, key: str, hops: tuple[str, ...] | None, *, learned: bool = False) -> None:
"""Give the contact with ``key`` a route, or forget its route (``None``).
A route that the simulated radio *learned* from the answer to a flood is pushed to
the listeners as a route change, as the companion pushes ``PATH_UPDATE``.
"""
self._contacts = [
replace(c, route_hops=hops) if self._mock_key(c) == key else c for c in self._contacts
]
if learned:
held = next((c for c in self._contacts if self._mock_key(c) == key), None)
full = (held.public_key if held is not None else "") or key
for listener in list(self._listeners):
listener(MeshEvent.route_event(RouteChange(full.lower())))
def _push_room(self, room: Contact) -> None:
"""Start the catch-up of a room: the posts after our newest post, oldest first.
@@ -6090,6 +6262,61 @@ def _as_int(value: object) -> int | None:
return None
def route_at_width(hops: Iterable[str], size: int, *, name: str = "") -> tuple[str, ...]:
"""The hops of a device route at the hash width of the radio, ready to write.
Args:
hops: The relays, in order from us outward, as hex hashes or key prefixes.
size: The bytes of each hash in the radio (its path hash mode plus one).
name: The name of the contact, for the error text.
Returns:
Each hop cut to ``size`` bytes, in lowercase hex.
Raises:
DeviceCommandError: If a hop is not hex, if a hop is shorter than the width, or if
the route has more bytes than the radio can hold (:data:`ROUTE_MAX_BYTES`).
"""
route: list[str] = []
for hop in hops:
text = str(hop).strip().lower().removeprefix("0x")
try:
bytes.fromhex(text)
except ValueError:
raise DeviceCommandError(f"{hop!r} is not a hop in hex") from None
if len(text) < size * 2:
raise DeviceCommandError(
f"hop {text} is shorter than the radio's {size}-byte path hash, so the "
f"route to {name or 'the contact'} can't name it"
)
route.append(text[: size * 2])
if len(route) * size > ROUTE_MAX_BYTES:
raise DeviceCommandError(
f"the route has {len(route)} hops, and the radio holds at most "
f"{ROUTE_MAX_BYTES // size} at its {size}-byte path hash"
)
return tuple(route)
def _discovered_hops(payload: dict, which: str) -> tuple[str, ...]:
"""One route of a path discovery answer, as one hex hash for each relay.
Args:
payload: The ``PATH_RESPONSE`` payload of the library.
which: ``"out"`` or ``"in"``.
Returns:
The relays in their order of travel, or an empty tuple for no relay (or for a
field that cannot be read).
"""
count = _as_int(payload.get(f"{which}_path_len")) or 0
size = _as_int(payload.get(f"{which}_path_hash_len")) or 1
text = str(payload.get(f"{which}_path") or "").lower()
if count <= 0 or len(text) < count * size * 2:
return ()
return tuple(text[i * size * 2 : (i + 1) * size * 2] for i in range(count))
def _contact_route(info: dict) -> tuple[str, ...] | None:
"""Get the outbound route of a contact as the device learned it, one hex hash per hop.
+27
View File
@@ -38,6 +38,23 @@ class EventKind(str, Enum):
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)
@@ -76,6 +93,16 @@ class MeshEvent:
"""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."""
+24
View File
@@ -397,6 +397,30 @@ class Contact:
return is_room(self.node_type)
#: The most bytes that the route of one contact can have in the firmware (``MAX_PATH_SIZE``).
#: The hop limit is this number divided by the bytes of each hash.
ROUTE_MAX_BYTES = 64
@dataclass(frozen=True, slots=True)
class DiscoveredRoute:
"""The two routes that one path discovery found between our node and a contact.
A path discovery is one flood request. The first copy that reached the contact
traveled on :attr:`out_hops`, and the first copy of the answer that reached us traveled
on :attr:`in_hops`. A radio link is not symmetric, so the two routes can be different.
Attributes:
out_hops: The route from our node to the contact: one hex hash for each relay, in
order from us outward. An empty tuple means no relay (a neighbour).
in_hops: The route from the contact to our node: one hex hash for each relay, in
order from the contact toward us.
"""
out_hops: tuple[str, ...]
in_hops: tuple[str, ...]
@dataclass(slots=True)
class MapMarker:
"""One mesh node to put on the map.
+207 -4
View File
@@ -22,6 +22,20 @@ computer, not to the radio, and this store keeps them in two forms:
:meth:`OutboundStore.lookup` gives the list that applies to a device, in this order: the
list of the fixed device, then the list of the active site, then no list.
Each site and each fixed device also holds **device routes** for single contacts (refer to
:meth:`~meshterm.core.connection.Device.set_route`). A device route is the route that the
radio uses to send to one contact. It depends on where the radio is, as an outbound path
does. Two maps hold them:
* **Kept routes.** The user chose the route and told MeshTerm to keep it. MeshTerm writes it
back to the radio each time that the radio replaces it. :meth:`OutboundStore.route_owner`
gives the record that holds the kept routes of a device, in the order of the lookup above.
With no fixed device and no active site, no record holds them.
* **Saved routes** (sites only). These are routes that the radio learned at a site. When the
user changes site, MeshTerm saves them here and clears them from the radio, because their
first hops are out of reach at the new site. When the user comes back, MeshTerm writes
them to the radio again.
The file is ``<config_dir>/outbound.json``, global machine state, the same as the other
JSON stores. It is intentionally outside the SQLite database, which can be different for
each run. The file is read into typed records (:class:`Site`, :class:`FixedDevice`) and
@@ -42,6 +56,11 @@ from .atomicwrite import write_atomically
#: usually the 12-digit key prefix of the node, or a shorter hash that the user typed.
OutboundPath = tuple[str, ...]
#: One device route: the relays from our node to one contact, in order outward. Each hop is
#: as in :data:`OutboundPath`. Unlike an outbound path, a device route can be empty: no
#: relay, because the contact is a neighbour.
RoutePath = tuple[str, ...]
#: The source of a lookup when the list comes from a fixed device.
SOURCE_DEVICE = "device"
#: The source of a lookup when the list comes from the active site.
@@ -93,6 +112,40 @@ def clean_path(value: object) -> OutboundPath | None:
return hops # type: ignore[return-value] - the check above removed each None
def clean_route(value: object) -> RoutePath | None:
"""A device route as the store keeps it, or ``None`` when the value is not one.
The rules are those of :func:`clean_path`, but a route can have no hops.
Args:
value: The raw route: a list of hops, or a comma-separated spec (``""`` for none).
Returns:
The route as a tuple of hops, or ``None``.
"""
if isinstance(value, str):
value = [part for part in value.split(",") if part.strip()]
if isinstance(value, list | tuple) and not value:
return ()
return clean_path(value)
def _clean_routes(raw: object) -> dict[str, RoutePath]:
"""The valid device routes of a file entry, with the contact key of each as the key."""
routes: dict[str, RoutePath] = {}
for key, entry in raw.items() if isinstance(raw, dict) else ():
contact = clean_hop(key)
route = clean_route(entry)
if contact is not None and route is not None:
routes[contact] = route
return routes
def _routes_json(routes: dict[str, RoutePath]) -> dict[str, list[str]]:
"""The device routes as written."""
return {key: list(route) for key, route in routes.items()}
def _clean_paths(raw: object) -> list[OutboundPath]:
"""The valid outbound paths of a file entry, in order, without duplicates."""
paths: list[OutboundPath] = []
@@ -111,10 +164,15 @@ class Site:
name: The name that the user gave the site (``Home``, ``Foulab``). Names are
unique without regard to case.
paths: The outbound paths, the preferred path first.
kept: The kept device routes at this site, with the contact key as the key.
saved: The device routes that the radio learned at this site, which MeshTerm saved
when the user changed site. The contact key is the key.
"""
name: str
paths: list[OutboundPath] = field(default_factory=list)
kept: dict[str, RoutePath] = field(default_factory=dict)
saved: dict[str, RoutePath] = field(default_factory=dict)
#: The fields that this record held before. It must never hold them again with a
#: different meaning (refer to :data:`meshterm.core.preferences.RETIRED` for the
@@ -129,11 +187,21 @@ class Site:
name = str(raw.get("name") or "").strip()
if not name:
return None
return cls(name=name, paths=_clean_paths(raw.get("paths")))
return cls(
name=name,
paths=_clean_paths(raw.get("paths")),
kept=_clean_routes(raw.get("kept")),
saved=_clean_routes(raw.get("saved")),
)
def to_json(self) -> dict:
"""The site as written: its own fields only."""
return {"name": self.name, "paths": [list(path) for path in self.paths]}
return {
"name": self.name,
"paths": [list(path) for path in self.paths],
"kept": _routes_json(self.kept),
"saved": _routes_json(self.saved),
}
@dataclass(slots=True)
@@ -144,10 +212,12 @@ class FixedDevice:
name: The name of the companion when the user fixed it. The list of fixed devices
shows it, because a public key means nothing to the user.
paths: The outbound paths, the preferred path first.
kept: The kept device routes of this companion, with the contact key as the key.
"""
name: str
paths: list[OutboundPath] = field(default_factory=list)
kept: dict[str, RoutePath] = field(default_factory=dict)
#: The fields that this record held before. There are none yet (refer to
#: :attr:`Site.RETIRED`).
@@ -157,11 +227,19 @@ class FixedDevice:
def read(cls, raw: object) -> FixedDevice:
"""Build a fixed device from one file entry, with only the fields that it knows."""
record = raw if isinstance(raw, dict) else {}
return cls(name=str(record.get("name") or ""), paths=_clean_paths(record.get("paths")))
return cls(
name=str(record.get("name") or ""),
paths=_clean_paths(record.get("paths")),
kept=_clean_routes(record.get("kept")),
)
def to_json(self) -> dict:
"""The fixed device as written: its own fields only."""
return {"name": self.name, "paths": [list(path) for path in self.paths]}
return {
"name": self.name,
"paths": [list(path) for path in self.paths],
"kept": _routes_json(self.kept),
}
@dataclass(slots=True)
@@ -232,6 +310,24 @@ class OutboundChoice:
name: str = ""
@dataclass(frozen=True, slots=True)
class RouteOwner:
"""The record that holds the kept device routes of one device.
Attributes:
source: :data:`SOURCE_DEVICE` for a fixed device, :data:`SOURCE_SITE` for the
active site.
name: The name of the site, or the name of the fixed device.
"""
source: str
name: str
class NoRouteOwnerError(LookupError):
"""No record can keep a device route: the device is not fixed, and no site is active."""
def _find(sites: list[Site], name: str) -> Site | None:
"""The site with ``name``, without regard to case, or ``None``."""
wanted = name.strip().casefold()
@@ -326,6 +422,9 @@ class OutboundStore:
if clash is not None and clash is not current:
raise ValueError(f"a site named {clash.name} already exists")
site = Site(name=name, paths=_clean_paths([list(path) for path in paths]))
if current is not None:
# A rename or a new list of paths keeps the device routes of the site.
site.kept, site.saved = current.kept, current.saved
if current is None:
records.sites.append(site)
else:
@@ -382,6 +481,8 @@ class OutboundStore:
raise ValueError(f"not a device key: {device_key!r}")
records = self._load()
device = FixedDevice(name=name.strip(), paths=_clean_paths([list(p) for p in paths]))
if key in records.devices:
device.kept = records.devices[key].kept # a new list of paths keeps the routes
records.devices[key] = device
self._write(records)
return device
@@ -424,3 +525,105 @@ class OutboundStore:
if site is not None:
return OutboundChoice(tuple(site.paths), SOURCE_SITE, site.name)
return OutboundChoice()
# -- device routes --------------------------------------------------------------
def _owner_record(
self, records: _OutboundFile, device_key: str | None
) -> tuple[RouteOwner, Site | FixedDevice] | None:
"""The record that holds the kept routes of a device, in the order of the lookup."""
key = clean_hop(device_key) if device_key else None
device = records.devices.get(key) if key else None
if device is not None:
return RouteOwner(SOURCE_DEVICE, device.name), device
site = _find(records.sites, records.active or "")
if site is not None:
return RouteOwner(SOURCE_SITE, site.name), site
return None
def route_owner(self, device_key: str | None) -> RouteOwner | None:
"""The record that holds the kept routes of a device, or ``None`` when none can.
The order is that of :meth:`lookup`: the fixed device, then the active site.
"""
found = self._owner_record(self._load(), device_key)
return found[0] if found is not None else None
def kept_routes(self, device_key: str | None) -> dict[str, RoutePath]:
"""The kept device routes that apply to a device, with the contact key as the key."""
found = self._owner_record(self._load(), device_key)
return dict(found[1].kept) if found is not None else {}
def kept_route(self, device_key: str | None, contact_key: str) -> RoutePath | None:
"""The kept device route to one contact, or ``None`` when the user keeps none."""
key = clean_hop(contact_key)
return self.kept_routes(device_key).get(key) if key else None
def keep_route(self, device_key: str | None, contact_key: str, route: RoutePath) -> RouteOwner:
"""Keep a device route to one contact, in the record that applies to the device.
Args:
device_key: The public key of the companion, or ``None``.
contact_key: The public key of the contact.
route: The relays, in order outward. An empty route means no relay.
Returns:
The record that keeps the route.
Raises:
NoRouteOwnerError: If the device is not fixed and no site is active.
ValueError: If the contact key or the route is not valid.
"""
key = clean_hop(contact_key)
clean = clean_route(list(route))
if key is None or clean is None:
raise ValueError(f"not a device route: {contact_key!r} {route!r}")
records = self._load()
found = self._owner_record(records, device_key)
if found is None:
raise NoRouteOwnerError(contact_key)
found[1].kept[key] = clean
self._write(records)
return found[0]
def unkeep_route(self, device_key: str | None, contact_key: str) -> bool:
"""Stop keeping the device route to one contact.
Returns:
Whether a kept route was removed.
"""
key = clean_hop(contact_key)
records = self._load()
found = self._owner_record(records, device_key)
if key is None or found is None or found[1].kept.pop(key, None) is None:
return False
self._write(records)
return True
def saved_routes(self, site_name: str) -> dict[str, RoutePath]:
"""The device routes saved for a site, with the contact key as the key."""
site = _find(self._load().sites, site_name)
return dict(site.saved) if site is not None else {}
def save_routes(self, site_name: str, routes: dict[str, RoutePath]) -> None:
"""Add device routes to the saved routes of a site. A newer route replaces an older.
Raises:
KeyError: If no site has that name.
"""
records = self._load()
site = _find(records.sites, site_name)
if site is None:
raise KeyError(site_name)
site.saved.update(_clean_routes({key: list(route) for key, route in routes.items()}))
self._write(records)
def take_saved(self, site_name: str) -> dict[str, RoutePath]:
"""Remove and return the saved device routes of a site (empty for no such site)."""
records = self._load()
site = _find(records.sites, site_name)
if site is None or not site.saved:
return {}
taken, site.saved = site.saved, {}
self._write(records)
return taken
+12
View File
@@ -357,6 +357,18 @@ PREFERENCES: tuple[PrefSpec, ...] = (
maximum=720,
unit="h",
),
PrefSpec(
key="auto_route",
label="Auto route",
help="Before a DM, set the suggested route if the radio has none",
group="Sending",
value_type="bool",
# Off: the suggested route comes from evidence, and a wrong one loses the message,
# where a flood finds a way. On, MeshTerm sets it before a direct message when the
# radio has no route, or a route that starts on another site's first hop. A kept
# route is never changed. Refer to meshterm.services.device_routes.
default=False,
),
# --- TX optimize -------------------------------------------------------------
PrefSpec(
key="tx_opt_min",
+10
View File
@@ -585,6 +585,16 @@ class ChatService:
The stored outbound :class:`ChatMessage`. Its ``acked`` shows whether a
delivery acknowledgement arrived in the wait, until now.
"""
# With the ``auto_route`` preference on, the radio gets the suggested route first,
# when it has no route or a route from another site (refer to
# meshterm.services.device_routes). The write is local. The message is still the
# only transmission, and a failed write never stops it.
routes = getattr(self._ctx, "routes", None)
if routes is not None and self._ctx.preferences.auto_route:
try:
await routes.prepare_message(contact)
except Exception as exc: # noqa: BLE001 - the message goes out anyway
self._ctx.log.warning("couldn't set the route to %s first: %s", contact.name, exc)
acked, codes, flood = await self._deliver_direct(contact, text)
chat = ChatMessage(
text=text,
+604
View File
@@ -0,0 +1,604 @@
# SPDX-License-Identifier: Apache-2.0
"""Device routes: forget, set, and keep the route that the radio uses to each contact.
The companion holds one *device route* for each contact: the relays, in order from our
node outward. It sends each direct message, login, request, and admin command to the
contact on that route. It learns the route from a path return: the answer to a flood that
reached the contact. It does not keep the best route. It replaces the route each time that
a path return arrives, and it never forgets a route that stopped to work. After that, each
packet sent on the route is lost with no error.
This module gives the user control over that route:
* **Forget.** The radio clears the route, so the next message floods, and the radio
learns a new route from the answer (:meth:`RouteKeeper.forget`).
* **Set.** The radio gets a route that the user chose (:meth:`RouteKeeper.set`). It stays
until the radio learns another one.
* **Keep.** MeshTerm remembers the route, and writes it back each time that the radio
replaces it (:meth:`RouteKeeper.keep`). A kept route belongs to the active site, or to a
fixed device (refer to :mod:`meshterm.core.outbound_store`). A kept route whose first
hop is silent is not written: the repeater is probably off, or out of reach from here.
When the user changes site, the routes that the radio learned at the old site start on
hops that are out of reach now. :meth:`RouteKeeper.reconcile` saves them for that site
and clears them from the radio, and writes back the routes saved for the new site. Thus
the routes of the radio follow the user from site to site. The reconcile runs at each
connection and after each change of site.
Each action here is local to the radio: nothing is transmitted, except by
:meth:`RouteKeeper.discover`, which sends one path discovery.
"""
from __future__ import annotations
import asyncio
from dataclasses import dataclass, field
from datetime import datetime, timedelta
from typing import TYPE_CHECKING
from ..core.events import EventKind, MeshEvent
from ..core.models import Contact, DiscoveredRoute, utcnow
from ..core.outbound_store import (
SOURCE_DEVICE,
OutboundStore,
RouteOwner,
RoutePath,
Site,
)
from ..persistence.logging import get_logger
from .outbound import device_identity, session_topology
if TYPE_CHECKING: # pragma: no cover - typing only
from collections.abc import Callable, Iterable
from ..context import AppContext
from ..core.connection import Device
from .topology import MeshTopology
#: How the radio got the route that it holds now (refer to :attr:`RouteStatus.origin`).
ORIGIN_FLOOD = ""
ORIGIN_LEARNED = "learned"
ORIGIN_SET = "set"
ORIGIN_KEPT = "kept"
def _matches(radio_hop: str, hop: str) -> bool:
"""Whether a hop that the radio holds can be the stored hop: one is a prefix of the other.
The radio holds each hop at its hash width (one to three bytes). The store holds a
longer key prefix when it knows one.
"""
radio_hop, hop = radio_hop.lower(), hop.lower()
if not radio_hop or not hop:
return False
return hop.startswith(radio_hop) or radio_hop.startswith(hop)
def same_route(radio: tuple[str, ...] | None, route: RoutePath) -> bool:
"""Whether the route that the radio holds is ``route``, hop by hop, at its own width."""
if radio is None or len(radio) != len(route):
return False
return all(_matches(a, b) for a, b in zip(radio, route, strict=True))
def first_hops(paths: Iterable[tuple[str, ...]]) -> list[str]:
"""The first hop of each outbound path, in order, without duplicates."""
hops: list[str] = []
for path in paths:
if path and path[0] not in hops:
hops.append(path[0])
return hops
def starts_on(route: tuple[str, ...] | None, hops: Iterable[str]) -> bool:
"""Whether a route has a first relay, and that relay is one of ``hops``."""
return bool(route) and any(_matches(route[0], hop) for hop in hops) # type: ignore[index]
def silent_since(
topo: MeshTopology,
route: RoutePath,
contact_key: str,
silent_before: datetime | None,
) -> datetime | None:
"""When the first hop of a route was last heard, if that is before ``silent_before``.
The first hop is the first relay, or the contact itself for a route with no relay. A
first hop with no evidence at all is not silent, because nothing says so. This is the
rule of the outbound paths (refer to
:meth:`~meshterm.services.topology.MeshTopology.outbound_scenarios`).
Returns:
The time of the last packet on the link from our node to the first hop, when the
hop is silent. ``None`` when the hop is not silent.
"""
if silent_before is None:
return None
first = route[0] if route else contact_key.lower()[:12]
node = topo.canonical(first) or first
link = topo.link(topo.self_id, node)
last = link.last_seen if link is not None else None
return last if last is not None and last < silent_before else None
def silent_before_now(ctx: AppContext) -> datetime | None:
"""The time before which a first hop counts as silent (the ``outbound_silent_hours`` window)."""
prefs = getattr(ctx, "preferences", None)
if prefs is None:
return None
return utcnow() - timedelta(hours=prefs.outbound_silent_hours)
@dataclass(frozen=True, slots=True)
class RouteStatus:
"""What MeshTerm knows about the device route to one contact.
Attributes:
hops: The route that the radio holds now, or ``None`` for no route (flood).
origin: How the radio got that route: :data:`ORIGIN_KEPT`, :data:`ORIGIN_SET` (the
user set it in this session), :data:`ORIGIN_LEARNED`, or :data:`ORIGIN_FLOOD`
for no route.
changed_at: When the route changed in this session, if MeshTerm saw it change.
kept: The kept route to the contact, or ``None`` when the user keeps none.
owner: The record that keeps routes for the connected device (the fixed device or
the active site), or ``None`` when none can.
skipped_since: When the kept route is not in the radio because its first hop is
silent, the time that the hop was last heard. Otherwise ``None``.
"""
hops: tuple[str, ...] | None
origin: str
changed_at: datetime | None = None
kept: RoutePath | None = None
owner: RouteOwner | None = None
skipped_since: datetime | None = None
@property
def kept_in_radio(self) -> bool:
"""Whether the radio holds the kept route now."""
return self.kept is not None and same_route(self.hops, self.kept)
@dataclass(slots=True)
class RouteReport:
"""What one reconcile did.
Attributes:
saved: For each other site, how many learned routes MeshTerm saved for it and
cleared from the radio.
restored: How many saved routes of the active site MeshTerm wrote back.
kept_written: How many kept routes MeshTerm wrote back.
kept_skipped: The names of the contacts whose kept route has a silent first hop.
failed: The names of the contacts whose route the radio refused to change.
site: The name of the active site, or ``""``.
"""
saved: dict[str, int] = field(default_factory=dict)
restored: int = 0
kept_written: int = 0
kept_skipped: list[str] = field(default_factory=list)
failed: list[str] = field(default_factory=list)
site: str = ""
@property
def changed(self) -> bool:
"""Whether the reconcile changed a route in the radio."""
return bool(self.saved) or bool(self.restored) or bool(self.kept_written)
def _routes(count: int) -> str:
return f"{count} route" if count == 1 else f"{count} routes"
def report_notice(report: RouteReport) -> str:
"""The notice that tells the user what a reconcile did, or ``""`` when it did nothing."""
parts: list[str] = []
for site, count in report.saved.items():
parts.append(f"saved {_routes(count)} for {site} and cleared them from the radio")
if report.restored:
where = f" for {report.site}" if report.site else ""
parts.append(f"restored {_routes(report.restored)}{where}")
if report.kept_written:
parts.append(f"wrote back {_routes(report.kept_written)} you keep")
if report.kept_skipped:
parts.append(f"skipped {_routes(len(report.kept_skipped))} with a silent first hop")
if report.failed:
parts.append(f"the radio refused {_routes(len(report.failed))}")
if not parts:
return ""
text = " · ".join(parts)
return text[0].upper() + text[1:]
def _key(contact: Contact) -> str:
return (contact.public_key or "").lower().removeprefix("0x")
class RouteKeeper:
"""The session service for device routes: the actions, the reconcile, and the listener.
The interactive session starts it with the other always-on services
(:meth:`start`). Then it listens for the route changes of the radio, and the context
calls :meth:`on_connected` for each stable connection. A scripted CLI run does not
start it, and calls the actions and :meth:`reconcile` directly.
"""
def __init__(self, ctx: AppContext) -> None:
"""Make the service idle."""
self._ctx = ctx
self._armed = False
self._unsubscribe: Callable[[], None] | None = None
self._task: asyncio.Future | None = None
self._settled: int | None = None
#: The routes that MeshTerm wrote in this session, and when, by contact key.
self._written: dict[str, tuple[tuple[str, ...], datetime]] = {}
#: When the radio said that it learned a new route, by contact key.
self._learned: dict[str, datetime] = {}
#: What the last reconcile at connection did, for the menu to show.
self.last_report: RouteReport | None = None
# -- the session --------------------------------------------------------------------
async def start(self) -> None:
"""Listen for route changes, and reconcile a device that is already connected."""
if self._armed:
return
self._armed = True
self._unsubscribe = self._ctx.events.subscribe(self._on_event, EventKind.ROUTE)
device = self._ctx._device
if device is not None:
self.on_connected(device)
def on_connected(self, device: Device) -> None:
"""Reconcile a new stable connection in the background. Idle until :meth:`start`."""
if not self._armed or self._settled == id(device):
return
self._settled = id(device)
self._task = asyncio.ensure_future(self._settle())
async def _settle(self) -> None:
"""Run one reconcile at connection, and write what it did to the log."""
try:
report = await self.reconcile()
except asyncio.CancelledError:
raise
except Exception as exc: # noqa: BLE001 - a best-effort action. It never breaks the session
get_logger().warning("couldn't reconcile the device routes: %s", exc)
return
self.last_report = report
notice = report_notice(report)
if notice:
get_logger().info("device routes: %s", notice)
def _on_event(self, event: MeshEvent): # type: ignore[no-untyped-def]
"""Note a route that the radio learned. Write a kept route back (the hub runs it)."""
change = event.route
if change is None:
return None
self._learned[change.public_key] = utcnow()
self._written.pop(change.public_key, None)
devstate = getattr(self._ctx, "devstate", None)
if devstate is not None:
devstate.invalidate_contacts()
return self._restore_kept(change.public_key)
async def _restore_kept(self, contact_key: str) -> None:
"""Write the kept route to one contact back, after the radio replaced it."""
try:
identity = await device_identity(self._ctx)
kept = self._ctx.outbound_store.kept_route(identity.key or None, contact_key)
if kept is None:
return
contacts = await self._ctx.devstate.contacts()
contact = next((c for c in contacts if _key(c) == contact_key), None)
if contact is None or same_route(contact.route_hops, kept):
return
topo = session_topology(self._ctx, identity.key, contacts)
if silent_since(topo, kept, contact_key, silent_before_now(self._ctx)) is not None:
get_logger().info(
"the radio replaced the kept route to %s; its first hop is silent, so "
"the new route stays",
contact.name,
)
return
await self._write(contact, kept)
get_logger().info("wrote the kept route to %s back to the radio", contact.name)
except Exception as exc: # noqa: BLE001 - a background action. The log says why
get_logger().warning("couldn't write a kept route back: %s", exc)
async def aclose(self) -> None:
"""Stop listening at the end of the session, and stop a reconcile in progress."""
self._armed = False
if self._unsubscribe is not None:
self._unsubscribe()
self._unsubscribe = None
task, self._task = self._task, None
if task is not None and not task.done():
task.cancel()
try:
await task
except (asyncio.CancelledError, Exception): # noqa: BLE001 - ends the session
pass
# -- the actions ----------------------------------------------------------------------
def _invalidate(self) -> None:
devstate = getattr(self._ctx, "devstate", None)
if devstate is not None:
devstate.invalidate_contacts()
async def _write(self, contact: Contact, route: RoutePath) -> tuple[str, ...]:
device = await self._ctx.device()
written = await device.set_route(contact, tuple(route))
self._written[_key(contact)] = (written, utcnow())
self._invalidate()
return written
async def forget(self, contact: Contact) -> None:
"""Clear the device route to ``contact``, so that its next message floods.
A kept route stays kept: the user forgets what the radio holds, not the choice.
"""
device = await self._ctx.device()
await device.reset_route(contact)
self._written.pop(_key(contact), None)
self._invalidate()
async def set(self, contact: Contact, route: RoutePath) -> tuple[str, ...]:
"""Write a device route to ``contact``. It stays until the radio learns another.
Returns:
The route as the radio holds it now, at its hash width.
"""
return await self._write(contact, route)
async def keep(self, contact: Contact, route: RoutePath) -> RouteOwner:
"""Keep a device route to ``contact``, and write it to the radio now.
Returns:
The record that keeps it: the fixed device, or the active site.
Raises:
NoRouteOwnerError: If the device is not fixed and no site is active.
"""
identity = await device_identity(self._ctx)
owner = self._ctx.outbound_store.keep_route(identity.key or None, _key(contact), route)
await self._write(contact, route)
return owner
async def unkeep(self, contact: Contact) -> bool:
"""Stop keeping the route to ``contact``. The radio keeps the route that it holds."""
identity = await device_identity(self._ctx)
return self._ctx.outbound_store.unkeep_route(identity.key or None, _key(contact))
async def discover(self, contact: Contact) -> DiscoveredRoute | None:
"""Send one path discovery to ``contact`` (one flood), and return the two routes."""
device = await self._ctx.device()
return await device.discover_route(contact)
# -- what the pages show ----------------------------------------------------------
def status(
self,
contact: Contact,
*,
device_key: str,
topo: MeshTopology | None = None,
silent_before: datetime | None = None,
) -> RouteStatus:
"""The device route to ``contact``, how it got there, and what the user keeps.
Args:
contact: The contact, as the radio reported it (with its route).
device_key: The public key of the connected companion, or ``""``.
topo: The evidence graph, to find a silent first hop. Without it, no kept route
counts as skipped.
silent_before: The time before which a first hop counts as silent.
"""
store: OutboundStore = self._ctx.outbound_store
key = _key(contact)
owner = store.route_owner(device_key or None)
kept = store.kept_route(device_key or None, key) if key else None
hops = contact.route_hops
written = self._written.get(key)
if hops is None:
origin, changed = ORIGIN_FLOOD, written[1] if written else None
elif kept is not None and same_route(hops, kept):
origin, changed = ORIGIN_KEPT, written[1] if written else None
elif written is not None and same_route(hops, written[0]):
origin, changed = ORIGIN_SET, written[1]
else:
origin, changed = ORIGIN_LEARNED, self._learned.get(key)
skipped = None
if kept is not None and not same_route(hops, kept) and topo is not None:
skipped = silent_since(topo, kept, key, silent_before)
return RouteStatus(hops, origin, changed, kept, owner, skipped)
# -- the reconcile -------------------------------------------------------------------
async def reconcile(self) -> RouteReport:
"""Make the routes of the radio follow the active site and the kept routes.
In order:
1. A route that the radio learned at another site (it starts on a first hop of
that site, and on no first hop of the active site) is saved for that site and
cleared from the radio.
2. The routes saved for the active site are written back, unless the radio learned
a route here since, or the first hop is silent.
3. Each kept route that the radio does not hold is written, unless its first hop is
silent.
Steps 1 and 2 apply only to a device that is not fixed: a fixed device never moves.
Returns:
What the reconcile did.
"""
ctx = self._ctx
store: OutboundStore = ctx.outbound_store
identity = await device_identity(ctx)
device_key = identity.key or None
contacts = await ctx.devstate.contacts(force=True)
topo = session_topology(ctx, identity.key, contacts)
silent_before = silent_before_now(ctx)
by_key = {_key(c): c for c in contacts if _key(c)}
kept = store.kept_routes(device_key)
owner = store.route_owner(device_key)
report = RouteReport(site=owner.name if owner is not None else "")
cleared: set[str] = set()
if owner is not None and owner.source != SOURCE_DEVICE:
active = store.active_site()
if active is not None:
cleared = await self._save_elsewhere(store, active, by_key, kept, report)
await self._restore_saved(store, active, by_key, kept, cleared, topo, report)
for key, route in kept.items():
contact = by_key.get(key)
if contact is None:
continue
radio = None if key in cleared else contact.route_hops
if same_route(radio, route):
continue
if silent_since(topo, route, key, silent_before) is not None:
report.kept_skipped.append(contact.name)
continue
try:
await self._write(contact, route)
report.kept_written += 1
except Exception: # noqa: BLE001 - one refusal must not stop the others
report.failed.append(contact.name)
return report
async def _save_elsewhere(
self,
store: OutboundStore,
active: Site,
by_key: dict[str, Contact],
kept: dict[str, RoutePath],
report: RouteReport,
) -> set[str]:
"""Save and clear the learned routes that start on another site's first hop."""
own = first_hops(active.paths)
others = [
(site.name, first_hops(site.paths))
for site in store.sites()
if site.name.casefold() != active.name.casefold()
]
to_save: dict[str, dict[str, tuple[str, ...]]] = {}
for key, contact in by_key.items():
route = contact.route_hops
if key in kept or not route or starts_on(route, own):
continue
site = next((name for name, hops in others if starts_on(route, hops)), None)
if site is not None:
to_save.setdefault(site, {})[key] = route
cleared: set[str] = set()
if not to_save:
return cleared
device = await self._ctx.device()
for site, routes in to_save.items():
store.save_routes(site, routes)
for key in routes:
try:
await device.reset_route(by_key[key])
cleared.add(key)
except Exception: # noqa: BLE001 - one refusal must not stop the others
report.failed.append(by_key[key].name)
if any(key in cleared for key in routes):
report.saved[site] = sum(1 for key in routes if key in cleared)
self._invalidate()
return cleared
async def _restore_saved(
self,
store: OutboundStore,
active: Site,
by_key: dict[str, Contact],
kept: dict[str, RoutePath],
cleared: set[str],
topo: MeshTopology,
report: RouteReport,
) -> None:
"""Write back the routes saved for the active site, where they still apply."""
silent_before = silent_before_now(self._ctx)
for key, route in store.take_saved(active.name).items():
contact = by_key.get(key)
if contact is None or key in kept:
continue
radio = None if key in cleared else contact.route_hops
if radio is not None:
continue # the radio learned a route here since: it is newer
if silent_since(topo, route, key, silent_before) is not None:
continue
try:
await self._write(contact, route)
report.restored += 1
except Exception: # noqa: BLE001 - one refusal must not stop the others
report.failed.append(contact.name)
async def change_site(self, name: str | None) -> RouteReport | None:
"""Make a site active (or none), then reconcile the routes when a radio is connected.
Returns:
What the reconcile did, or ``None`` when no radio is connected. The next
connection then reconciles.
Raises:
KeyError: If no site has that name.
"""
self._ctx.outbound_store.set_active(name)
if not self._ctx.is_connected:
return None
return await self.reconcile()
# -- automatic routes ------------------------------------------------------------
async def prepare_message(self, contact: Contact) -> tuple[str, ...] | None:
"""Set the suggested route before a direct message, when the ``auto_route`` preference asks.
MeshTerm acts only when the radio has no route to the contact, or when its route
starts on a first hop of another site. A kept route is never changed here: the
reconcile owns it. The write is local, and the message itself is the only
transmission.
Returns:
The route that MeshTerm wrote, or ``None`` when it wrote nothing.
"""
ctx = self._ctx
prefs = getattr(ctx, "preferences", None)
if prefs is None or not prefs.auto_route:
return None
key = _key(contact)
if not key:
return None
store: OutboundStore = ctx.outbound_store
identity = await device_identity(ctx)
if store.kept_route(identity.key or None, key) is not None:
return None
contacts = await ctx.devstate.contacts()
held = next((c for c in contacts if _key(c) == key), None)
if held is None:
return None
choice = store.lookup(identity.key or None)
if held.route_hops is not None:
others = [
hop
for site in store.sites()
if choice.source == SOURCE_DEVICE or site.name.casefold() != choice.name.casefold()
for hop in first_hops(site.paths)
]
own = first_hops(choice.paths)
if not starts_on(held.route_hops, others) or starts_on(held.route_hops, own):
return None
topo = session_topology(ctx, identity.key, contacts)
target = topo.canonical(key[:12]) or key[:12]
outbound = tuple(tuple(topo.canonical(h) or h for h in path) for path in choice.paths)
suggested = topo.suggested(target, outbound=outbound, silent_before=silent_before_now(ctx))
if suggested is None:
return None
written = await self._write(held, suggested.hops)
get_logger().info(
"set the suggested route to %s before the message: %s",
held.name,
",".join(written) or "no relays",
)
return written
+8 -1
View File
@@ -36,6 +36,7 @@ import typer
from ..context import AppContext
from ..core import exitcodes
from ..core.outbound_store import OutboundPath, clean_path
from ..services.device_routes import report_notice
from .base import Tool, ToolResult, register
if TYPE_CHECKING: # pragma: no cover - typing only
@@ -100,7 +101,13 @@ class OutboundTool(Tool):
raise typer.BadParameter(
f"no site is named {name!r}; see `meshterm outbound sites`"
)
store.set_active(name)
# The device routes follow the site when a radio is connected. Otherwise the
# next connection of the menu reconciles them (refer to
# meshterm.services.device_routes).
routes = await ctx.routes.change_site(name)
notice = report_notice(routes) if routes is not None else ""
if notice:
ctx.ui.ack(f"[ok]✓[/ok] {notice}")
active = store.active_site()
shown = active.name if active else None
return _ack(
+4
View File
@@ -1115,6 +1115,10 @@ async def _resume_monitor(ctx: AppContext) -> Exception | None:
# The site suggestion only counts what the hub hears, and the menu asks the user. It
# never opens the device (refer to meshterm.services.site_suggest).
await ctx.site_suggest.start()
# The device routes listen for the route changes of the radio, and reconcile at each
# connection. They write to the radio only what the user keeps or saved for a site
# (refer to meshterm.services.device_routes). Nothing is transmitted.
await ctx.routes.start()
if not ctx.settings.connect_on_start:
return None
failure: Exception | None = None
+33 -4
View File
@@ -40,7 +40,9 @@ from ..core.outbound_store import (
OutboundStore,
clean_path,
)
from ..persistence.logging import get_logger
from ..services import trace_runner
from ..services.device_routes import report_notice
from ..services.outbound import (
DeviceIdentity,
FirstLink,
@@ -159,7 +161,7 @@ async def manage_outbound(ctx: AppContext) -> None:
if name is not None:
store.put_site(name, [])
if store.active_site() is None:
store.set_active(name) # the first site is where the user is
await switch_site(ctx, name) # the first site is where the user is
await _site_page(ctx, env, name)
elif choice == _FIX and env.identity.key:
active = store.active_site()
@@ -298,9 +300,9 @@ async def _site_page(ctx: AppContext, env: _Env, name: str) -> None:
async def act(value: Any) -> bool:
"""Run one action of the site. Return ``True`` when the page must close."""
if value == _USE:
store.set_active(state["name"])
await switch_site(ctx, state["name"])
elif value == _UNUSE:
store.set_active(None)
await switch_site(ctx, None)
elif value == _RENAME:
new = await _ask_site_name(ctx, current=state["name"])
if new is not None and new != state["name"]:
@@ -644,6 +646,33 @@ async def _path_actions(ctx: AppContext, env: _Env, staged: list[OutboundPath],
return 0
async def switch_site(ctx: AppContext, name: str | None) -> None:
"""Make a site active (or none), let the device routes follow, and say what changed.
The routes that the radio learned at the old site are saved for it and cleared, and the
routes saved for the new site come back (refer to
:meth:`~meshterm.services.device_routes.RouteKeeper.change_site`). Each step can be
undone by a change back, so nothing asks first. A notice says what changed, and only
when something changed.
"""
try:
report = await ctx.routes.change_site(name)
except KeyError:
return # the site was deleted while the page was open
except Exception as exc: # noqa: BLE001 - the site changed. Only the routes did not follow
get_logger().warning("couldn't make the device routes follow the site: %s", exc)
await ctx.ui.dialog(
f"The site changed, but the radio refused a route change: {exc}",
[("OK", None)],
title="Device routes",
default=0,
)
return
notice = report_notice(report) if report is not None else ""
if notice:
await ctx.ui.dialog(f"{notice}.", [("OK", None)], title="Device routes", default=0)
async def offer_site(ctx: AppContext, suggestion: SiteSuggestion) -> None:
"""Ask the user to use the site whose way out the radio hears, and say why.
@@ -677,7 +706,7 @@ async def offer_site(ctx: AppContext, suggestion: SiteSuggestion) -> None:
default=2,
)
if answer == "use":
store.set_active(site.name)
await switch_site(ctx, site.name)
elif answer == "never":
ctx.preferences.set("suggest_site", False)
ctx.preferences.save()
+435
View File
@@ -0,0 +1,435 @@
# SPDX-License-Identifier: Apache-2.0
"""Tests for device routes: the store's kept and saved routes, and the device layer."""
from __future__ import annotations
import json
from pathlib import Path
import pytest
from meshterm.core.connection import (
ContactNotOnDeviceError,
DeviceCommandError,
MockDevice,
route_at_width,
)
from meshterm.core.events import EventKind
from meshterm.core.models import Contact
from meshterm.core.outbound_store import (
SOURCE_DEVICE,
SOURCE_SITE,
NoRouteOwnerError,
OutboundStore,
RouteOwner,
clean_route,
)
DEVICE = "c0ffee" * 10 + "abcd" # a public key of 32 bytes
ALICE = "f2c24f54551e" + "0" * 52
BOB = "a100008dc55e" + "1" * 52
HOME = [("3d63c6429436",)]
LAB = [("a100008dc55e",)]
@pytest.fixture
def store(tmp_path: Path) -> OutboundStore:
"""An empty store in a temporary directory."""
return OutboundStore(tmp_path / "outbound.json")
# -- the store -----------------------------------------------------------------------
def test_clean_route_takes_no_hops_as_a_neighbour() -> None:
"""A device route can be empty (no relay), unlike an outbound path."""
assert clean_route([]) == ()
assert clean_route("") == ()
assert clean_route("27D4,f2c2") == ("27d4", "f2c2")
assert clean_route(["27d4", "27d4"]) is None
assert clean_route(["xyz"]) is None
def test_keep_needs_a_site_or_a_fixed_device(store: OutboundStore) -> None:
"""With no active site and no fixed device, no record can keep a route."""
assert store.route_owner(DEVICE) is None
with pytest.raises(NoRouteOwnerError):
store.keep_route(DEVICE, ALICE, ("3d63",))
assert store.kept_routes(DEVICE) == {}
def test_kept_routes_belong_to_the_active_site(store: OutboundStore) -> None:
"""A route kept at Home is not the route at Foulab, and comes back with Home."""
store.put_site("Home", HOME)
store.put_site("Foulab", LAB)
store.set_active("Home")
assert store.keep_route(DEVICE, ALICE, ("3d63", "f2c2")) == RouteOwner(SOURCE_SITE, "Home")
assert store.kept_route(DEVICE, ALICE) == ("3d63", "f2c2")
store.set_active("Foulab")
assert store.kept_route(DEVICE, ALICE) is None
store.set_active("Home")
assert store.kept_route(DEVICE, ALICE.upper()) == ("3d63", "f2c2")
def test_a_fixed_device_keeps_its_own_routes(store: OutboundStore) -> None:
"""The fixed device's record comes before the active site, for routes too."""
store.put_site("Home", HOME)
store.set_active("Home")
store.keep_route(DEVICE, ALICE, ("3d63",))
store.fix_device(DEVICE, "Roof", [])
assert store.route_owner(DEVICE) == RouteOwner(SOURCE_DEVICE, "Roof")
assert store.kept_route(DEVICE, ALICE) is None
store.keep_route(DEVICE, ALICE, ())
assert store.kept_route(DEVICE, ALICE) == ()
store.fix_device(DEVICE, "Roof", [("27d4",)]) # new paths keep the routes
assert store.kept_route(DEVICE, ALICE) == ()
assert store.unkeep_route(DEVICE, ALICE)
assert not store.unkeep_route(DEVICE, ALICE)
def test_a_rename_keeps_the_routes_of_the_site(store: OutboundStore) -> None:
"""New paths or a new name do not lose the kept and saved routes."""
store.put_site("Home", HOME)
store.set_active("Home")
store.keep_route(DEVICE, ALICE, ("3d63",))
store.save_routes("Home", {BOB: ("27",)})
store.put_site("Maison", [("27d4",)], old_name="Home")
assert store.kept_route(DEVICE, ALICE) == ("3d63",)
assert store.saved_routes("Maison") == {BOB: ("27",)}
def test_saved_routes_are_taken_one_time(store: OutboundStore) -> None:
"""A take returns the saved routes and empties them. A newer save replaces an older."""
store.put_site("Home", HOME)
store.save_routes("Home", {ALICE: ("3d",), BOB: ()})
store.save_routes("Home", {ALICE: ("27",)})
assert store.take_saved("Home") == {ALICE: ("27",), BOB: ()}
assert store.take_saved("Home") == {}
with pytest.raises(KeyError):
store.save_routes("Nowhere", {ALICE: ()})
def test_routes_are_written_from_the_records(tmp_path: Path) -> None:
"""A bad route or a bad contact key does not survive a write."""
path = tmp_path / "outbound.json"
path.write_text(
json.dumps(
{
"active": "Home",
"sites": [
{
"name": "Home",
"paths": [],
"kept": {ALICE: ["3d63"], "NOTHEX": ["3d"], BOB: ["zz"]},
"saved": {BOB: []},
}
],
}
),
encoding="utf-8",
)
store = OutboundStore(path)
store.set_active("Home")
written = json.loads(path.read_text(encoding="utf-8"))
assert written["sites"][0]["kept"] == {ALICE: ["3d63"]}
assert written["sites"][0]["saved"] == {BOB: []}
# -- the device layer ------------------------------------------------------------------
def test_route_at_width_cuts_each_hop_and_refuses_what_the_radio_cannot_hold() -> None:
"""Each hop goes in at the radio's width. A short hop or a long route is refused."""
assert route_at_width(["3D63C6", "27d4"], 2) == ("3d63", "27d4")
assert route_at_width([], 1) == ()
with pytest.raises(DeviceCommandError, match="shorter"):
route_at_width(["3d"], 2)
with pytest.raises(DeviceCommandError, match="not a hop"):
route_at_width(["xyz"], 1)
with pytest.raises(DeviceCommandError, match="at most 32"):
route_at_width([f"{i:04x}" for i in range(33)], 2)
def _held(device: MockDevice, name: str) -> Contact:
return next(c for c in device._contacts if c.name == name)
async def test_the_mock_sets_and_forgets_a_route() -> None:
"""Set writes the route at the radio's width. Reset makes the contact flood."""
device = MockDevice()
alice = _held(device, "Alice")
assert await device.set_route(alice, ("b2c3d4e5", "a1b2c3d4")) == ("b2", "a1")
assert _held(device, "Alice").route_hops == ("b2", "a1")
assert await device.set_route(alice, ()) == ()
await device.reset_route(alice)
assert _held(device, "Alice").route_hops is None
with pytest.raises(ContactNotOnDeviceError):
await device.set_route(Contact(name="Stranger", public_key="ee" * 32), ())
async def test_the_mock_discovers_a_route_each_way() -> None:
"""A path discovery gives the out route and the in route, and changes nothing."""
device = MockDevice()
alice = _held(device, "Alice")
before = alice.route_hops
found = await device.discover_route(alice)
assert found is not None
assert found.out_hops == ("a1",)
assert found.in_hops == ("a1",)
assert _held(device, "Alice").route_hops == before
device._unreachable.add("Alice")
assert await device.discover_route(alice) is None
async def test_a_learned_route_is_pushed_as_a_route_change() -> None:
"""The mock pushes a route change when the answer to a flood teaches it a route."""
device = MockDevice()
events = []
unsubscribe = await device.subscribe_events(events.append)
try:
held = _held(device, "Alice")
device._set_route(device._mock_key(held), ("a1",), learned=True)
finally:
unsubscribe()
changes = [e.route for e in events if e.kind is EventKind.ROUTE]
assert [c.public_key for c in changes] == [held.public_key.lower()]
# -- the service -----------------------------------------------------------------------
class _DevState:
"""The parts of the device state cache that the service reads."""
def __init__(self, device: MockDevice) -> None:
self.device = device
self.invalidated = 0
async def contacts(self, *, force: bool = False) -> list[Contact]:
return list(self.device._contacts)
async def self_info(self) -> dict:
return {"public_key": DEVICE, "name": "Homestead"}
def invalidate_contacts(self) -> None:
self.invalidated += 1
class _Repo:
"""A repository with no evidence: no first hop is silent."""
def trace_paths(self) -> list:
return []
def packet_paths(self) -> list:
return []
def neighbour_links(self) -> list:
return []
def _ctx(tmp_path: Path, device: MockDevice, *, auto_route: bool = False): # noqa: ANN202
from types import SimpleNamespace
async def get_device() -> MockDevice:
return device
return SimpleNamespace(
outbound_store=OutboundStore(tmp_path / "outbound.json"),
devstate=_DevState(device),
device=get_device,
repo=_Repo(),
preferences=SimpleNamespace(outbound_silent_hours=24, auto_route=auto_route),
is_connected=True,
_device=device,
)
YAGI = "a1b2c3d4" # the first hop of Home in these tests (Alice's route starts on it)
LOCAL = "b2c3d4e5" # the first hop of Foulab (Observer-Bot's route starts on it)
def _sites(ctx) -> None: # noqa: ANN001
ctx.outbound_store.put_site("Home", [(YAGI,)])
ctx.outbound_store.put_site("Foulab", [(LOCAL,)])
async def test_a_site_change_saves_clears_and_restores_learned_routes(tmp_path: Path) -> None:
"""At Foulab, Home's routes are saved and cleared. Back at Home, they come back."""
from meshterm.services.device_routes import RouteKeeper, report_notice
device = MockDevice()
ctx = _ctx(tmp_path, device)
_sites(ctx)
keeper = RouteKeeper(ctx)
report = await keeper.change_site("Foulab")
assert report is not None
assert report.saved == {"Home": 2} # Alice and the room both start on Yagi
assert _held(device, "Alice").route_hops is None # cleared: it started on Yagi
assert _held(device, "Lakeside BBS").route_hops is None
assert _held(device, "Observer-Bot").route_hops == (LOCAL,) # Foulab's own: it stays
alice = _held(device, "Alice").public_key.lower()
room = _held(device, "Lakeside BBS").public_key.lower()
assert ctx.outbound_store.saved_routes("Home") == {alice: (YAGI,), room: (YAGI,)}
assert report_notice(report) == "Saved 2 routes for Home and cleared them from the radio"
report = await keeper.change_site("Home")
assert report is not None
assert report.saved == {"Foulab": 1}
assert report.restored == 2
assert _held(device, "Alice").route_hops == ("a1",) # back, at the radio's width
assert _held(device, "Observer-Bot").route_hops is None
assert ctx.outbound_store.saved_routes("Home") == {}
async def test_a_route_learned_here_since_wins_over_a_saved_one(tmp_path: Path) -> None:
"""A saved route is not written over a route that the radio learned at this site."""
from meshterm.services.device_routes import RouteKeeper
device = MockDevice()
ctx = _ctx(tmp_path, device)
_sites(ctx)
ctx.outbound_store.set_active("Home")
alice = _held(device, "Alice")
ctx.outbound_store.save_routes("Home", {alice.public_key.lower(): (LOCAL,)})
report = await RouteKeeper(ctx).reconcile()
assert report.restored == 0
assert _held(device, "Alice").route_hops == (YAGI,)
async def test_kept_routes_are_written_and_a_silent_first_hop_is_skipped(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""The reconcile writes each kept route that the radio lacks, unless its hop is silent."""
from datetime import datetime, timezone
from meshterm.services import device_routes
from meshterm.services.device_routes import ORIGIN_KEPT, RouteKeeper
device = MockDevice()
ctx = _ctx(tmp_path, device)
_sites(ctx)
ctx.outbound_store.set_active("Home")
alice = _held(device, "Alice")
bob = _held(device, "Observer-Bot")
store = ctx.outbound_store
store.keep_route(DEVICE, alice.public_key, (LOCAL, YAGI))
store.keep_route(DEVICE, bob.public_key, ("c3d4e5f6",))
long_ago = datetime(2026, 1, 1, tzinfo=timezone.utc)
def silent(topo, route, key, before): # noqa: ANN001, ANN202
return long_ago if route and route[0] == "c3d4e5f6" else None
monkeypatch.setattr(device_routes, "silent_since", silent)
keeper = RouteKeeper(ctx)
report = await keeper.reconcile()
assert report.kept_written == 1
assert report.kept_skipped == ["Observer-Bot"]
assert _held(device, "Alice").route_hops == ("b2", "a1")
status = keeper.status(_held(device, "Alice"), device_key=DEVICE)
assert status.origin == ORIGIN_KEPT
assert status.kept_in_radio
async def test_the_actions_and_the_origin_of_a_route(tmp_path: Path) -> None:
"""Set marks the route as set by you. Keep needs a site. Forget makes it flood."""
from meshterm.core.outbound_store import NoRouteOwnerError
from meshterm.services.device_routes import (
ORIGIN_FLOOD,
ORIGIN_LEARNED,
ORIGIN_SET,
RouteKeeper,
)
device = MockDevice()
ctx = _ctx(tmp_path, device)
keeper = RouteKeeper(ctx)
alice = _held(device, "Alice")
assert keeper.status(alice, device_key=DEVICE).origin == ORIGIN_LEARNED
await keeper.set(alice, (LOCAL,))
assert keeper.status(_held(device, "Alice"), device_key=DEVICE).origin == ORIGIN_SET
with pytest.raises(NoRouteOwnerError):
await keeper.keep(alice, (LOCAL,))
await keeper.forget(alice)
assert keeper.status(_held(device, "Alice"), device_key=DEVICE).origin == ORIGIN_FLOOD
assert ctx.devstate.invalidated >= 2
async def test_auto_route_sets_the_suggested_route_only_when_asked(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""With the preference off nothing happens. On, a contact with no route gets one."""
from types import SimpleNamespace
from meshterm.services import device_routes
from meshterm.services.device_routes import RouteKeeper
device = MockDevice()
alice = _held(device, "Alice")
await device.reset_route(alice)
ctx = _ctx(tmp_path, device)
assert await RouteKeeper(ctx).prepare_message(alice) is None
ctx = _ctx(tmp_path, device, auto_route=True)
class _Topo:
self_id = "local"
def canonical(self, hop: str) -> str:
return hop
def suggested(self, target, *, outbound, silent_before): # noqa: ANN001, ANN202
return SimpleNamespace(hops=(LOCAL,))
monkeypatch.setattr(device_routes, "session_topology", lambda *a: _Topo())
assert await RouteKeeper(ctx).prepare_message(alice) == ("b2",)
# A route that the radio holds, and that starts on no other site's hop, stays.
assert await RouteKeeper(ctx).prepare_message(_held(device, "Alice")) is None
async def test_the_radio_gets_the_fresh_record_with_only_the_route_changed() -> None:
"""set_route reads the radio's record and changes its route only (flags and name stay)."""
from types import SimpleNamespace
from meshterm.core.connection import MeshCoreDevice
key = "ab" * 32
record = {
"public_key": key,
"type": 1,
"flags": 1,
"out_path_len": -1,
"out_path_hash_mode": 0,
"out_path": "",
"adv_name": "Alice",
"last_advert": 1_700_000_000,
"adv_lat": 45.5,
"adv_lon": -73.6,
}
calls: list[tuple[dict, str, int]] = []
async def get_contact_by_key(pubkey: bytes): # noqa: ANN202
return SimpleNamespace(payload=dict(record), is_error=lambda: False)
async def change_contact_path(contact: dict, path: str, path_hash_mode: int): # noqa: ANN202
calls.append((contact, path, path_hash_mode))
return SimpleNamespace(payload={}, is_error=lambda: False)
async def get_path_hash_mode() -> int:
return 1
device = MeshCoreDevice(port="mock")
device._mc = SimpleNamespace(
commands=SimpleNamespace(
get_contact_by_key=get_contact_by_key,
change_contact_path=change_contact_path,
get_path_hash_mode=get_path_hash_mode,
)
)
alice = Contact(name="Alice", public_key=key)
assert await device.set_route(alice, ("3d63c6", "27d4aa")) == ("3d63", "27d4")
((sent, path, mode),) = calls
assert sent == record # the fresh record, unchanged: the library adds the route
assert (path, mode) == ("3d6327d4", 1)
with pytest.raises(DeviceCommandError, match="key prefix"):
await device.set_route(Contact(name="Short", public_key="ab12"), ())
+2 -2
View File
@@ -125,8 +125,8 @@ def test_the_file_is_written_from_the_records(tmp_path: Path) -> None:
written = json.loads(path.read_text(encoding="utf-8"))
assert written == {
"active": "Home",
"sites": [{"name": "Home", "paths": [["3d63"]]}],
"devices": {DEVICE: {"name": "Roof", "paths": [["3d"]]}},
"sites": [{"name": "Home", "paths": [["3d63"]], "kept": {}, "saved": {}}],
"devices": {DEVICE: {"name": "Roof", "paths": [["3d"]], "kept": {}}},
}