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:
1 parent
73ae08b365
commit
88d0d94ca7
13 files changed
+1618
-15
No files matched your search
@@ -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
@@ -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.
|
||||
|
||||
|
||||
@@ -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."""
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
@@ -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",
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
|
||||
@@ -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(
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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()
|
||||
|
||||
@@ -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"), ())
|
||||
@@ -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": {}}},
|
||||
}
|
||||
|
||||
|
||||
|
||||
Reference in new issue
Block a user