From c50656c58688a4106ab2e5a2e11210a64751ca02 Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Sat, 7 Nov 2026 13:06:08 -0500 Subject: [PATCH] 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 --- docs/development/writing-style.md | 3 + meshterm/context.py | 7 + meshterm/core/outbound_store.py | 426 ++++++++++++++++++++++++++++++ meshterm/demo/home.py | 1 + tests/test_outbound_store.py | 137 ++++++++++ 5 files changed, 574 insertions(+) create mode 100644 meshterm/core/outbound_store.py create mode 100644 tests/test_outbound_store.py diff --git a/docs/development/writing-style.md b/docs/development/writing-style.md index 80e6250..9b98fad 100644 --- a/docs/development/writing-style.md +++ b/docs/development/writing-style.md @@ -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 | diff --git a/meshterm/context.py b/meshterm/context.py index d42f240..c23c7dc 100644 --- a/meshterm/context.py +++ b/meshterm/context.py @@ -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 ``/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 ``/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: diff --git a/meshterm/core/outbound_store.py b/meshterm/core/outbound_store.py new file mode 100644 index 0000000..9bfa7a8 --- /dev/null +++ b/meshterm/core/outbound_store.py @@ -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 ``/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() diff --git a/meshterm/demo/home.py b/meshterm/demo/home.py index 9a29079..df52bc5 100644 --- a/meshterm/demo/home.py +++ b/meshterm/demo/home.py @@ -51,6 +51,7 @@ _STORES = ( "adverts.json", "devices.json", "places.json", + "outbound.json", ) diff --git a/tests/test_outbound_store.py b/tests/test_outbound_store.py new file mode 100644 index 0000000..02557b4 --- /dev/null +++ b/tests/test_outbound_store.py @@ -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()