Sites and fixed devices keep their outbound paths

core/outbound_store.py keeps, in outbound.json, the sites of this computer
with their outbound paths in order, the active site, and the fixed devices
with their own paths. lookup() gives the fixed device's paths, else the
active site's, else none. The glossary gains outbound path, site, and fixed
device.

Refs: #35

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Haiku 5.5 committed 2026-11-07 13:06:08 -05:00
1 parent e2146f9092
commit c50656c586
5 files changed
+574

No files matched your search

+3
View File
@@ -183,6 +183,9 @@ and in quoted text.
| path | An ordered list of hops that you write or force (`a1,3d,…`) | |
| route | The sequence of nodes that a trace went through or will go through | |
| hop | One node in a path or a route | |
| outbound path | A path that starts at our node and goes out into the mesh, one or more hops long. The user trusts it for the first hops of a route, because the user knows which way out works | outbound leg (for this: an outbound leg is the outbound half of a trace) |
| site | A name for where the user takes the computer (`Home`, `Foulab`), with its outbound paths in order. One site is active | profile (for this: a profile is a connection alias in `config.toml`) |
| fixed device | A companion that never moves. It keeps its own outbound paths, and the active site does not apply to it | |
| via | The prefix for the relay chain of a packet or a message | |
| location | The coordinates (latitude and longitude) that a node advertises | coordinates (alone) |
| place | The named area nearest the location of a node: a neighbourhood, a village, a town, or a peak. It has a fine part and a coarse part (`Villeray, Montréal`) | location name, locality |
+7
View File
@@ -24,6 +24,7 @@ from .core.courier_store import CourierStore
from .core.device_store import DeviceStore
from .core.discovery import DiscoveredDevice, discover_devices
from .core.mute_store import MuteStore
from .core.outbound_store import OutboundStore
from .core.place_store import PlaceStore
from .core.preferences import PREFERENCES_FILENAME, Preferences, report_dropped
from .core.preferences import install as install_preferences
@@ -106,6 +107,9 @@ class AppContext:
place_store: The store for the places that the user typed for nodes. A typed place
wins over a found place (if the caller does not inject it, the default is
``<config_dir>/places.json``).
outbound_store: The store for the outbound paths: the sites of this computer, the
active site, and the fixed devices (if the caller does not inject it, the
default is ``<config_dir>/outbound.json``).
mock: Whether the context uses the simulator device.
demo: Whether the simulator is the demo world of ``--demo``
(:mod:`meshterm.demo`), which implies ``mock``.
@@ -151,6 +155,7 @@ class AppContext:
contact_store: ContactStore | None = None
room_store: RoomStore | None = None
place_store: PlaceStore | None = None
outbound_store: OutboundStore | None = None
profile: DeviceProfile | None = None
mock: bool = False
demo: bool = False
@@ -234,6 +239,8 @@ class AppContext:
self.room_store = RoomStore(self.settings.config_dir / "rooms.json")
if self.place_store is None:
self.place_store = PlaceStore(self.settings.config_dir / "places.json")
if self.outbound_store is None:
self.outbound_store = OutboundStore(self.settings.config_dir / "outbound.json")
@property
def profile_name(self) -> str | None:
+426
View File
@@ -0,0 +1,426 @@
# SPDX-License-Identifier: Apache-2.0
"""The store for outbound paths: the sites of this computer, and the fixed devices.
An *outbound path* is a path that starts at our node and goes out into the mesh, one or
more hops long. The user trusts it to carry the first hops of a route. A radio link is not
symmetric. A repeater that our node hears well can hear our node badly, and the evidence of
MeshTerm comes mostly from what our node hears. Thus the user, who knows which way out
works, gives these paths, in order of preference. The route suggestions then start on one
of them (refer to :meth:`~meshterm.services.topology.MeshTopology.scenarios`).
The paths depend on where the radio is. MeshTerm runs on a computer that the user takes
from site to site, with whichever companion is at hand. Thus the paths belong to the
computer, not to the radio, and this store keeps them in two forms:
* **Sites.** Each site (``Home``, ``Foulab``, ``Work``) has a name and an ordered list of
outbound paths. One site is *active*: the site where the user is now. It applies to each
companion that MeshTerm connects to.
* **Fixed devices.** A companion that never moves (a radio on the roof, a uConsole on a
shelf) keeps its own list. The key is the public key of the companion. The active site
does not apply to a fixed device.
: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.
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
written back from them. The store never writes back the raw JSON that it read. Thus a field
that no record knows is removed after the next write.
"""
from __future__ import annotations
import json
from dataclasses import dataclass, field
from pathlib import Path
from typing import ClassVar
from .atomicwrite import write_atomically
#: One outbound path: the hops in order from our node outward. Each hop is lowercase hex,
#: usually the 12-digit key prefix of the node, or a shorter hash that the user typed.
OutboundPath = 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.
SOURCE_SITE = "site"
_HEX = frozenset("0123456789abcdef")
def clean_hop(value: object) -> str | None:
"""A hop as the store keeps it, or ``None`` when the value cannot be a hop.
A hop is a whole number of bytes in hex, from one byte to a full public key. The store
keeps it in lowercase, so that a comparison never depends on how the user typed it.
Args:
value: The raw hop, from the file or from the user.
Returns:
The hop in lowercase hex, or ``None``.
"""
if not isinstance(value, str):
return None
hop = value.strip().lower()
if not hop or len(hop) % 2 or len(hop) > 64 or not set(hop) <= _HEX:
return None
return hop
def clean_path(value: object) -> OutboundPath | None:
"""An outbound path as the store keeps it, or ``None`` when the value is not one.
A path must have at least one hop, and each hop must pass :func:`clean_hop`. A node
that comes two times in a path is never useful, because repeaters discard a packet that
they relayed before. Thus such a path is not valid either.
Args:
value: The raw path: a list of hops, or a comma-separated spec (``"27d4,f2c2"``).
Returns:
The path as a tuple of hops, or ``None``.
"""
if isinstance(value, str):
value = [part for part in value.split(",") if part.strip()]
if not isinstance(value, list | tuple) or not value:
return None
hops = tuple(clean_hop(hop) for hop in value)
if any(hop is None for hop in hops) or len(set(hops)) != len(hops):
return None
return hops # type: ignore[return-value] - the check above removed each None
def _clean_paths(raw: object) -> list[OutboundPath]:
"""The valid outbound paths of a file entry, in order, without duplicates."""
paths: list[OutboundPath] = []
for entry in raw if isinstance(raw, list) else []:
path = clean_path(entry)
if path is not None and path not in paths:
paths.append(path)
return paths
@dataclass(slots=True)
class Site:
"""One site: a name, and the outbound paths that work there, in order of preference.
Attributes:
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.
"""
name: str
paths: list[OutboundPath] = field(default_factory=list)
#: 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
#: reason that a name is never used again). There are none yet.
RETIRED: ClassVar[frozenset[str]] = frozenset()
@classmethod
def read(cls, raw: object) -> Site | None:
"""Build a site from one file entry, or ``None`` when the entry has no name."""
if not isinstance(raw, dict):
return None
name = str(raw.get("name") or "").strip()
if not name:
return None
return cls(name=name, paths=_clean_paths(raw.get("paths")))
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]}
@dataclass(slots=True)
class FixedDevice:
"""A companion that never moves, and its own outbound paths.
Attributes:
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.
"""
name: str
paths: list[OutboundPath] = field(default_factory=list)
#: The fields that this record held before. There are none yet (refer to
#: :attr:`Site.RETIRED`).
RETIRED: ClassVar[frozenset[str]] = frozenset()
@classmethod
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")))
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]}
@dataclass(slots=True)
class _OutboundFile:
"""All of the file: the sites, the active site, and the fixed devices.
Attributes:
sites: The sites, in the order in which the user made them.
active: The name of the active site, or ``None`` when no site is active.
devices: The fixed devices, with the lowercase public key of each as the key.
"""
sites: list[Site] = field(default_factory=list)
active: str | None = None
devices: dict[str, FixedDevice] = field(default_factory=dict)
#: The fields that this record held before. There are none yet (refer to
#: :attr:`Site.RETIRED`).
RETIRED: ClassVar[frozenset[str]] = frozenset()
@classmethod
def read(cls, raw: object) -> _OutboundFile:
"""Build the records from the parsed file, with only the fields that they know.
A second site with the name of an earlier site is not read. An active name that
names no site reads as no active site.
"""
record = raw if isinstance(raw, dict) else {}
sites: list[Site] = []
for entry in record.get("sites") if isinstance(record.get("sites"), list) else []:
site = Site.read(entry)
if site is not None and _find(sites, site.name) is None:
sites.append(site)
active = _find(sites, str(record.get("active") or ""))
devices: dict[str, FixedDevice] = {}
raw_devices = record.get("devices")
if isinstance(raw_devices, dict):
for key, entry in raw_devices.items():
device_key = clean_hop(key)
if device_key is not None:
devices[device_key] = FixedDevice.read(entry)
return cls(sites=sites, active=active.name if active else None, devices=devices)
def to_json(self) -> dict:
"""The file as written: its own fields only."""
return {
"active": self.active,
"sites": [site.to_json() for site in self.sites],
"devices": {key: device.to_json() for key, device in self.devices.items()},
}
@dataclass(frozen=True, slots=True)
class OutboundChoice:
"""The outbound paths that apply to one device, and where they come from.
Attributes:
paths: The outbound paths, the preferred path first. The tuple is empty when no
list applies.
source: :data:`SOURCE_DEVICE` for the list of a fixed device,
:data:`SOURCE_SITE` for the list of the active site, or ``""`` for no list.
name: The name of the site, or the name of the fixed device. It is ``""`` when
no list applies.
"""
paths: tuple[OutboundPath, ...] = ()
source: str = ""
name: str = ""
def _find(sites: list[Site], name: str) -> Site | None:
"""The site with ``name``, without regard to case, or ``None``."""
wanted = name.strip().casefold()
return (
next((site for site in sites if site.name.casefold() == wanted), None) if wanted else None
)
class OutboundStore:
"""Reads and writes the sites, the active site, and the fixed devices."""
def __init__(self, path: Path) -> None:
"""Open the store on the location of a JSON file.
Args:
path: Path to the JSON file (made only at the first write).
"""
self._path = path
def _load(self) -> _OutboundFile:
"""Read the file into records (empty records when the file is absent or corrupt)."""
try:
data = json.loads(self._path.read_text(encoding="utf-8"))
except (OSError, ValueError):
return _OutboundFile()
return _OutboundFile.read(data)
def _write(self, records: _OutboundFile) -> None:
"""Write ``records`` atomically.
If a crash occurs during the write, the previous file stays.
"""
write_atomically(self._path, json.dumps(records.to_json(), indent=2))
# -- sites ----------------------------------------------------------------------
def sites(self) -> list[Site]:
"""All the sites, in the order in which the user made them."""
return self._load().sites
def site(self, name: str) -> Site | None:
"""The site with ``name``, without regard to case, or ``None``."""
return _find(self._load().sites, name)
def active_site(self) -> Site | None:
"""The active site, or ``None`` when no site is active."""
records = self._load()
return _find(records.sites, records.active or "")
def set_active(self, name: str | None) -> None:
"""Make the site with ``name`` active, or make no site active with ``None``.
Raises:
KeyError: If no site has that name.
"""
records = self._load()
if name is None:
records.active = None
else:
site = _find(records.sites, name)
if site is None:
raise KeyError(name)
records.active = site.name
self._write(records)
def put_site(
self, name: str, paths: list[OutboundPath], *, old_name: str | None = None
) -> Site:
"""Make a site, or replace the paths (and the name) of a site.
Args:
name: The name of the site. The spelling that the user gives is kept.
paths: Its outbound paths, the preferred path first. Duplicates are removed.
old_name: The current name of a site that this call renames. Omit it to make
a site, or to replace the paths of the site with ``name``.
Returns:
The site as stored.
Raises:
ValueError: If the name is empty, or if another site already has it.
KeyError: If ``old_name`` names no site.
"""
name = name.strip()
if not name:
raise ValueError("a site needs a name")
records = self._load()
current = _find(records.sites, old_name if old_name is not None else name)
if old_name is not None and current is None:
raise KeyError(old_name)
clash = _find(records.sites, name)
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 None:
records.sites.append(site)
else:
records.sites[records.sites.index(current)] = site
if records.active is not None and records.active.casefold() == current.name.casefold():
records.active = site.name
self._write(records)
return site
def remove_site(self, name: str) -> bool:
"""Delete the site with ``name``. When it was active, no site is active after this.
Returns:
Whether a site was deleted.
"""
records = self._load()
site = _find(records.sites, name)
if site is None:
return False
records.sites.remove(site)
if records.active is not None and records.active.casefold() == site.name.casefold():
records.active = None
self._write(records)
return True
# -- fixed devices --------------------------------------------------------------
def fixed_devices(self) -> dict[str, FixedDevice]:
"""The fixed devices, with the lowercase public key of each as the key."""
return self._load().devices
def fixed_device(self, device_key: str) -> FixedDevice | None:
"""The record of a fixed device, or ``None`` when the device is not fixed."""
key = clean_hop(device_key)
return self._load().devices.get(key) if key else None
def fix_device(self, device_key: str, name: str, paths: list[OutboundPath]) -> FixedDevice:
"""Fix a device, or replace the paths of a fixed device.
Args:
device_key: The public key of the companion.
name: The name of the companion now, for the list of fixed devices.
paths: Its outbound paths, the preferred path first. An empty list is valid:
the device then has no outbound paths, whatever site is active.
Returns:
The fixed device as stored.
Raises:
ValueError: If ``device_key`` is not a key in hex.
"""
key = clean_hop(device_key)
if key is None:
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]))
records.devices[key] = device
self._write(records)
return device
def unfix_device(self, device_key: str) -> bool:
"""Remove the fixed list of a device, so that the active site applies to it again.
Returns:
Whether the device was fixed.
"""
key = clean_hop(device_key)
records = self._load()
if key is None or records.devices.pop(key, None) is None:
return False
self._write(records)
return True
# -- the lookup -----------------------------------------------------------------
def lookup(self, device_key: str | None) -> OutboundChoice:
"""The outbound paths that apply to the device with ``device_key``.
The order is: the list of the fixed device, then the list of the active site, then
no list. A fixed device keeps its list also when the list is empty. The user fixed
the device to say what applies to it, and "nothing" is a valid answer.
Args:
device_key: The public key of the connected companion, or ``None`` when it is
not known (then only the active site can apply).
Returns:
The paths, with their source.
"""
records = self._load()
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 OutboundChoice(tuple(device.paths), SOURCE_DEVICE, device.name)
site = _find(records.sites, records.active or "")
if site is not None:
return OutboundChoice(tuple(site.paths), SOURCE_SITE, site.name)
return OutboundChoice()
+1
View File
@@ -51,6 +51,7 @@ _STORES = (
"adverts.json",
"devices.json",
"places.json",
"outbound.json",
)
+137
View File
@@ -0,0 +1,137 @@
# SPDX-License-Identifier: Apache-2.0
"""Tests for the store of outbound paths: sites, the active site, fixed devices, the lookup."""
from __future__ import annotations
import json
from pathlib import Path
import pytest
from meshterm.core.outbound_store import (
SOURCE_DEVICE,
SOURCE_SITE,
OutboundChoice,
OutboundStore,
clean_path,
)
DEVICE = "c0ffee" * 10 + "abcd" # a public key of 32 bytes
HOME = [("3d63c6429436",), ("27d4396a2967", "f2c24f54551e")]
LAB = [("a100008dc55e",)]
@pytest.fixture
def store(tmp_path: Path) -> OutboundStore:
"""An empty store in a temporary directory."""
return OutboundStore(tmp_path / "outbound.json")
def test_clean_path_takes_a_list_or_a_spec_and_refuses_junk() -> None:
"""A path is whole bytes of hex, at least one hop, and no node two times."""
assert clean_path(["27D4", " f2c2 "]) == ("27d4", "f2c2")
assert clean_path("27d4,f2c2") == ("27d4", "f2c2")
assert clean_path([]) is None
assert clean_path(["27d"]) is None # half a byte
assert clean_path(["zz"]) is None
assert clean_path(["27d4", "27d4"]) is None # a node two times is never useful
def test_an_empty_store_applies_no_list(store: OutboundStore) -> None:
"""With no site and no fixed device, the lookup gives nothing."""
assert store.sites() == []
assert store.active_site() is None
assert store.lookup(DEVICE) == OutboundChoice()
def test_the_active_site_applies_to_each_device(store: OutboundStore) -> None:
"""The active site is the answer for each device that is not fixed."""
store.put_site("Home", HOME)
store.put_site("Foulab", LAB)
store.set_active("foulab") # names match without regard to case
assert store.lookup(DEVICE) == OutboundChoice(tuple(LAB), SOURCE_SITE, "Foulab")
assert store.lookup(None).name == "Foulab" # an unknown device still gets the site
def test_a_fixed_device_keeps_its_own_list_whatever_site_is_active(store: OutboundStore) -> None:
"""A fixed device wins over the active site, also with an empty list."""
store.put_site("Home", HOME)
store.set_active("Home")
store.fix_device(DEVICE.upper(), "uConsole", LAB)
assert store.lookup(DEVICE) == OutboundChoice(tuple(LAB), SOURCE_DEVICE, "uConsole")
assert store.lookup("ab" * 32).source == SOURCE_SITE # another device follows the site
store.fix_device(DEVICE, "uConsole", [])
assert store.lookup(DEVICE) == OutboundChoice((), SOURCE_DEVICE, "uConsole")
assert store.unfix_device(DEVICE)
assert store.lookup(DEVICE).source == SOURCE_SITE
assert not store.unfix_device(DEVICE)
def test_site_names_are_unique_and_a_rename_keeps_the_site_active(store: OutboundStore) -> None:
"""Two sites cannot share a name, and an active site stays active when it is renamed."""
store.put_site("Home", HOME)
store.put_site("Work", LAB)
store.set_active("Home")
with pytest.raises(ValueError, match="already exists"):
store.put_site("WORK", HOME, old_name="Home") # a rename onto another site
store.put_site("Maison", HOME, old_name="home")
assert [site.name for site in store.sites()] == ["Maison", "Work"]
assert store.active_site().name == "Maison"
with pytest.raises(ValueError):
store.put_site(" ", HOME)
with pytest.raises(KeyError):
store.put_site("School", HOME, old_name="Nowhere")
with pytest.raises(KeyError):
store.set_active("Nowhere")
def test_a_put_with_the_same_name_replaces_the_paths(store: OutboundStore) -> None:
"""A put on a name that exists replaces that site, and removes duplicate paths."""
store.put_site("Home", HOME)
store.put_site("HOME", [*LAB, *LAB])
assert [(site.name, site.paths) for site in store.sites()] == [("HOME", LAB)]
def test_removing_the_active_site_leaves_no_site_active(store: OutboundStore) -> None:
"""A deleted site cannot stay active."""
store.put_site("Home", HOME)
store.set_active("Home")
assert store.remove_site("home")
assert store.active_site() is None
assert not store.remove_site("home")
def test_the_file_is_written_from_the_records(tmp_path: Path) -> None:
"""A field that no record knows, a bad path, and a duplicate site do not survive a write."""
path = tmp_path / "outbound.json"
path.write_text(
json.dumps(
{
"active": "Lost",
"legacy": 1,
"sites": [
{"name": "Home", "paths": [["3d63"], ["xyz"], []], "colour": "red"},
{"name": "home", "paths": [["27d4"]]},
{"paths": [["27d4"]]},
],
"devices": {"NOTHEX": {"name": "x"}, DEVICE: {"name": "Roof", "paths": [["3d"]]}},
}
),
encoding="utf-8",
)
store = OutboundStore(path)
assert store.active_site() is None # the active name named no site
store.set_active("Home")
written = json.loads(path.read_text(encoding="utf-8"))
assert written == {
"active": "Home",
"sites": [{"name": "Home", "paths": [["3d63"]]}],
"devices": {DEVICE: {"name": "Roof", "paths": [["3d"]]}},
}
def test_a_corrupt_file_reads_as_empty(tmp_path: Path) -> None:
"""A file that is not JSON gives the empty answer, not an error."""
path = tmp_path / "outbound.json"
path.write_text("{not json", encoding="utf-8")
assert OutboundStore(path).lookup(DEVICE) == OutboundChoice()