diff --git a/meshterm/core/connection.py b/meshterm/core/connection.py index a2b8505..8860dbb 100644 --- a/meshterm/core/connection.py +++ b/meshterm/core/connection.py @@ -45,6 +45,7 @@ from .models import ( advert_time, utcnow, ) +from .region_sim import SimulatedRegionMap from .regions import WILDCARD as REGION_WILDCARD from .regions import normalize as normalize_region from .regions import parse_region_list, region_key @@ -3371,6 +3372,36 @@ class MockDevice(Device): ("a1b2c3d4", -3.25, 900), ], } + # Simulated region tables, keyed like the neighbour tables: one per repeater, what + # its ``region`` CLI edits and the anonymous regions request reads. Yagi's fits in + # one reply; Local's is deliberately too big for the 160-byte reply buffer, so the + # region editor's cut-and-recover path is drivable without hardware. + self._region_maps: dict[str, SimulatedRegionMap] = { + "a1b2c3d4": SimulatedRegionMap( + [ + ("lakeside", "*", True), + ("lakeside-north", "lakeside", True), + ("lakeside-south", "lakeside", False), + ("harbour", "*", True), + ] + ), + "b2c3d4e5": SimulatedRegionMap( + [ + ("lakeside", "*", True), + ("lakeside-north", "lakeside", True), + ("lakeside-south", "lakeside", False), + ("harbour", "*", True), + ("harbour-east", "harbour", True), + ("harbour-west", "harbour", True), + ("old-town", "*", False), + ("old-town-market", "old-town", True), + ("riverside", "*", True), + ("riverside-upper", "riverside", True), + ("riverside-lower", "riverside", False), + ("hilltop", "*", True), + ] + ), + } # Mutable configuration state, keyed exactly like the real SELF_INFO payload so the # settings registry behaves identically on the simulator and on hardware. self._info: dict = { @@ -3564,6 +3595,11 @@ class MockDevice(Device): return "OK - clock synced" if parts[1:] == ["sync"] else "12:00 - 1/1/2026 UTC" if verb == "advert": return "OK - Advert sent" + regions = self._region_maps.get(node.key_prefix or "") + if verb == "region" and regions is not None: + return regions.command(command.strip()) + if verb == "reboot" and regions is not None: + regions.reboot() # a power cycle drops every region edit not saved if verb in ("reboot", "password", "time", "start"): return "OK" if verb == "neighbors": @@ -3658,12 +3694,17 @@ class MockDevice(Device): async def request_regions(self, node: Contact) -> list[str]: # noqa: D102 await asyncio.sleep(0) key = self._mock_key(node) - # Only a node with a neighbour table is a repeater here, and only a repeater answers. - if self._neighbour_tables.get(key[:8]) is None: + # Only a node with a region table is a repeater here, and only a repeater answers. + regions = self._region_maps.get(node.key_prefix or key[:8]) + if node.name in self._unreachable: + raise DeviceCommandError( + f"{node.name!r} did not answer the regions request (out of direct reach)." + ) + if regions is None: raise DeviceCommandError( f"{node.name!r} did not answer the regions request (not a repeater)." ) - return parse_region_list("*,lakeside,lakeside-north,harbour") + return parse_region_list(regions.allowed_names()) @staticmethod def _mock_key(node: Contact) -> str: diff --git a/meshterm/core/region_admin.py b/meshterm/core/region_admin.py new file mode 100644 index 0000000..4dd3514 --- /dev/null +++ b/meshterm/core/region_admin.py @@ -0,0 +1,520 @@ +# SPDX-License-Identifier: Apache-2.0 +"""A repeater's region table as its CLI shows it: the parser, the commands, the edits. + +A MeshCore repeater keeps a small table of regions (at most 32) in a tree under the +wildcard ``*``, and relays a *scoped* flood only when the flood's region is one it lists as +flood-allowed (see :mod:`~meshterm.core.regions` for the maths that ties a flood to its +region). The tree is **organisational only**: a repeater relays exactly the regions it +lists as allowed, so allowing ``lakeside`` says nothing about ``lakeside-north`` beneath it. +The wildcard's own flag is the unscoped case — whether it relays plain floods at all. + +The admin reads and edits that table over the remote CLI (firmware ``CommonCLI:: +handleRegionCmd``, ``RegionMap``), and this module is everything about it that is not a +screen: + +* **The dump** (:func:`parse_region_dump`). ``region`` answers with the tree, one region per + line, each line indented one space per level below the wildcard, the name followed by + ``^`` on the home region and `` F`` where floods are allowed:: + + *^ F + lakeside F + lakeside-north F + lakeside-south + harbour F + +* **The cut.** Every CLI reply is written into a 160-byte buffer (``exportTo(reply, 160)``), + and the dump simply stops where the buffer ends — mid-line, mid-name, with nothing to say + it did. A table of 32 regions with real names does not fit, so a dump near the cap is read + as *possibly cut* (:data:`REPLY_CAP_BYTES`, :func:`parse_region_dump`), its unfinished last + line is dropped rather than shown as a region with half a name, and the reader is told. + The flat lists (``region list allowed`` / ``region list denied``) are how the rest is + recovered (:func:`parse_name_list`, :func:`RegionTable.with_lists`) — they carry no parent, + so those regions are shown *beyond the cut*, placed nowhere. The lists have a cap of their + own and skip a name that would not fit rather than cutting it, so a list close enough to + the cap to have skipped one is flagged too (:func:`list_may_be_incomplete`). Nothing here + ever claims to hold the whole table when it cannot know. + +* **The commands** (:func:`allow_command` and siblings). Every edit is one remote command, + and each is spelled here exactly once. ``allowf``/``denyf``/``home`` match a name by + *prefix* on the firmware, preferring an exact match — MeshTerm only ever sends names the + repeater itself listed, so the exact match always wins. + +* **The edits** (:meth:`RegionTable.after`). What a command the repeater accepted does to the + table, so the editor redraws from the reply rather than spending another round trip on a + re-read. ``region put`` of a name that already exists *moves* it on the firmware, which is + why the editor refuses a name it can see is taken. + +* **Persistence.** Every edit lives in the repeater's RAM until ``region save``; a reboot + undoes whatever was not saved. The one exception is ``region default`` (firmware 1.15+), + which saves the whole table itself — its reply (``default scope is now …``) is how an edit + says it took the unsaved ones with it (:func:`saves_table`). +""" + +from __future__ import annotations + +from collections.abc import Iterable +from dataclasses import dataclass, replace + +from .regions import MAX_NAME_BYTES, WILDCARD, RegionNameError, validate + +#: The firmware's CLI reply buffer, in bytes. ``BufStream`` stops one short of it (the NUL), +#: so a dump that ran out of room arrives 159 bytes long. +REPLY_CAP_BYTES = 160 + +#: How close to the cap a dump must come to be read as possibly cut. A cut can land inside +#: a multi-byte UTF-8 name, which the decode on the way here may shorten by a few bytes, and +#: the transport may strip a trailing newline — so the test leaves room for both rather +#: than asking for exactly 159. +_CUT_SLACK = 4 + +#: The command that dumps the tree. +DUMP_COMMAND = "region" +#: The command that asks which region is the default scope (firmware 1.15+). +DEFAULT_QUERY = "region default" +#: The two flat lists — every flood-allowed and every flood-denied name, ``*`` included. +LIST_ALLOWED = "region list allowed" +LIST_DENIED = "region list denied" +#: The command that writes the table to flash. Nothing else survives a reboot. +SAVE_COMMAND = "region save" + +#: The token ``region default`` takes to clear the default scope. +NULL_DEFAULT = "" + +#: What an empty flat list reads as on the repeater. +_EMPTY_LIST = "-none-" + + +# -- the table ----------------------------------------------------------------------- + + +@dataclass(frozen=True, slots=True) +class RegionRow: + """One region in a repeater's table. + + Attributes: + name: The bare region name (``*`` for the wildcard). + parent: The parent's name — ``*`` for a top-level region, ``None`` for the wildcard + itself and for a region recovered from a flat list, whose place is unknown. + depth: Levels below the wildcard (0 for the wildcard, 1 for a top-level region). + flood: Whether the repeater relays floods scoped to it (``F``) — for the wildcard, + whether it relays unscoped floods. + home: Whether it is the repeater's home region (``^``). + placed: ``False`` for a region known only from a flat list: it is in the table, + but the dump was cut before it, so its parent and depth are not known. + """ + + name: str + parent: str | None + depth: int + flood: bool + home: bool = False + placed: bool = True + + @property + def wildcard(self) -> bool: + """Whether this row is the wildcard — the unscoped case, not a region.""" + return self.name == WILDCARD + + +@dataclass(frozen=True, slots=True) +class RegionTable: + """What MeshTerm knows of one repeater's region table. + + Attributes: + rows: The wildcard first (when the dump reached it), then every region in dump order + (depth-first, as the firmware prints the tree), then any recovered from the flat + lists after a cut (``placed=False``). + cut: Whether the dump may have been cut at the reply cap — rows after ``cut_after`` + may exist that the tree does not show. + cut_after: The last region the dump showed whole (``None`` when it showed none). + lists_read: Whether the flat lists were read to recover what the cut hid. + lists_partial: Whether either flat list came close enough to its own cap that a + name may have been skipped — the recovered set may still be short. + default: The default-scope region, ``None`` where there is none, and absent + knowledge is :attr:`default_known` ``False`` (older firmware has no such query). + default_known: Whether ``default`` was actually read. + """ + + rows: tuple[RegionRow, ...] = () + cut: bool = False + cut_after: str | None = None + lists_read: bool = False + lists_partial: bool = False + default: str | None = None + default_known: bool = False + + # -- reading it --------------------------------------------------------------- + + def get(self, name: str) -> RegionRow | None: + """The row for ``name``, or ``None`` when the table (as known) has no such region.""" + return next((row for row in self.rows if row.name == name), None) + + @property + def wildcard(self) -> RegionRow | None: + """The wildcard's row, or ``None`` when the dump never reached it.""" + return self.get(WILDCARD) + + def regions(self) -> list[RegionRow]: + """Every region row, the wildcard left out.""" + return [row for row in self.rows if not row.wildcard] + + def children(self, name: str) -> list[RegionRow]: + """The regions directly under ``name`` (placed rows only — nothing else has a parent).""" + return [row for row in self.rows if row.parent == name and not row.wildcard] + + @property + def home(self) -> str | None: + """The home region's name (``*`` when none was set), or ``None`` when not seen.""" + return next((row.name for row in self.rows if row.home), None) + + @property + def complete(self) -> bool: + """Whether every region the repeater holds is (to the best of our reading) here. + + A clean dump is complete. A cut one is complete again once both flat lists were read + and neither came near its own cap — the tree is still partly unplaced, but no name + is missing. + """ + return not self.cut or (self.lists_read and not self.lists_partial) + + def carried(self) -> list[str]: + """What the repeater relays floods for, as the regions request would list it. + + ``*`` first when it relays unscoped floods, then every flood-allowed region — the + exact shape :meth:`~meshterm.core.region_store.RegionStore.learn_carried` takes. + """ + wild = self.wildcard + head = [WILDCARD] if wild is not None and wild.flood else [] + return head + [row.name for row in self.regions() if row.flood] + + # -- editing it --------------------------------------------------------------- + + def after(self, command: str, reply: str) -> RegionTable: + """The table as it stands once the repeater accepted ``command``. + + Only the verbs this module spells are understood; anything else (or a refused + reply — see :func:`region_refused`) returns the table unchanged, so a caller may + fold every accepted reply through here without first asking what it was. + + Args: + command: The command sent, as built by this module. + reply: The repeater's reply to it. + + Returns: + The updated table (a new object; tables are immutable). + """ + if region_refused(reply): + return self + parts = command.split() + if len(parts) < 2 or parts[0] != "region": + return self + verb, args = parts[1], parts[2:] + if verb in ("allowf", "denyf") and args: + return self._with(args[0], flood=verb == "allowf") + if verb == "home" and args: + if self.get(args[0]) is None: + return self + rows = tuple(replace(row, home=row.name == args[0]) for row in self.rows) + return replace(self, rows=rows) + if verb == "default" and args: + if args[0] == NULL_DEFAULT: + return replace(self, default=None, default_known=True) + # The firmware forces flood on for the default region, and creates it at the top + # level if it did not exist. + table = self if self.get(args[0]) else self._put(args[0], WILDCARD, flood=True) + return replace(table._with(args[0], flood=True), default=args[0], default_known=True) + if verb == "put" and args: + parent = args[1] if len(args) > 1 else WILDCARD + # 1.15+ answers "OK - (flood allowed)"; older firmware created it denied. + return self._put(args[0], parent, flood="flood allowed" in reply.lower()) + if verb == "remove" and args: + if self.children(args[0]): + return self # the firmware refuses this; a reply claiming otherwise is noise + rows = tuple(row for row in self.rows if row.name != args[0]) + default = None if self.default == args[0] else self.default + return replace(self, rows=rows, default=default) + return self + + def _with(self, name: str, **changes: object) -> RegionTable: + """The table with one row's fields changed (unchanged when the row is not here).""" + rows = tuple(replace(row, **changes) if row.name == name else row for row in self.rows) + return replace(self, rows=rows) + + def _put(self, name: str, parent: str, *, flood: bool) -> RegionTable: + """The table with a new region placed as the last child of ``parent``. + + Dump order is depth-first, so the new row goes after the parent's last descendant — + exactly where the next ``region`` dump would print it. + """ + if self.get(name) is not None: + return self + above = self.get(parent) + depth = (above.depth + 1) if above is not None and above.placed else 1 + row = RegionRow(name=name, parent=parent, depth=depth, flood=flood) + rows = list(self.rows) + at = len(rows) + if above is not None and above.placed: + at = rows.index(above) + 1 + while at < len(rows) and rows[at].placed and rows[at].depth > above.depth: + at += 1 + else: + # An unplaced parent has no subtree to append to: keep placed rows together and + # put the new one ahead of the unplaced tail. + at = next((i for i, r in enumerate(rows) if not r.placed), len(rows)) + rows.insert(at, row) + return replace(self, rows=tuple(rows)) + + def with_lists(self, allowed: str | None, denied: str | None) -> RegionTable: + """Fold the two flat lists into a cut table, recovering the regions the cut hid. + + A name in a list that the tree did not show joins it unplaced, flooded as its list + says. Names the tree already has keep their tree row — the tree has the parent the + list lacks — and the wildcard's flag is taken from the lists when the tree never + reached it (it always does, being the first line, unless the reply was empty). + + Args: + allowed: The reply to :data:`LIST_ALLOWED` (``None`` when it never came). + denied: The reply to :data:`LIST_DENIED` (``None`` when it never came). + + Returns: + The table with the recovered rows appended; ``lists_read`` is set only when both + lists answered, and ``lists_partial`` when either may have skipped a name. + """ + rows = list(self.rows) + partial = False + for reply, flood in ((allowed, True), (denied, False)): + if reply is None or region_refused(reply): + continue + partial = partial or list_may_be_incomplete(reply) + for name in parse_name_list(reply): + if any(row.name == name for row in rows): + continue + if name == WILDCARD: + rows.insert(0, RegionRow(name=WILDCARD, parent=None, depth=0, flood=flood)) + else: + rows.append( + RegionRow(name=name, parent=None, depth=1, flood=flood, placed=False) + ) + both = ( + allowed is not None + and denied is not None + and not region_refused(allowed) + and not region_refused(denied) + ) + return replace(self, rows=tuple(rows), lists_read=both, lists_partial=partial) + + def with_default(self, reply: str | None) -> RegionTable: + """The table with the default scope read from a :data:`DEFAULT_QUERY` reply. + + Unchanged (``default_known`` left ``False``) when there was no reply or the firmware + does not know the query — pre-1.15 answers it with its catch-all ``Err - ??``. + """ + parsed = parse_default_reply(reply) + if parsed is None: + return self + return replace(self, default=parsed or None, default_known=True) + + +# -- parsing --------------------------------------------------------------------------- + + +def dump_may_be_cut(text: str) -> bool: + """Whether a reply came close enough to the 160-byte cap to have been cut short.""" + return len(text.encode("utf-8")) >= REPLY_CAP_BYTES - 1 - _CUT_SLACK + + +def parse_region_dump(text: str | None) -> RegionTable: + """Parse a ``region`` dump into a table, dropping a line the reply cap cut in half. + + Each non-blank line is one region: its leading spaces are its depth, then the name, an + optional ``^`` (home), and an optional ``F`` (flood allowed) after a space. A line's + parent is the nearest line above it one level up; depth 0 is the wildcard. A line that + does not fit the grammar, or whose indentation skips a level, is not guessed at — it + ends the tree there and the table is marked cut, since a dump that stops making sense + has stopped being the dump. + + Args: + text: The reply text (``None`` or empty reads as an empty, uncut table). + + Returns: + The table. When the reply came within reach of the cap its last line is dropped + unless the reply ended on a newline (so the line is known whole), ``cut`` is set, + and ``cut_after`` names the last region shown. + """ + if not text: + return RegionTable() + raw = text.replace("\r", "").replace("\x00", "") + cut = dump_may_be_cut(raw) + lines = raw.split("\n") + if cut and not raw.endswith("\n") and lines: + lines = lines[:-1] # the line the buffer ran out inside — a name may be half a name + rows: list[RegionRow] = [] + stack: list[str] = [] # the open ancestor at each depth + for line in lines: + if not line.strip(): + continue + depth = len(line) - len(line.lstrip(" ")) + row = _parse_line(line.strip(), depth, stack) + if row is None: + cut = True + break + del stack[depth:] + stack.append(row.name) + rows.append(row) + cut_after = next((row.name for row in reversed(rows)), None) if cut else None + return RegionTable(rows=tuple(rows), cut=cut, cut_after=cut_after) + + +def _parse_line(body: str, depth: int, stack: list[str]) -> RegionRow | None: + """One dump line, or ``None`` when it breaks the grammar (see :func:`parse_region_dump`).""" + tokens = body.split() + if not tokens or len(tokens) > 2 or (len(tokens) == 2 and tokens[1] != "F"): + return None + name = tokens[0] + home = name.endswith("^") + name = name.removesuffix("^") + if not name or depth > len(stack): + return None + if depth == 0 and name != WILDCARD: + return None + if depth > 0 and name == WILDCARD: + return None + parent = stack[depth - 1] if depth > 0 else None + return RegionRow(name=name, parent=parent, depth=depth, flood=len(tokens) == 2, home=home) + + +def parse_name_list(text: str | None) -> list[str]: + """The names in a ``region list allowed|denied`` reply (``-none-`` reads as empty).""" + if not text or text.strip() == _EMPTY_LIST: + return [] + names: list[str] = [] + for part in text.replace("\x00", "").split(","): + name = part.strip().removeprefix("#") + if name and name not in names: + names.append(name) + return names + + +def list_may_be_incomplete(text: str) -> bool: + """Whether a flat list came near enough its cap that a name may have been skipped. + + The firmware appends a name only while ``length + len(name) + 2 < 160`` and skips one + that would not fit — then carries on with the next, so a later short name can still get + in. A skip therefore needs the list to have reached at least ``158 - len(name)`` bytes + for some name of at most :data:`~meshterm.core.regions.MAX_NAME_BYTES`, and a list + shorter than that skipped nothing. + """ + return len(text.encode("utf-8")) >= REPLY_CAP_BYTES - 2 - MAX_NAME_BYTES + + +def parse_default_reply(text: str | None) -> str | None: + """The default scope named by a ``region default`` reply. + + Returns: + The region name, ``""`` for none (````), or ``None`` when the reply is + missing, refused, or not a default-scope answer at all. + """ + if not text or region_refused(text): + return None + marker = "default scope is" + lowered = text.lower() + if marker not in lowered: + return None + rest = text[lowered.index(marker) + len(marker) :].strip() + rest = rest.removeprefix("now").strip() + name = rest.split()[0] if rest.split() else "" + return "" if name in ("", NULL_DEFAULT) else name.removeprefix("#") + + +def region_refused(reply: str | None) -> bool: + """Whether a reply to a region command is the repeater refusing it. + + The region verbs answer ``Err - …`` (``unknown region``, ``not empty``, ``unable to + put``, ``save failed``, and ``??`` for a verb the firmware lacks), which the settings + catalog's own error test does not recognise. Older firmware with no ``region`` command + at all answers its generic unknown-command text. + """ + if reply is None: + return True + lowered = reply.strip().lower() + return lowered.startswith(("err", "??", "unknown command", "error")) + + +def saves_table(command: str, reply: str | None) -> bool: + """Whether an accepted command wrote the whole table to flash on its own. + + ``region save`` does, by definition; ``region default`` does too on firmware 1.15+, + which is the firmware that answers it with ``default scope is now …``. + """ + if reply is None or region_refused(reply): + return False + if command == SAVE_COMMAND: + return True + return command.startswith("region default ") and "default scope is now" in reply.lower() + + +# -- the commands ------------------------------------------------------------------ + + +def allow_command(name: str) -> str: + """Relay floods scoped to ``name`` (``*``: relay unscoped floods).""" + return f"region allowf {name}" + + +def deny_command(name: str) -> str: + """Stop relaying floods scoped to ``name`` (``*``: stop relaying unscoped floods).""" + return f"region denyf {name}" + + +def home_command(name: str) -> str: + """Make ``name`` the repeater's home region (``*`` clears it back to none).""" + return f"region home {name}" + + +def default_command(name: str | None) -> str: + """Make ``name`` the default scope for the repeater's own floods, or clear it (``None``).""" + return f"region default {name or NULL_DEFAULT}" + + +def put_command(name: str, parent: str = WILDCARD) -> str: + """Add ``name`` under ``parent`` (top level for ``*``). New regions are flood-allowed.""" + return f"region put {name}" if parent == WILDCARD else f"region put {name} {parent}" + + +def remove_command(name: str) -> str: + """Remove ``name`` — refused by the firmware while it still has sub-regions.""" + return f"region remove {name}" + + +def _is_name_char(ch: str) -> bool: + """Whether the firmware's ``RegionMap::is_name_char`` accepts ``ch`` in a region name.""" + return ch in "-$#" or ch.isdigit() or ord(ch) >= ord("A") + + +def validate_new_name(name: str, taken: Iterable[str] = ()) -> str: + """Check a name for ``region put``, the firmware's own rules and one of MeshTerm's. + + On top of :func:`~meshterm.core.regions.validate` (length, no wildcard, no private + ``$`` names), the firmware refuses a name with any punctuation but ``-`` — its + ``is_name_char`` — and ``region put`` of a name that exists *moves* that region rather + than adding one, so a name already in the table is refused here instead. + + Args: + name: The name as typed. + taken: Names already in the table. + + Returns: + The bare, valid name. + + Raises: + RegionNameError: With the reason, in words a reader can act on. + """ + bare = validate(name) + bad = sorted({ch for ch in bare if not _is_name_char(ch)}) + if bad: + raise RegionNameError( + f"a repeater refuses {' '.join(bad)} in a region name — letters, digits and - only" + ) + if bare in set(taken): + raise RegionNameError(f"{bare} is already a region here") + return bare diff --git a/meshterm/core/region_sim.py b/meshterm/core/region_sim.py new file mode 100644 index 0000000..404f927 --- /dev/null +++ b/meshterm/core/region_sim.py @@ -0,0 +1,244 @@ +# SPDX-License-Identifier: Apache-2.0 +"""A repeater's region table and region CLI, as the simulator speaks them. + +The :class:`~meshterm.core.connection.MockDevice` answers ``region …`` commands and the +anonymous regions request from one of these per simulated repeater, so the node page, the +region editor and the ``regions`` command are all drivable under ``--mock``. + +It is a transcription of the firmware rather than an idea of it — ``RegionMap`` and +``CommonCLI::handleRegionCmd`` as of MeshCore 1.15/1.16 — because the parser it feeds +(:mod:`~meshterm.core.region_admin`) is meant for the real thing, and a simulator that +answered more kindly than a repeater would let a parser bug through. So it keeps the +firmware's awkward edges on purpose: the 160-byte reply buffer that cuts a long dump +mid-name, the flat lists that *skip* a name that would not fit, prefix matching on +``allowf``/``denyf``/``home``/``get``, ``put`` of an existing name moving it, ``remove`` +refusing a region with children, new regions flood-allowed, ``default`` creating a missing +region and saving the table, and every other edit living in RAM until ``save`` +(:meth:`SimulatedRegionMap.reboot` puts the saved table back). +""" + +from __future__ import annotations + +import copy +from dataclasses import dataclass + +from .region_admin import REPLY_CAP_BYTES +from .regions import WILDCARD + +#: The firmware's table size (``MAX_REGION_ENTRIES``). +MAX_REGIONS = 32 + + +@dataclass(slots=True) +class _Entry: + """One ``RegionEntry``: an id, its parent's id, the deny-flood flag, and the name.""" + + id: int + parent: int + deny_flood: bool + name: str + + +class SimulatedRegionMap: + """One simulated repeater's region table and the CLI verbs that edit it.""" + + def __init__(self, tree: list[tuple[str, str, bool]] | None = None) -> None: + """Build a table, already saved, from ``(name, parent, flood)`` triples in order. + + Args: + tree: The regions, each after its parent (``*`` for top level). ``None`` is an + empty table: a stock repeater relaying unscoped floods and nothing else. + """ + self._wild_deny = False + self._entries: list[_Entry] = [] + self._next_id = 1 + self._home = 0 + self._default = 0 + for name, parent, flood in tree or (): + parent_id = 0 if parent == WILDCARD else self._by_name(parent).id # type: ignore[union-attr] + entry = self._put(name, parent_id) + assert entry is not None + entry.deny_flood = not flood + self._saved = self._snapshot() + + # -- the RegionMap ------------------------------------------------------------ + + def _snapshot(self) -> tuple: + return copy.deepcopy( + (self._wild_deny, self._entries, self._next_id, self._home, self._default) + ) + + def reboot(self) -> None: + """Drop every unsaved edit, as a power cycle does.""" + (self._wild_deny, self._entries, self._next_id, self._home, self._default) = copy.deepcopy( + self._saved + ) + + def _by_name(self, name: str) -> _Entry | None: + """``findByName``: an exact match (``*`` is the wildcard, reported as ``None`` here).""" + name = name.removeprefix("#") + return next((e for e in self._entries if e.name.removeprefix("#") == name), None) + + def _by_prefix(self, prefix: str) -> _Entry | str | None: + """``findByNamePrefix``: exact wins, else the *last* prefix match; ``*`` → ``"*"``.""" + if prefix == WILDCARD: + return WILDCARD + prefix = prefix.removeprefix("#") + partial = None + for entry in self._entries: + bare = entry.name.removeprefix("#") + if bare == prefix: + return entry + if bare.startswith(prefix): + partial = entry + return partial + + def _put(self, name: str, parent_id: int) -> _Entry | None: + """``putRegion``: refuse bad characters, move an existing name, else append.""" + if not all(ch in "-$#" or ch.isdigit() or ord(ch) >= ord("A") for ch in name): + return None + entry = self._by_name(name) + if entry is not None: + if entry.id == parent_id: + return None + entry.parent = parent_id + return entry + if len(self._entries) >= MAX_REGIONS: + return None + entry = _Entry(id=self._next_id, parent=parent_id, deny_flood=True, name=name) + self._next_id += 1 + self._entries.append(entry) + return entry + + def _dump(self) -> str: + """``exportTo(reply, 160)``: the tree, cut where the buffer runs out.""" + out: list[str] = [] + + def visit(indent: int, entry_id: int, name: str, deny: bool) -> None: + home = "^" if entry_id == self._home else "" + out.append( + " " * indent + f"{name.removeprefix('#')}{home}" + ("" if deny else " F") + "\n" + ) + for child in self._entries: + if child.parent == entry_id: + visit(indent + 1, child.id, child.name, child.deny_flood) + + visit(0, 0, WILDCARD, self._wild_deny) + return _capped("".join(out)) + + def _names(self, *, allowed: bool) -> str: + """``exportNamesTo(reply, 160, …)``: comma-joined, skipping what will not fit.""" + parts: list[str] = [] + length = 0 + if self._wild_deny != allowed: + parts.append(WILDCARD) + length = 2 + for entry in self._entries: + if entry.deny_flood == allowed: + continue + bare = entry.name.removeprefix("#") + size = len(bare.encode("utf-8")) + if length + size + 2 < REPLY_CAP_BYTES: + parts.append(bare) + length += size + 1 + return ",".join(parts) + + def allowed_names(self) -> str: + """What the anonymous regions request answers with (``*`` first when unscoped).""" + return self._names(allowed=True) + + # -- the CLI ------------------------------------------------------------------ + + def command(self, text: str) -> str: + """Answer one ``region …`` command as ``handleRegionCmd`` does.""" + parts = text.split() + n = len(parts) + if n == 1: + return self._dump() + verb = parts[1] + if verb == "save": + self._saved = self._snapshot() + return "OK" + if verb in ("allowf", "denyf") and n >= 3: + found = self._by_prefix(parts[2]) + if found is None: + return "Err - unknown region" + if found == WILDCARD: + self._wild_deny = verb == "denyf" + else: + found.deny_flood = verb == "denyf" # type: ignore[union-attr] + return "OK" + if verb == "get" and n >= 3: + found = self._by_prefix(parts[2]) + if found is None: + return "Err - unknown region" + if found == WILDCARD: + return f" * {'' if self._wild_deny else 'F'}" + parent = next((e for e in self._entries if e.id == found.parent), None) # type: ignore[union-attr] + flag = "" if found.deny_flood else "F" # type: ignore[union-attr] + if parent is not None: + return f" {found.name} ({parent.name}) {flag}" # type: ignore[union-attr] + return f" {found.name} {flag}" # type: ignore[union-attr] + if verb == "home": + if n == 2: + home = next((e.name for e in self._entries if e.id == self._home), WILDCARD) + return f" home is {home}" + found = self._by_prefix(parts[2]) + if found is None: + return "Err - unknown region" + self._home = 0 if found == WILDCARD else found.id # type: ignore[union-attr] + return f" home is now {WILDCARD if found == WILDCARD else found.name}" # type: ignore[union-attr] + if verb == "default": + if n == 2: + current = next((e.name for e in self._entries if e.id == self._default), None) + return f" default scope is {current or ''}" + if parts[2] == "": + self._default = 0 + self._saved = self._snapshot() + return " default scope is now " + found = self._by_prefix(parts[2]) + if found == WILDCARD: + self._wild_deny = False + self._default = 0 + self._saved = self._snapshot() + return " default scope is now *" + if found is None: + found = self._put(parts[2], 0) + if found is None: + return "Err - region table full" + found.deny_flood = False # type: ignore[union-attr] + self._default = found.id # type: ignore[union-attr] + self._saved = self._snapshot() + return f" default scope is now {found.name}" # type: ignore[union-attr] + if verb == "put" and n >= 3: + if n >= 4: + parent = self._by_prefix(parts[3]) + if parent is None: + return "Err - unknown parent" + parent_id = 0 if parent == WILDCARD else parent.id # type: ignore[union-attr] + else: + parent_id = 0 + entry = self._put(parts[2], parent_id) + if entry is None: + return "Err - unable to put" + entry.deny_flood = False + return "OK - (flood allowed)" + if verb == "remove" and n >= 3: + entry = self._by_name(parts[2]) + if entry is None: + return "Err - not found" + if any(e.parent == entry.id for e in self._entries): + return "Err - not empty" + self._entries.remove(entry) + return "OK" + if verb == "list" and n >= 3: + if parts[2] not in ("allowed", "denied"): + return "Err - use 'allowed' or 'denied'" + return self._names(allowed=parts[2] == "allowed") or "-none-" + return "Err - ??" + + +def _capped(text: str) -> str: + """``BufStream``: bytes past the 159th are dropped, whatever they were in the middle of.""" + raw = text.encode("utf-8")[: REPLY_CAP_BYTES - 1] + return raw.decode("utf-8", errors="ignore") diff --git a/meshterm/core/region_store.py b/meshterm/core/region_store.py index f048e4b..9024e7e 100644 --- a/meshterm/core/region_store.py +++ b/meshterm/core/region_store.py @@ -11,7 +11,8 @@ wherever MeshTerm meets one: * ``repeater`` — a repeater's answer to the regions request, or its ``region`` listing, which also records *which* repeaters carry it (the node page lists them, and a scoped send that nothing relayed can say whether anything in earshot was ever heard to carry - its region); + its region) — and, beside the regions, each repeater's last whole answer: whether it + relays unscoped floods too, and when it said so (:class:`CarriedAnswer`); * ``typed`` — a name the reader entered themselves. The store also holds **channel scopes**: the region a channel's messages are sent under. @@ -80,6 +81,30 @@ class KnownRegion: RETIRED: ClassVar[frozenset[str]] = frozenset() +@dataclass(frozen=True) +class CarriedAnswer: + """The last whole answer one repeater gave about what it carries. + + The regions themselves live on :class:`KnownRegion` (``repeaters``), where resolution + wants them; this keeps what does not belong to any one region — whether the repeater + also relays *unscoped* floods (the ``*`` a region list leads with, which names no + region), and when it said so. A repeater with no record here was never asked, which is + a different thing from a repeater that answered with nothing. + + Attributes: + node: The repeater's 12-hex node id. + unscoped: Whether its answer included the wildcard. + answered_at: When it answered (UTC). + """ + + node: str + unscoped: bool + answered_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc)) + + #: Fields this record once held and must never hold again under another meaning. + RETIRED: ClassVar[frozenset[str]] = frozenset() + + class RegionStore: """Reads and writes the known regions and the channel scopes, memory-first. @@ -99,6 +124,7 @@ class RegionStore: self._path = path self._regions: dict[str, KnownRegion] | None = None self._channels: dict[str, str] = {} + self._answers: dict[str, CarriedAnswer] = {} self._memo: dict[tuple[bytes, int], str | None] = {} self.revision = 0 @@ -108,17 +134,19 @@ class RegionStore: def _state(self) -> dict[str, KnownRegion]: """The name -> record map, loaded from disk on first access.""" if self._regions is None: - self._regions, self._channels = self._load() + self._regions, self._channels, self._answers = self._load() return self._regions - def _load(self) -> tuple[dict[str, KnownRegion], dict[str, str]]: + def _load( + self, + ) -> tuple[dict[str, KnownRegion], dict[str, str], dict[str, CarriedAnswer]]: """Parse the file, or start empty on a missing or corrupt one.""" try: data = json.loads(self._path.read_text(encoding="utf-8")) except (OSError, ValueError): - return {}, {} + return {}, {}, {} if not isinstance(data, dict): - return {}, {} + return {}, {}, {} regions: dict[str, KnownRegion] = {} for entry in data.get("regions") or []: region = _region_from_json(entry) @@ -130,7 +158,12 @@ class RegionStore: channels[str(identity)] = validate(str(name)) except RegionNameError: continue - return regions, channels + answers: dict[str, CarriedAnswer] = {} + for entry in data.get("answers") or []: + answer = _answer_from_json(entry) + if answer is not None: + answers[answer.node] = answer + return regions, channels, answers # -- what is known --------------------------------------------------------------- @@ -163,6 +196,15 @@ class RegionStore: node = node.lower()[:12] return [r.name for r in self.regions() if node in r.repeaters] + def answer_of(self, node: str) -> CarriedAnswer | None: + """The last whole answer a repeater gave (unscoped too, and when), or ``None``. + + ``None`` means it was never asked — or never answered — which the node page states + as such, rather than reading an empty :meth:`carried_by` as "carries nothing". + """ + self._state # noqa: B018 - load on first access + return self._answers.get(node.lower()[:12]) + # -- changing it ----------------------------------------------------------------- def learn(self, name: str, source: str, *, repeater: str | None = None) -> str | None: @@ -200,17 +242,23 @@ class RegionStore: """Record what one repeater says it carries, replacing what it said before. A repeater's list is its whole answer, so a region it no longer names loses that - repeater (and, if nothing else taught it, the region itself). + repeater (and, if nothing else taught it, the region itself). Whether it listed the + wildcard — relays unscoped floods — and when it answered are kept beside the + regions (:meth:`answer_of`). Args: repeater: The repeater's node id (12-hex prefix or full key). - names: The regions it listed (the wildcard is skipped). + names: The regions it listed (the wildcard is recorded as the unscoped flag). Returns: The bare region names learned, in the order given. """ node = repeater.lower()[:12] - wanted = [n for n in (normalize(x) for x in names) if n and n != WILDCARD] + given = [normalize(x) for x in names] + self._state # noqa: B018 - load on first access + self._answers[node] = CarriedAnswer(node=node, unscoped=WILDCARD in given) + self._changed() + wanted = [n for n in given if n and n != WILDCARD] learned: list[str] = [] for name in wanted: bare = self.learn(name, "repeater", repeater=node) @@ -321,10 +369,35 @@ class RegionStore: for r in self._state.values() ], "channels": dict(sorted(self._channels.items())), + "answers": [ + { + "node": a.node, + "unscoped": a.unscoped, + "answered_at": a.answered_at.astimezone(timezone.utc).isoformat(), + } + for a in self._answers.values() + ], } write_atomically(self._path, json.dumps(data, indent=2, ensure_ascii=False)) +def _answer_from_json(entry: object) -> CarriedAnswer | None: + """Parse one stored repeater answer, or ``None`` if it is malformed.""" + if not isinstance(entry, dict) or not entry.get("node"): + return None + try: + answered_at = datetime.fromisoformat(str(entry["answered_at"])) + except (KeyError, ValueError): + return None + if answered_at.tzinfo is None: + answered_at = answered_at.replace(tzinfo=timezone.utc) + return CarriedAnswer( + node=str(entry["node"]).lower()[:12], + unscoped=bool(entry.get("unscoped")), + answered_at=answered_at, + ) + + def _region_from_json(entry: object) -> KnownRegion | None: """Parse one stored region, or ``None`` if it is malformed.""" if not isinstance(entry, dict): diff --git a/meshterm/core/remote_config.py b/meshterm/core/remote_config.py index 117c306..529fe4c 100644 --- a/meshterm/core/remote_config.py +++ b/meshterm/core/remote_config.py @@ -52,12 +52,13 @@ from dataclasses import dataclass #: Reply text (lowercased) that reads as the firmware refusing/unknowing a command. ``??:`` #: is how ``handleGetCmd`` answers a key it doesn't know; ``unknown config:`` is its ``set`` -#: twin. +#: twin. ``err - `` is the ``region`` verbs' own refusal (``Err - not empty``). _ERRORISH = ( "??:", "unknown", "error", "err:", + "err - ", "invalid", "denied", "bad ", @@ -627,12 +628,17 @@ KNOWN_COMMANDS: tuple[str, ...] = ( "password ", "poweroff", "reboot", + # ``region load`` is left out on purpose: it switches the CLI into a line-by-line + # reading mode ended by a blank line, which a remote command line cannot send. "region", "region allowf ", + "region def ", "region default", "region denyf ", "region get ", "region home", + "region list allowed", + "region list denied", "region put ", "region remove ", "region save", diff --git a/meshterm/tools/regions.py b/meshterm/tools/regions.py new file mode 100644 index 0000000..0953eea --- /dev/null +++ b/meshterm/tools/regions.py @@ -0,0 +1,132 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The ``regions`` command: ask a repeater which regions it relays floods for. + +``meshterm regions `` sends the anonymous regions request (firmware 1.12+, no +login) and prints the answer — the regions it relays scoped floods for, and whether it also +relays unscoped ones. One request, one transmission, per invocation: the repeater +rate-limits the question, and nothing here retries it. + +It is a command-line face only. In the menu the same question lives on a repeater's node +page (*Ask which regions it carries*), beside the answer it last gave, so there is no menu +row for it here. + +The answer is learned into the region store either way, exactly as the node page learns it, +so a scoped flood heard afterwards can be traced back to a region this repeater named. + +Exit status, per the CLI's rules: ``0`` when it answered with anything (unscoped floods +alone are an answer), ``5`` when it answered and named nothing at all — it relays no floods +— ``2`` for a contact that does not exist or is known not to be a repeater (nothing was +sent), and ``4`` when it never answered, which is what a repeater out of direct reach does: +the request is only answered when it arrives from a neighbour or over a known route. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any + +import typer + +from ..context import AppContext +from ..core import exitcodes +from ..core.models import NODE_TYPE_LABELS, NODE_TYPE_REPEATER, Contact +from ..core.regions import WILDCARD +from .base import Tool, ToolResult, register + +if TYPE_CHECKING: # pragma: no cover - typing only + from ..ui.report import Facts + + +@register +class RegionsTool(Tool): + """Ask one repeater which regions it carries (command line only).""" + + name = "regions" + title = "Regions" + icon = "🔖" + help = "Ask a repeater which regions it relays floods for" + category = "Other nodes" + order = 20 + menu_visible = False # the menu asks from the repeater's node page + + async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: + """Send the regions request to one repeater and report its answer. + + Args: + ctx: Shared application context. + params: ``node``, the repeater's contact name. + + Returns: + The answer as a report; ``NO_RESULT`` when it named nothing. + + Raises: + typer.BadParameter: For an unknown contact, or one known not to be a repeater — + both decided before anything is sent. + DeviceCommandError: When the repeater never answered. + """ + device = await ctx.device() + contacts = await device.get_contacts() + name = str(params["node"]) + node = next((c for c in contacts if c.name == name), None) + if node is None: + raise typer.BadParameter(f"unknown contact: {name!r}") + if node.node_type is not None and node.node_type != NODE_TYPE_REPEATER: + role = NODE_TYPE_LABELS.get(node.node_type, "not a repeater") + raise typer.BadParameter( + f"{name!r} is a {role}; only a repeater answers the regions request" + ) + names = await device.request_regions(node) + node_id = (node.public_key or node.key_prefix or "").lower()[:12] + if node_id and ctx.region_store is not None: + ctx.region_store.learn_carried(node_id, names) + regions = [n for n in names if n != WILDCARD] + unscoped = WILDCARD in names + return ToolResult( + report=(_answer(node, unscoped, regions),), + summary={"node": name, "unscoped": unscoped, "regions": regions}, + exit_code=exitcodes.OK if names else exitcodes.NO_RESULT, + ) + + def register_cli(self, app: typer.Typer) -> None: + """Register the ``regions`` subcommand. + + Args: + app: The Typer application. + """ + from ..cli import run_tool_command + + @app.command(name=self.name, help=self.help) + def _regions( + node: str = typer.Argument(..., help="The repeater's contact name"), + ) -> None: + run_tool_command(self, {"node": node}) + + +def _answer(node: Contact, unscoped: bool, regions: list[str]) -> Facts: + """The repeater's answer, stated once for both faces. + + Three facts: who answered, whether it relays unscoped floods, and the regions it relays + scoped floods for — the wildcard kept out of that list, since it names no region (see + :func:`~meshterm.ui.fields.regions`). + """ + from ..ui import fields + from ..ui.fields import NodeRef + from ..ui.report import Facts + + return Facts( + key="regions", + fields=( + fields.node("node", lanes=(("name", "node"),)), + fields.flag("unscoped", "unscoped"), + fields.regions("regions", "regions"), + ), + values={ + "node": NodeRef( + name=node.name, + key=(node.public_key or "").lower() or None, + hash=(node.key_prefix or "").lower() or None, + type=NODE_TYPE_LABELS.get(node.node_type), + ), + "unscoped": unscoped, + "regions": regions, + }, + ) diff --git a/meshterm/ui/fields.py b/meshterm/ui/fields.py index 5b18d81..ed21a7b 100644 --- a/meshterm/ui/fields.py +++ b/meshterm/ui/fields.py @@ -276,6 +276,22 @@ def scope(key: str = "scope", header: str = "SCOPE") -> Column: return Column(key=key, lanes=(Lane(header=header, render=_scope_cell),), json=scope_json) +def regions(key: str = "regions", header: str = "REGIONS") -> Column: + """A set of region names — what a repeater relays: joined plain, an array in the document. + + The row holds a sequence of bare names, never the wildcard: *unscoped* is its own + concept (a :func:`flag` beside this column), because ``*`` names no region and a + consumer reading this array for names would otherwise have to know to skip it. An empty + sequence is a real answer — *no regions* — so it reads as the word ``none`` plain and + stays ``[]`` in the document; ``None`` is *not known*, the absent token and ``null``. + """ + return Column( + key=key, + lanes=(Lane(header=header, render=_regions_cell),), + json=lambda names: None if names is None else [str(n) for n in names], + ) + + def when(key: str, header: str, *, absent: str = script.NONE) -> Column: """A time the reader reads as an age: ``5m``, ``3h``, ``never``. @@ -489,6 +505,13 @@ def hidden(key: str) -> Column: return Column(key=key) +def _regions_cell(names: Sequence[str] | None) -> str: + """A region set's plain cell: the names comma-joined, ``none`` when empty, else absent.""" + if names is None: + return script.NONE + return ", ".join(script.name(n) for n in names) if names else "none" + + def _rendered_cell(value: Rendered | None) -> str: """One setting's cell: the text its own spec produced, or the absent token.""" return script.NONE if value is None else value.text diff --git a/meshterm/ui/node_detail_screen.py b/meshterm/ui/node_detail_screen.py index 064666e..d1ea8cf 100644 --- a/meshterm/ui/node_detail_screen.py +++ b/meshterm/ui/node_detail_screen.py @@ -15,7 +15,9 @@ the node itself, in full: * **Info** — the node's vitals as labelled rows (its key with the routing hash lit, when it was first and last heard, how many packets we've overheard, its reception SNR and - last RSSI, and where it sits). The key is a single lane, never wrapped: a full public + last RSSI, where it sits, and — for a repeater — the regions it was last heard to relay + floods for, whether it relays unscoped floods too, and when it said so; see + :func:`regions_value`). The key is a single lane, never wrapped: a full public key outruns the row on any terminal we target, so ``←→`` scroll it a whole four bytes at a time under faint ``…`` edge marks, exactly as a long pathline scrolls on the Routes tab. Then — when the node has advertised a location — a @@ -24,7 +26,10 @@ the node itself, in full: map opens centred here with its find filter seeded to this node, so it lights among the rest), ``Time machine``, ``Share contact`` — a popup contact card (QR code + ``meshcore://`` link, see :func:`~meshterm.ui.config_editor.show_contact_card`), - offered whenever the node's full key is known — and, last, ``Remove contact``: the + offered whenever the node's full key is known — ``Ask which regions it carries`` on a + repeater (one anonymous request, answered only when it arrives direct; the answer is + learned into the region store and the row redraws in place) — and, last, + ``Remove contact``: the single-contact counterpart to the Contacts list's bulk archive (see :mod:`~meshterm.ui.contacts_screen`), dropping *this* node from the device's contact table behind a red confirm. It is the one thing on the page that changes anything, so @@ -68,7 +73,8 @@ The screen is a pure read-and-route view: it renders already-resolved display da resolves an action token (the Trace token carrying the selected route's spec via :meth:`NodeDetailScreen.selected_spec`); :func:`open_node_detail` owns the data-gathering and runs the sub-flows each action opens, then re-shows the page — the same loop the Time -Machine and Contacts list use. Nothing here transmits. +Machine and Contacts list use. The screen itself never transmits; the one action that does +is the regions question, asked once, by the opener, when the reader commits its row. """ from __future__ import annotations @@ -85,9 +91,9 @@ from typing import TYPE_CHECKING from rich.cells import cell_len from rich.text import Text -from ..core.connection import ContactNotOnDeviceError +from ..core.connection import ContactNotOnDeviceError, DeviceCommandError from ..core.geo import haversine_km, usable_fix -from ..core.models import NODE_TYPE_LABELS, Contact, utcnow +from ..core.models import NODE_TYPE_LABELS, NODE_TYPE_REPEATER, Contact, utcnow from ..platforms import Platform, on_platform from . import menus from .mapcanvas import RGB @@ -576,6 +582,18 @@ class NodeDetailScreen(Screen): trace = [self._trace_action] if self._trace_action else [] return menus.icon_lane(action.glyph for action in (*self._info_actions, *trace)) + def replace_info_row(self, label: str, value: Text) -> None: + """Swap one vital's value in place — the regions row, once the repeater has answered. + + The row keeps its place in the block (a label not already there is appended), and + the cursor stays on whatever it was on: the page is the same visit, one fact newer. + """ + for i, (existing, _value) in enumerate(self._info_rows): + if existing == label: + self._info_rows[i] = (label, value) + return + self._info_rows.append((label, value)) + def replace_info_actions(self, actions: list[_Action]) -> None: """Swap the Info tab's action rows in place, keeping the cursor on the row it was on. @@ -1279,6 +1297,20 @@ async def open_node_detail( info_rows.append(("signal", signal)) if lat is not None and lon is not None: info_rows.append(("where", _range_text(lat, lon, self_lat, self_lon))) + # A repeater's regions: what it was last heard to relay, from the region store (its own + # answer to the regions request, or its table read on the admin page). Only a repeater + # answers the request, so only a repeater's page asks it. + region_store = getattr(ctx, "region_store", None) + asks_regions = ( + not you + and contact is not None + and node_type == NODE_TYPE_REPEATER + and bool(node_id) + and region_store is not None + ) + routed = contact is not None and contact.route_hops is not None + if asks_regions: + info_rows.append(("regions", regions_value(region_store, node_id, routed=routed))) # -- the location preview (only when the node advertised a fix). minimap: MiniMap | None = None @@ -1347,6 +1379,9 @@ async def open_node_detail( full_key = key.lower().removeprefix("0x") if len(full_key) == 64 and is_path_hash(full_key): info_actions.append(_Action("share", "📱", "", "Share contact — QR / link")) + if asks_regions: + # Acts at once — one anonymous request, one transmission — so no trailing "…". + info_actions.append(_Action("regions", "🔖", "", "Ask which regions it carries")) # -- contact management, the page's last group and the only actions that end the visit. # Withheld entirely when the caller opened the page to look rather than to act (see # ``manage``), and never offered for our own node or for a contact carrying no key at @@ -1450,6 +1485,13 @@ async def open_node_detail( ) elif action == "share": await show_contact_card(ctx, label, full_key, adv_type) + elif action == "regions": + assert contact is not None and region_store is not None # only offered so + failed = await _ask_regions(ctx, contact, node_id, label, routed=routed) + screen.replace_info_row( + "regions", + regions_value(region_store, node_id, routed=routed, failed=failed), + ) elif action == "timemachine": if you: await open_timemachine_self(ctx) @@ -1727,6 +1769,88 @@ async def _remove_contact(ctx: AppContext, contact: Contact, self_key: str, labe return True +#: Why a repeater may not answer the regions request, in the words the page uses for it. +_REGIONS_REACH = "it answers only a neighbour, or over a known route" + + +def regions_value(store, node_id: str, *, routed: bool, failed: bool = False) -> Text: # noqa: ANN001 - RegionStore + """A repeater's ``regions`` vital: what it relays, whether unscoped too, and how fresh. + + Four states, each in its own words so none reads as another: + + * **answered** — the regions it named, then whether it also relays *unscoped* floods + (the ``*`` its answer leads with, which names no region), then when it said so. A + repeater that relays unscoped floods and no region reads ``unscoped floods only``, and + one that named nothing at all reads that it relays no floods; + * **not asked** — nothing on record; a repeater with no known route also says why the + question may go unanswered (the request is only answered when it arrives direct); + * **no answer** — the question was just asked and nothing came back, on a repeater that + never answered before. One that answered earlier keeps its answer, marked stale by its + age: an unanswered repeat says nothing about what it carries. + + Args: + store: The region store. + node_id: The repeater's 12-hex id. + routed: Whether the device holds a route to it (a neighbour or a learned path). + failed: Whether the ask this visit went unanswered. + + Returns: + The row's value. + """ + answer = store.answer_of(node_id) + if answer is None: + if failed: + text = Text("no answer", style="warn") + text.append(f" — {_REGIONS_REACH}", style="muted") + return text + text = Text("not asked yet", style="muted") + if not routed: + text.append(f" — {_REGIONS_REACH}", style="muted") + return text + names = store.carried_by(node_id) + text = Text() + if names: + text.append(", ".join(names)) + text.append(" · " + ("unscoped too" if answer.unscoped else "scoped only"), style="muted") + elif answer.unscoped: + text.append("unscoped floods only") + else: + text.append("none — it relays no floods", style="warn") + text.append(f" · answered {format_ago(age_seconds(answer.answered_at))}", style="muted") + if failed: + text.append(" · no answer now", style="warn") + return text + + +async def _ask_regions( + ctx: AppContext, contact: Contact, node_id: str, label: str, *, routed: bool +) -> bool: + """Ask a repeater which regions it carries — once — and learn the answer. + + One anonymous request, one transmission, under the busy overlay; the answer replaces + what the store held for this repeater (:meth:`~meshterm.core.region_store.RegionStore. + learn_carried`). An unanswered request is said in a popup with the reason it most + likely went unanswered — the request is dropped unless it arrives direct, and the + repeater rate-limits it — and nothing retries it. + + Returns: + ``True`` when the repeater did not answer. + """ + device = await ctx.device() + try: + async with ctx.ui.busy_overlay(): + names = await device.request_regions(contact) + except DeviceCommandError as exc: + where = "" if routed else " There is no known route to it, so only a neighbour answers." + await ctx.ui.session.message_dialog( + Text(f"{exc}{where}", style="warn"), + title=f"Regions — {label}", + ) + return True + ctx.region_store.learn_carried(node_id, names) + return False + + def _signal_row(hn) -> Text | None: # noqa: ANN001 - Optional[HeardNode] """Median/best reception SNR and last RSSI, or ``None`` when nothing was measured.""" if hn is None: diff --git a/meshterm/ui/region_editor.py b/meshterm/ui/region_editor.py new file mode 100644 index 0000000..ec1ec97 --- /dev/null +++ b/meshterm/ui/region_editor.py @@ -0,0 +1,694 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The region editor: which floods a repeater relays, region by region, over the mesh. + +Reached from a repeater-admin session's *Regions* row (see :mod:`meshterm.ui.repeater_admin`) +once logged in. A repeater keeps a small table of regions in a tree under the wildcard +``*`` and relays a scoped flood only when that flood's region is one it allows; the +wildcard's own flag says whether it relays plain, unscoped floods at all. This page reads +the table over the remote CLI (``region``, parsed by +:func:`~meshterm.core.region_admin.parse_region_dump`), draws it as a tree — region, whether +floods are allowed, and a note for the unscoped wildcard, the home region and the default +scope — and edits it one command at a time. + +**Edits apply at once; saving is the commit.** The settings editor next door stages values +and sends them on Apply, because a staged value costs nothing and a sent one is final. A +region edit is the other way round: the repeater itself is the staging area. Every command +changes the table in its RAM and nothing reaches flash until ``region save``, so a reboot +undoes whatever was not saved. Staging a second time on this side would only add a second +list of pending changes that could disagree with the first — and region edits depend on +each other (a region must exist before it can be allowed, emptied before it is removed), +so a staged batch would have to replay the firmware's rules to know it would work. So each +action sends its one command and the tree redraws from the reply +(:meth:`~meshterm.core.region_admin.RegionTable.after`), the title counts the edits not yet +saved, and the page ends on the same Apply/discard pair the editors use +(:func:`~meshterm.ui.menus.exit_rows`) — worded for what it is here: *Save n changes to the +repeater* over *Back — a reboot undoes them*. Leaving with edits unsaved asks first. +``region default`` saves the whole table itself on firmware that has it +(:func:`~meshterm.core.region_admin.saves_table`), so the count drops to zero there too. + +**A dump the reply cap cut is said to be cut.** Every CLI reply fits in 160 bytes and a +real tree does not, so a dump near the cap is read as possibly cut, its half-line dropped, +and the flat ``region list allowed``/``denied`` read to recover the rest — shown under +*Beyond the cut*, their place in the tree unknown, and still editable by name. A list near +its own cap may have skipped a name, and the page says so rather than claiming a complete +table. + +Whatever the table says the repeater relays is learned into the region store +(:meth:`~meshterm.core.region_store.RegionStore.learn_carried`), so the node page and scope +resolution know it without asking again — replacing its previous answer only when the table +is known whole, and only adding to it when it may not be. + +Every command is one paced transmission the reader asked for: the read is two to four +commands under an abortable progress dialog with the trace cooldown between them, and each +edit is one command under the busy overlay. Nothing polls. +""" + +from __future__ import annotations + +import asyncio +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any + +from rich.cells import cell_len +from rich.text import Text + +from ..core.models import Contact +from ..core.region_admin import ( + DEFAULT_QUERY, + DUMP_COMMAND, + LIST_ALLOWED, + LIST_DENIED, + SAVE_COMMAND, + RegionRow, + RegionTable, + allow_command, + default_command, + deny_command, + home_command, + parse_region_dump, + put_command, + region_refused, + remove_command, + saves_table, + validate_new_name, +) +from ..core.regions import WILDCARD, RegionNameError +from .menus import ( + Lane, + column_header, + icon_lane, + lane_row, + marked_label, + menu_rows, + run_steps, + section_heading, +) +from .tui import Choice, Separator +from .tui.select import DeleteRequest, SelectScreen + +if TYPE_CHECKING: + from ..context import AppContext + from ..core.connection import Device + +#: Seconds to wait for one reply — the admin page's own patience (multi-hop takes seconds). +_REPLY_TIMEOUT_S = 10.0 + +#: The page's key hint. ``Del remove`` is spliced in on the rows it would act on. +REGION_HINT = "↑↓ move · type to filter · Enter open · ^R read · Esc back" +REMOVE_HINT = "Del remove" + +# Action sentinels. Region rows carry a :class:`RegionPick` instead, so no region name — +# which may hold underscores — can ever be mistaken for one of these. +_ADD = "__add__" +_READ = "__read__" +_SAVE = "__save__" +_BACK = "__back__" + + +@dataclass(frozen=True, slots=True) +class RegionPick: + """A region row's value: the region it names. + + Attributes: + name: The region's name, ``*`` for the wildcard row. + """ + + name: str + + +class RegionMenu(SelectScreen): + """The region editor's list, plus ``^R`` to read the table again. + + A full-screen page, not a popup: the reader works in it for a while, it is the tool's + own view of one repeater, and every question it asks (a region's actions, a new name, a + confirm) floats over it. ``^R`` is the admin page's *read again* chord for the same + reason it is there — the mesh is asked the same question again — and here it re-reads + the whole table, which is the only read there is. + + On the F-key lane ``Read`` takes F3, with ``Remove`` as its Shift half, lit only on a + region the firmware would let go (no sub-regions, never the wildcard) — the same pair of + this-row verbs the admin page puts on that slot. + """ + + floating = False + + def __init__(self, title: str, items: list, **kwargs: Any) -> None: + """Build the page; rows end at the edge, as every editor lane does.""" + kwargs.setdefault("hscroll", False) + kwargs.setdefault("footer_hint", REGION_HINT) + kwargs.setdefault("delete_hint", REMOVE_HINT) + super().__init__(title, items, **kwargs) + + def _removable(self) -> bool: + """Whether the highlighted row is a region Del would offer to remove.""" + current = self._current_choice() + return current is not None and current.deletable + + @property + def fkey_lane(self): + """The list's lane with ``Read`` on F3 and ``Remove`` behind it.""" + from .tui.fkeys import FPair + + lane = list(super().fkey_lane) + lane[2] = FPair( + "Read", + "retry", + opp_label="Remove", + opp_action="delete", + opp_enabled=self._removable(), + ) + return lane + + def handle(self, action: str, data: str = "") -> None: + """Read the table again on ``^R``, or behave as any select list does.""" + if action == "retry": + self.resolve(_READ) + return + super().handle(action, data) + + +# --- the page ------------------------------------------------------------------------ + + +def node_id_of(node: Contact) -> str: + """The 12-hex id the region store files a repeater under.""" + return (node.public_key or node.key_prefix or "").lower().removeprefix("0x")[:12] + + +def region_items(node: Contact, table: RegionTable, unsaved: int) -> tuple[str, list]: + """The editor's title and rows for one table and its count of unsaved edits. + + The tree first — the wildcard, then every region indented one step per level — in the + same REGION / FLOOD / NOTE lanes the other editors draw their settings in, headed by a + pinned column header. Then, when the dump was cut, a note saying where, and the regions + recovered from the flat lists under their own heading. Then the page's actions, and + last the save/leave pair while anything is unsaved. + """ + placed = [row for row in table.rows if row.placed] + unplaced = [row for row in table.rows if not row.placed] + lines = [(_row_label(row), _flood_text(row), _row_note(row, table), row) for row in table.rows] + label_w = max([cell_len("REGION")] + [cell_len(label) for label, _, _, _ in lines]) + value_w = max([cell_len("FLOOD")] + [cell_len(value.plain) for _, value, _, _ in lines]) + + items: list = [ + Separator( + lambda w: column_header( + [Lane("REGION", label_w + 2), Lane("FLOOD", value_w + 2), Lane("NOTE")], w + ), + pinned=True, + ), + section_heading("Regions"), + ] + for label, value, note, row in lines: + if row.placed: + items.append(_region_choice(label, value, note, row, table, label_w, value_w)) + if not [row for row in placed if not row.wildcard] and not unplaced: + items.append(Separator(Text("no regions — only the wildcard", style="muted"))) + if table.cut: + where = f" after {table.cut_after}" if table.cut_after else "" + items.append(Separator(Text(f"⚠ the reply ran out at 160 bytes{where}", style="warn"))) + if not table.lists_read: + items.append( + Separator(Text(" regions past it are not shown — ^R reads again", style="warn")) + ) + if unplaced: + items.append(section_heading("Beyond the cut")) + items.append(Separator(Text("from the flat lists — place in the tree unknown", "muted"))) + for label, value, note, row in lines: + if not row.placed: + items.append(_region_choice(label, value, note, row, table, label_w, value_w)) + if table.cut and table.lists_read and table.lists_partial: + items.append(Separator(Text("⚠ the lists were long too — some may be missing", "warn"))) + + actions = [ + ("+", "Add region…", "A new region, floods allowed", _ADD), + ("↻", "Read regions", "Ask the repeater for its table again", _READ), + ] + lane = icon_lane(icon for icon, _, _, _ in actions) + # A blank line between the table and the page's commands: two lists, not one. The tree's + # first row is the wildcard, whose name ``*`` reads as a leading mark to anything that + # measures icon columns — it is data, and it answers to no column the actions keep. + items.append(Separator(" ")) + items.append(section_heading("Actions")) + items.extend( + menu_rows( + (marked_label(icon, label, "", lane=lane), help_text, value) + for icon, label, help_text, value in actions + ) + ) + items.extend(_save_rows(unsaved)) + + title = f"Regions — {node.name}" + (f" · {unsaved} unsaved" if unsaved else "") + return title, items + + +def _region_choice( + label: str, + value: Text, + note: str, + row: RegionRow, + table: RegionTable, + label_w: int, + value_w: int, +) -> Choice: + """One region row; Del removes it only where the firmware would let it go.""" + return Choice( + title=lane_row(label, value, note, label_w, value_w), + value=RegionPick(row.name), + deletable=not row.wildcard and not table.children(row.name), + ) + + +def _row_label(row: RegionRow) -> str: + """The REGION lane: the name, indented two cells per level below the top.""" + return " " * max(0, row.depth - 1) + row.name if row.placed else row.name + + +def _flood_text(row: RegionRow) -> Text: + """The FLOOD lane: the firmware's own two words (``allowf``/``denyf``).""" + return Text("allowed", style="ok") if row.flood else Text("denied", style="muted") + + +def _row_note(row: RegionRow, table: RegionTable) -> str: + """The NOTE lane: what the row *is* beyond its flag — unscoped, home, default.""" + if row.wildcard: + return "unscoped floods" + notes = [] + if row.home: + notes.append("home") + if table.default == row.name: + notes.append("default scope") + return " · ".join(notes) + + +def _save_rows(unsaved: int) -> list: + """The editors' Apply/discard pair, worded for a table that is live but not saved. + + Same shape as :func:`~meshterm.ui.menus.exit_rows` — nothing while clean, then a blank + line and the pair — with its words changed, because here nothing is discarded by + leaving: the edits are already live on the repeater, and it is the next reboot that + undoes them. + """ + if not unsaved: + return [] + noun = "change" if unsaved == 1 else "changes" + return [ + Separator(" "), + Choice( + title=Text.assemble(("✓ ", "ok"), f"Save {unsaved} {noun} to the repeater"), + value=_SAVE, + ), + Choice(title=Text.assemble(("✗ ", "err"), "Back — a reboot undoes them"), value=_BACK), + ] + + +# --- the visit ---------------------------------------------------------------------- + + +async def open_region_editor(ctx: AppContext, device: Device, node: Contact) -> None: + """Read ``node``'s region table and run the editor over it until the reader leaves. + + The node must already be logged in (the admin session's caller did that). A table that + cannot be read at all — no reply, or firmware without the ``region`` command — is said + in a popup and the page never opens: there would be nothing on it to edit. + + Args: + ctx: The shared application context (interactive TUI). + device: The connected companion. + node: The repeater being administered. + """ + from .tui import CANCEL + + session = ctx.ui.session + table = await read_table(ctx, device, node) + if table is None: + return + unsaved = 0 + title, items = region_items(node, table, unsaved) + menu = RegionMenu(title, items) + async with session.stay(menu) as visit: + while True: + choice = await visit.result() + if choice is CANCEL or choice is None or choice == _BACK: + if unsaved and not await _confirm_leave(ctx, node, unsaved): + continue + return + if choice == _READ: + fresh = await read_table(ctx, device, node) + if fresh is not None: + table = fresh + elif choice == _SAVE: + table, unsaved = await _edit(ctx, device, node, table, unsaved, SAVE_COMMAND) + elif choice == _ADD: + table, unsaved = await _add_region(ctx, device, node, table, unsaved, None) + elif isinstance(choice, DeleteRequest) and isinstance(choice.value, RegionPick): + table, unsaved = await _remove(ctx, device, node, table, unsaved, choice.value.name) + elif isinstance(choice, RegionPick): + table, unsaved = await _region_actions( + ctx, device, node, table, unsaved, choice.name + ) + title, items = region_items(node, table, unsaved) + menu.replace_items(items, title=title) + + +async def read_table(ctx: AppContext, device: Device, node: Contact) -> RegionTable | None: + """Read the whole table, paced, under an abortable progress dialog. + + ``region`` for the tree, then ``region default`` for the default scope (firmware 1.15+; + older firmware's refusal just leaves it unknown), then — only when the tree came back + cut — the two flat lists that recover what the cut hid. What was read is learned into + the region store. + + Returns: + The table, or ``None`` when the dump never came (no reply, the firmware has no + ``region`` command, or the reader aborted) — after saying which. + """ + from .repeater_admin import _run_under_dialog + + session = ctx.ui.session + replies: dict[str, str | None] = {} + + async def work(dialog: Any) -> None: + plan = [DUMP_COMMAND, DEFAULT_QUERY] + i = 0 + while i < len(plan): + command = plan[i] + if i: + await asyncio.sleep(ctx.preferences.trace_cooldown_s) + dialog.status = command + session.invalidate() + reply = await device.send_remote_command(node, command, timeout=_REPLY_TIMEOUT_S) + replies[command] = reply + if command == DUMP_COMMAND: + if reply is None or region_refused(reply): + return # nothing else is worth asking without the tree + if parse_region_dump(reply).cut: + plan += [LIST_ALLOWED, LIST_DENIED] + i += 1 + + aborted = await _run_under_dialog(ctx, f"Reading regions — {node.name}", work) + dump = replies.get(DUMP_COMMAND) + if aborted: + return None + if dump is None: + await session.message_dialog( + Text( + f"No reply from {node.name} to region — it may be out of reach or busy; " + "try again when it answers.", + style="warn", + ), + title="Regions", + ) + return None + if region_refused(dump): + await session.message_dialog( + Text( + f"{node.name} does not know the region command ({dump.strip()}). " + "Regions need repeater firmware 1.12 or newer.", + style="err", + ), + title="Regions", + ) + return None + table = parse_region_dump(dump).with_default(replies.get(DEFAULT_QUERY)) + if table.cut: + table = table.with_lists(replies.get(LIST_ALLOWED), replies.get(LIST_DENIED)) + learn_table(ctx, node, table) + return table + + +def learn_table(ctx: AppContext, node: Contact, table: RegionTable) -> None: + """Tell the region store what this repeater relays, as far as the table can say. + + A table known whole replaces the repeater's previous answer, exactly as the anonymous + regions request would; one that may be missing names only adds what it shows, so a cut + never makes the store forget a region the repeater still carries. + """ + store = getattr(ctx, "region_store", None) + node_id = node_id_of(node) + if store is None or not node_id: + return + if table.complete and table.wildcard is not None: + store.learn_carried(node_id, table.carried()) + return + for name in table.carried(): + if name != WILDCARD: + store.learn(name, "repeater", repeater=node_id) + + +async def _edit( + ctx: AppContext, + device: Device, + node: Contact, + table: RegionTable, + unsaved: int, + command: str, +) -> tuple[RegionTable, int]: + """Send one region command and fold an accepted reply into the table. + + A refused command shows the repeater's own words; a silent one says the change may + still have landed and points at ``^R``, since only a read can tell. An accepted edit + counts as unsaved unless it saved the table itself (``region save``, and ``region + default`` on firmware that auto-saves it). + + Returns: + The table and the unsaved count, after the command. + """ + async with ctx.ui.busy_overlay(): + reply = await device.send_remote_command(node, command, timeout=_REPLY_TIMEOUT_S) + if reply is None: + await ctx.ui.session.message_dialog( + Text( + f"No reply to {command} — it may still have landed. ^R reads the table again.", + style="warn", + ), + title=f"Regions — {node.name}", + ) + return table, unsaved + if region_refused(reply): + await ctx.ui.session.message_dialog( + Text(f"{node.name} refused {command}: {reply.strip()}", style="err"), + title=f"Regions — {node.name}", + ) + return table, unsaved + table = table.after(command, reply) + unsaved = 0 if saves_table(command, reply) else unsaved + 1 + learn_table(ctx, node, table) + return table, unsaved + + +async def _region_actions( + ctx: AppContext, + device: Device, + node: Contact, + table: RegionTable, + unsaved: int, + name: str, +) -> tuple[RegionTable, int]: + """What can be done to one region — a question asked in a popup, then done. + + Every row is one command except *Add region under it…*, which asks a name, and + *Remove…*, which asks first. Denying the wildcard asks too: it stops every plain flood + at this repeater, which is most of the mesh's traffic. + """ + row = table.get(name) + if row is None: + return table, unsaved + rows: list[tuple[str | Text, str, str]] = [] + subject = "unscoped floods" if row.wildcard else f"floods scoped to {name}" + if row.flood: + rows.append(("Deny flood", f"Stop relaying {subject}", "deny")) + else: + rows.append(("Allow flood", f"Relay {subject}", "allow")) + if row.wildcard: + if table.home not in (None, WILDCARD): + rows.append(("Clear home", f"No home region (now {table.home})", "home")) + elif not row.home: + rows.append(("Make home", "Mark it as this repeater's own region", "home")) + if not row.wildcard and table.default_known: + if table.default == name: + rows.append(("Clear default", "Its own floods go unscoped; saves all", "undefault")) + else: + rows.append(("Make default", "Scope its own floods to it; saves all", "default")) + under = "top level" if row.wildcard else f"inside {name}" + rows.append(("Add region…" if row.wildcard else "Add region under it…", f"New, {under}", "add")) + if not row.wildcard: + children = table.children(name) + if children: + rows.append(("Remove…", "Remove its sub-regions first", "blocked")) + else: + rows.append((Text("Remove…", style="err"), "Delete it from the table", "remove")) + + picked = await ctx.ui.select( + f"Region — {name}", + menu_rows(rows), + prompt=_state_line(row, table), + filterable=False, + floating=True, + ) + if picked is None: + return table, unsaved + if picked == "deny": + if row.wildcard and not await _confirm_deny_unscoped(ctx, node): + return table, unsaved + return await _edit(ctx, device, node, table, unsaved, deny_command(name)) + if picked == "allow": + return await _edit(ctx, device, node, table, unsaved, allow_command(name)) + if picked == "home": + return await _edit(ctx, device, node, table, unsaved, home_command(name)) + if picked == "default": + return await _edit(ctx, device, node, table, unsaved, default_command(name)) + if picked == "undefault": + return await _edit(ctx, device, node, table, unsaved, default_command(None)) + if picked == "add": + return await _add_region(ctx, device, node, table, unsaved, name) + if picked == "remove": + return await _remove(ctx, device, node, table, unsaved, name) + if picked == "blocked": + names = ", ".join(child.name for child in table.children(name)) + await ctx.ui.session.message_dialog( + Text(f"{name} still holds {names}. Remove those first.", style="warn"), + title=f"Region — {name}", + ) + return table, unsaved + + +def _state_line(row: RegionRow, table: RegionTable) -> str: + """The popup's one-line summary of a region: its flag, its place, its notes.""" + atoms = ["floods allowed" if row.flood else "floods denied"] + if row.wildcard: + atoms.append("the unscoped case") + elif not row.placed: + atoms.append("place unknown") + elif row.parent and row.parent != WILDCARD: + atoms.append(f"inside {row.parent}") + note = _row_note(row, table) + if note and not row.wildcard: + atoms.append(note) + return " · ".join(atoms) + + +async def _add_region( + ctx: AppContext, + device: Device, + node: Contact, + table: RegionTable, + unsaved: int, + parent: str | None, +) -> tuple[RegionTable, int]: + """Add a region: where (unless the row it was asked from already said), then its name. + + Two steps through :func:`~meshterm.ui.menus.run_steps`, so Esc on the name goes back to + the parent picker with its answer highlighted. The name is checked against the + firmware's own rules and against the table: ``region put`` of a name already there + *moves* that region, which is never what *Add* means. + """ + taken = [row.name for row in table.rows] + + async def pick_parent(values: list) -> str | None: + candidates = [row for row in table.rows if row.placed] + items = [ + Choice( + title=(" " * max(0, row.depth - 1) + row.name) + + (" (top level)" if row.wildcard else ""), + value=row.name, + ) + for row in candidates + ] + return await ctx.ui.select( + "Add region — where", + items, + prompt="The region to put it inside (* for the top level):", + default=values[0] or WILDCARD, + floating=True, + ) + + # The name is the last step either way; where it sits in the answers is the only + # difference between being asked from a row (one step) and from Actions (two). + slot = 0 if parent is not None else 1 + + async def ask_name(values: list) -> str | None: + where = parent if parent is not None else values[0] + inside = "at the top level" if where == WILDCARD else f"inside {where}" + + def check(text: str) -> bool | str: + try: + validate_new_name(text, taken) + except RegionNameError as exc: + return str(exc) + return True + + typed = await ctx.ui.text( + "Add region", + prompt=f"Name of the new region, {inside}:", + default=values[slot] or "", + validate=check, + help_text="letters, digits and -, up to 30 bytes", + floating=True, + ) + return typed.strip() if typed else None + + answers = await run_steps([ask_name] if parent is not None else [pick_parent, ask_name]) + if answers is None: + return table, unsaved + where = parent if parent is not None else answers[0] + name = answers[slot] + try: + bare = validate_new_name(name, taken) + except RegionNameError: # pragma: no cover - the prompt's validator already refused it + return table, unsaved + return await _edit(ctx, device, node, table, unsaved, put_command(bare, where)) + + +async def _remove( + ctx: AppContext, + device: Device, + node: Contact, + table: RegionTable, + unsaved: int, + name: str, +) -> tuple[RegionTable, int]: + """Remove one region behind the red single-record confirm.""" + from .tui import CANCEL + + row = table.get(name) + if row is None or row.wildcard or table.children(name): + return table, unsaved + choice = await ctx.ui.dialog( + f"Remove {name} from {node.name}? Floods scoped to it stop being relayed here " + "at once; region save makes it permanent.", + [("Cancel", CANCEL), ("Remove", "remove")], + title="Remove region", + default=1, + destructive=True, + ) + if choice != "remove": + return table, unsaved + return await _edit(ctx, device, node, table, unsaved, remove_command(name)) + + +async def _confirm_deny_unscoped(ctx: AppContext, node: Contact) -> bool: + """Ask before a repeater stops relaying plain floods — most of the mesh's traffic.""" + choice = await ctx.ui.dialog( + f"Stop {node.name} relaying unscoped floods? Every plain flood — adverts and most " + "messages today — would stop here, and only scoped floods would pass.", + [("Cancel", None), ("Deny", "deny")], + title="Deny unscoped floods", + default=1, + danger=True, + ) + return choice == "deny" + + +async def _confirm_leave(ctx: AppContext, node: Contact, unsaved: int) -> bool: + """Ask before leaving edits live but unsaved; ``True`` means leave anyway.""" + noun = "change is" if unsaved == 1 else "changes are" + choice = await ctx.ui.dialog( + f"{unsaved} {noun} live on {node.name} but not saved — its next reboot undoes " + f"{'it' if unsaved == 1 else 'them'}. Leave without saving?", + [("Keep editing", "keep"), ("Leave", "leave")], + title="Unsaved regions", + default=1, + danger=True, + ) + return choice == "leave" diff --git a/meshterm/ui/repeater_admin.py b/meshterm/ui/repeater_admin.py index 0611b60..180faf4 100644 --- a/meshterm/ui/repeater_admin.py +++ b/meshterm/ui/repeater_admin.py @@ -18,9 +18,10 @@ firmware doesn't have reads as ``n/a`` — kept apart from ``?``, never read. Ap staged values the same way and folds each confirmed value straight back into the cache. Beyond the settings, the action rows cover the box itself — advert, clock sync, change -admin password, reboot, each behind its own floating confirmation — and the **Command -line** opens the readline-style remote CLI (:mod:`meshterm.ui.remote_cli`) for anything -the catalog doesn't spell. +admin password, reboot, each behind its own floating confirmation — **Regions** opens the +region editor (:mod:`meshterm.ui.region_editor`), which floods it relays region by region, +and the **Command line** opens the readline-style remote CLI (:mod:`meshterm.ui.remote_cli`) +for anything the catalog doesn't spell. That command line is also where the page *grows*. Third-party builds carry settings the catalog has never heard of, and MeshTerm can't know which build a node is running without @@ -99,6 +100,7 @@ _ADVERT = "__advert__" _CLOCK = "__clock__" _PASSWORD = "__password__" _REBOOT = "__reboot__" +_REGIONS = "__regions__" _APPLY = "__apply__" _CANCEL = "__cancel__" @@ -409,6 +411,10 @@ async def _admin_session(ctx: AppContext, device: Device, node: Contact) -> dict await _stage_location(ctx, cache, pending) elif choice == _CLI: await _command_line(ctx, device, node) + elif choice == _REGIONS: + from .region_editor import open_region_editor + + await open_region_editor(ctx, device, node) elif choice == _ADVERT: await _simple_action( ctx, @@ -523,6 +529,7 @@ def _menu_items(node: Contact, cache: dict, pending: dict[str, str]) -> tuple[st actions = [ ("↻", "Read settings", "Fetch every value from the node, one paced read", _READ), ("⌨", "Command line…", "Talk to the node's CLI directly", _CLI), + ("🔖", "Regions…", "Which scoped floods it relays", _REGIONS), ("📡", "Send advert…", "Have the node announce itself now", _ADVERT), ("🕒", "Sync clock…", "Set the node's clock over the mesh", _CLOCK), ("🔐", "Admin password…", "Change the node's admin password", _PASSWORD), diff --git a/tests/test_cli_contract.py b/tests/test_cli_contract.py index 3d054f9..67eccef 100644 --- a/tests/test_cli_contract.py +++ b/tests/test_cli_contract.py @@ -620,12 +620,16 @@ def test_a_port_that_will_not_open_is_no_device_not_a_device_failure(run) -> Non "args", [ ("repeater-admin", "Nobody", "get", "name"), + ("regions", "Nobody"), + ("regions", "Alice"), ("courier", "queue", "Nobody", "hi"), ("courier", "queue", "Alice", "hi", "--at", "25:99"), ("tx-optimize", "--path", "Yagi-Repeater", "--samples", "1"), ], ids=[ "unknown-admin-node", + "unknown-regions-node", + "regions-of-a-companion", "unknown-courier-contact", "bad-at-time", "tx-optimize-one-hop-path", @@ -655,6 +659,49 @@ def test_a_node_that_answers_no_is_still_a_device_failure(run) -> None: # noqa: assert result.exit_code == exitcodes.DEVICE, result.output +def test_a_repeaters_regions_on_both_faces(run) -> None: # noqa: ANN001 + """Who answered, whether it relays unscoped floods, and the regions — never the ``*``.""" + plain = run("regions", "Yagi-Repeater") + assert plain.exit_code == exitcodes.OK, plain.output + assert result_lines(plain) == [ + "node Yagi-Repeater", + "unscoped yes", + "regions lakeside, lakeside-north, harbour", + ] + document = json.loads(run("--json", "regions", "Yagi-Repeater").stdout) + assert document["node"]["name"] == "Yagi-Repeater" + assert document["unscoped"] is True + assert document["regions"] == ["lakeside", "lakeside-north", "harbour"] + + +def test_a_repeater_that_names_nothing_is_nothing_to_report(run, monkeypatch) -> None: # noqa: ANN001 + """It answered, so this is not a failure — but it relays no floods at all: exit 5.""" + from meshterm.core.connection import MockDevice + + async def nothing(self, node): # noqa: ANN001, ANN202 + return [] + + monkeypatch.setattr(MockDevice, "request_regions", nothing) + result = run("regions", "Yagi-Repeater") + assert result.exit_code == exitcodes.NO_RESULT + document = json.loads(run("--json", "regions", "Yagi-Repeater").stdout) + assert document["unscoped"] is False and document["regions"] == [] + + +def test_a_repeater_that_never_answers_is_a_device_failure(run, monkeypatch) -> None: # noqa: ANN001 + """The request went out and nothing came back — a retry is a real option: exit 4.""" + from meshterm.core.connection import DeviceCommandError, MockDevice + + async def silent(self, node): # noqa: ANN001, ANN202 + raise DeviceCommandError(f"{node.name!r} did not answer the regions request.") + + monkeypatch.setattr(MockDevice, "request_regions", silent) + result = run("regions", "Yagi-Repeater") + assert result.exit_code == exitcodes.DEVICE + assert result.stdout == "" + assert "did not answer" in result.stderr + + def test_an_empty_result_writes_nothing_to_stdout_at_all(run) -> None: # noqa: ANN001 """Not a "no channels configured" line: the status carries it, so the pipe stays clean.""" result = run("channels", "list") diff --git a/tests/test_gallery.py b/tests/test_gallery.py index 5600d64..235b924 100644 --- a/tests/test_gallery.py +++ b/tests/test_gallery.py @@ -406,6 +406,59 @@ def _node_detail_map(cols: int, rows: int) -> Screen: return _node_detail(cols, rows, with_minimap=True) +def _node_detail_regions(cols: int, rows: int) -> Screen: + """A repeater's node page with its regions answered — the longest the row gets.""" + from meshterm.core.region_store import RegionStore + from meshterm.ui.node_detail_screen import regions_value + + store = RegionStore(Path(tempfile.mkdtemp(prefix="meshterm-gallery-regions-")) / "r.json") + store.learn_carried(_HUB_KEY[:12], ["*", "lakeside", "lakeside-north", "harbour"]) + screen = _node_detail(cols, rows) + assert isinstance(screen, NodeDetailScreen) + screen.replace_info_row("regions", regions_value(store, _HUB_KEY[:12], routed=True)) + screen.replace_info_actions( + [ + _Action("timemachine", "⏳", "", "Time machine — 42 receptions"), + _Action("regions", "🔖", "", "Ask which regions it carries"), + _Action("remove", "🗑", "err", "Remove contact…"), + ] + ) + return screen + + +def _region_editor(cols: int, rows: int) -> Screen: + """The region editor at its fullest: a cut dump, the rest recovered, edits unsaved.""" + from meshterm.core.region_admin import parse_region_dump + from meshterm.core.region_sim import SimulatedRegionMap + from meshterm.ui.region_editor import RegionMenu, region_items + + hub = Contact(name="Hilltop-Repeater", public_key=_HUB_KEY, key_prefix="3d63c6429436") + # A table too big for one reply, answered the way a repeater answers it. + sim = SimulatedRegionMap( + [ + ("lakeside", "*", True), + ("lakeside-north", "lakeside", True), + ("lakeside-south", "lakeside", False), + ("harbour", "*", True), + ("harbour-east", "harbour", True), + ("harbour-west", "harbour", True), + ("old-town", "*", False), + ("old-town-market", "old-town", True), + ("riverside", "*", True), + ("riverside-upper", "riverside", True), + ("a-region-named-thirty-bytes-xx", "riverside", True), + ] + ) + sim.command("region default harbour") + table = ( + parse_region_dump(sim.command("region")) + .with_default(sim.command("region default")) + .with_lists(sim.command("region list allowed"), sim.command("region list denied")) + ) + title, items = region_items(hub, table, 2) + return RegionMenu(title, items) + + def _chat(cols: int, rows: int) -> Screen: conv = Conversation( label="Alice", @@ -1286,6 +1339,7 @@ _ENTRIES: list[_Entry] = [ _Entry("archived", _archived), _Entry("node_detail", _node_detail), _Entry("node_detail_map", _node_detail_map), + _Entry("node_detail_regions", _node_detail_regions), _Entry("map", _map), _Entry("map_panned", _map_panned), _Entry("map_find", _map_find), @@ -1320,6 +1374,7 @@ _ENTRIES: list[_Entry] = [ _Entry("config_editor", _config_editor), _Entry("config_editor_revealed", _config_editor_revealed), _Entry("repeater_admin", _repeater_admin), + _Entry("region_editor", _region_editor), _Entry("preferences", _preferences), _Entry("preferences-weekly-advert", _preferences_weekly_advert), _Entry("cooldown_countdown", _cooldown_countdown), diff --git a/tests/test_region_admin.py b/tests/test_region_admin.py new file mode 100644 index 0000000..acc84b4 --- /dev/null +++ b/tests/test_region_admin.py @@ -0,0 +1,829 @@ +# SPDX-License-Identifier: Apache-2.0 +"""A repeater's region table: the dump parser, the commands, the editor, the node page. + +The parser is pinned against dumps spelled the way ``RegionMap::printChildRegions`` spells +them — including the ones the 160-byte reply buffer cuts mid-name — and against the +simulator (:mod:`meshterm.core.region_sim`), which transcribes the firmware's CLI. Every +editor action is checked for the one command it sends, and the table it leaves behind is +checked against what the repeater itself would dump next. +""" + +from __future__ import annotations + +import asyncio +import random +from contextlib import asynccontextmanager +from dataclasses import replace +from pathlib import Path +from types import SimpleNamespace + +import pytest +from rich.text import Text + +from meshterm.core.connection import DeviceCommandError, MockDevice +from meshterm.core.models import Contact +from meshterm.core.region_admin import ( + REPLY_CAP_BYTES, + RegionTable, + allow_command, + default_command, + deny_command, + dump_may_be_cut, + home_command, + list_may_be_incomplete, + parse_default_reply, + parse_name_list, + parse_region_dump, + put_command, + region_refused, + remove_command, + saves_table, + validate_new_name, +) +from meshterm.core.region_sim import SimulatedRegionMap +from meshterm.core.region_store import RegionStore +from meshterm.core.regions import RegionNameError +from meshterm.core.remote_config import known_commands +from meshterm.ui import region_editor +from meshterm.ui.region_editor import RegionMenu, RegionPick, region_items + +NODE = Contact(name="Yagi-Repeater", public_key="a1" * 32, key_prefix="a1b2c3d4", node_type=2) +BIG = Contact(name="Local-Repeater", public_key="b2" * 32, key_prefix="b2c3d4e5", node_type=2) + +#: A small table, dumped exactly as the firmware prints it. +SMALL_DUMP = "*^ F\n lakeside F\n lakeside-north F\n lakeside-south\n harbour F\n" + +_TREE = [ + ("lakeside", "*", True), + ("lakeside-north", "lakeside", True), + ("lakeside-south", "lakeside", False), + ("harbour", "*", True), +] + + +def _rows(table: RegionTable) -> list[tuple]: + return [(r.name, r.parent, r.depth, r.flood, r.home, r.placed) for r in table.rows] + + +# --- the dump -------------------------------------------------------------------------- + + +def test_a_dump_reads_as_a_tree_with_its_flags() -> None: + """Indentation is the parent, ``F`` is flood allowed, ``^`` is home.""" + table = parse_region_dump(SMALL_DUMP) + assert _rows(table) == [ + ("*", None, 0, True, True, True), + ("lakeside", "*", 1, True, False, True), + ("lakeside-north", "lakeside", 2, True, False, True), + ("lakeside-south", "lakeside", 2, False, False, True), + ("harbour", "*", 1, True, False, True), + ] + assert not table.cut and table.complete + assert table.home == "*" + assert [r.name for r in table.children("lakeside")] == ["lakeside-north", "lakeside-south"] + assert table.carried() == ["*", "lakeside", "lakeside-north", "harbour"] + + +def test_a_home_region_and_a_denied_wildcard() -> None: + """A region marked ``^`` is home; a wildcard without ``F`` relays no unscoped floods.""" + table = parse_region_dump("*\n yul^ F\n yul-east\n") + assert table.home == "yul" + assert table.wildcard is not None and not table.wildcard.flood + assert table.carried() == ["yul"] + + +def test_the_dump_survives_a_transport_that_stripped_its_last_newline() -> None: + """A short reply without its trailing newline is still whole — it never reached the cap.""" + assert _rows(parse_region_dump(SMALL_DUMP.rstrip("\n"))) == _rows(parse_region_dump(SMALL_DUMP)) + assert not parse_region_dump(SMALL_DUMP.rstrip("\n")).cut + + +def test_a_dump_at_the_cap_is_cut_and_its_half_line_dropped() -> None: + """The buffer stops mid-name; that name must not become a region with half a name. + + The last line here reads ``riverside-upper`` with no ``F`` — as a region it would be a + denied one called by a prefix of its name. It is dropped and the table says where the + tree stopped. + """ + sim = SimulatedRegionMap( + [ + *_TREE, + ("harbour-east", "harbour", True), + ("harbour-west", "harbour", True), + ("old-town", "*", False), + ("old-town-market", "old-town", True), + ("riverside", "*", True), + ("riverside-upper", "riverside", True), + ("hilltop", "*", True), + ] + ) + dump = sim.command("region") + assert len(dump.encode()) == REPLY_CAP_BYTES - 1 and not dump.endswith("\n") + table = parse_region_dump(dump) + assert table.cut and not table.complete + assert table.cut_after == "riverside" + assert table.get("riverside-upper") is None and table.get("hilltop") is None + + +def test_a_cut_line_that_ended_on_its_newline_is_kept() -> None: + """Near the cap but ending on a newline: the last line is whole, a next one may be lost.""" + dump = SMALL_DUMP + while len(dump.encode()) < REPLY_CAP_BYTES - 4: + dump += f" r{len(dump):03d} F\n" + assert dump_may_be_cut(dump) and dump.endswith("\n") + table = parse_region_dump(dump) + assert table.cut + assert table.rows[-1].name == dump.rstrip("\n").rsplit("\n", 1)[-1].split()[0] + + +def test_a_cut_inside_a_multibyte_name_still_counts_as_cut() -> None: + """A UTF-8 name split by the buffer decodes a few bytes short — still read as cut.""" + dumps = ( + SimulatedRegionMap([(f"{i:02d}" + "é" * k, "*", True) for i in range(20)]).command("region") + for k in range(1, 12) + ) + # Slide the name length until the cap lands inside an "é" and the decode loses a byte. + dump = next(d for d in dumps if len(d.encode()) < REPLY_CAP_BYTES - 1) + table = parse_region_dump(dump) + assert table.cut and not dump.endswith("\n") + assert len({len(r.name) for r in table.regions()}) == 1 # no half-name among them + + +def test_a_line_that_breaks_the_grammar_ends_the_tree_there() -> None: + """A dump that stops making sense stops being the dump: no guessing, marked cut.""" + table = parse_region_dump("*^ F\n lakeside F\n skipped-a-level F\n harbour F\n") + assert [r.name for r in table.rows] == ["*", "lakeside"] + assert table.cut and table.cut_after == "lakeside" + + +def test_an_empty_reply_is_an_empty_table() -> None: + """No reply, no rows — and nothing to call cut.""" + assert parse_region_dump("").rows == () + assert parse_region_dump(None).rows == () + + +# --- the flat lists and the default ---------------------------------------------------- + + +def test_the_flat_lists_recover_what_the_cut_hid() -> None: + """Names past the cut join unplaced, flooded as their list says; the tree keeps its own.""" + table = replace(parse_region_dump("*^ F\n lakeside F\n"), cut=True, cut_after="lakeside") + assert not table.complete + table = table.with_lists("*,lakeside,lakeside-north,hilltop", "old-town") + assert _rows(table)[2:] == [ + ("lakeside-north", None, 1, True, False, False), + ("hilltop", None, 1, True, False, False), + ("old-town", None, 1, False, False, False), + ] + assert table.lists_read and not table.lists_partial and table.complete + assert table.carried() == ["*", "lakeside", "lakeside-north", "hilltop"] + + +def test_a_list_near_its_cap_may_have_skipped_a_name() -> None: + """The firmware skips a name that won't fit and carries on — so a long list is flagged.""" + names = [f"region-number-{i:02d}" for i in range(12)] + sim = SimulatedRegionMap([(n, "*", True) for n in names]) + listed = sim.command("region list allowed") + assert parse_name_list(listed) != ["*", *names] # some were skipped + assert list_may_be_incomplete(listed) + assert not list_may_be_incomplete("*,lakeside,harbour") + assert parse_name_list("-none-") == [] + + +def test_the_default_scope_reply() -> None: + """``region default`` names the region, ````, or is not understood.""" + assert parse_default_reply(" default scope is harbour") == "harbour" + assert parse_default_reply(" default scope is now harbour") == "harbour" + assert parse_default_reply(" default scope is ") == "" + assert parse_default_reply("Err - ??") is None # pre-1.15 has no such query + assert parse_default_reply(None) is None + table = parse_region_dump(SMALL_DUMP) + assert not table.with_default("Err - ??").default_known + known = table.with_default(" default scope is harbour") + assert known.default_known and known.default == "harbour" + + +def test_refusals_are_the_region_verbs_own_words() -> None: + """``Err - …`` is a refusal; a reply naming a region is not.""" + for reply in ("Err - not empty", "Err - unknown region", "Err - ??", "Unknown command"): + assert region_refused(reply) + for reply in ("OK", "OK - (flood allowed)", " home is now harbour", "lakeside,harbour"): + assert not region_refused(reply) + assert region_refused(None) + + +# --- the commands ---------------------------------------------------------------------- + + +def test_every_edit_is_one_command_spelled_once() -> None: + """The exact text each editor action sends.""" + assert allow_command("lakeside") == "region allowf lakeside" + assert deny_command("*") == "region denyf *" + assert home_command("harbour") == "region home harbour" + assert default_command("harbour") == "region default harbour" + assert default_command(None) == "region default " + assert put_command("bay") == "region put bay" + assert put_command("bay", "*") == "region put bay" + assert put_command("bay", "harbour") == "region put bay harbour" + assert remove_command("bay") == "region remove bay" + + +def test_saving_is_region_save_or_a_default_that_saved_itself() -> None: + """Only a save, or a 1.15+ default change, clears the unsaved count.""" + assert saves_table("region save", "OK") + assert not saves_table("region save", "Err - save failed") + assert saves_table("region default harbour", " default scope is now harbour") + assert not saves_table("region allowf harbour", "OK") + + +def test_a_new_name_follows_the_firmware_and_never_moves_a_region() -> None: + """A put of a taken name would move it; punctuation the firmware refuses is refused first.""" + assert validate_new_name(" bay-2 ") == "bay-2" + with pytest.raises(RegionNameError, match="already"): + validate_new_name("harbour", ["*", "harbour"]) # region put would move it + with pytest.raises(RegionNameError, match="letters, digits"): + validate_new_name("old.town") + with pytest.raises(RegionNameError): + validate_new_name("$secret") + with pytest.raises(RegionNameError): + validate_new_name("*") + + +def test_the_command_line_completes_the_list_and_def_verbs_but_not_load() -> None: + """``region load`` reads lines until a blank one — no remote command line can send that.""" + commands = known_commands() + assert {"region list allowed", "region list denied", "region def "} <= set(commands) + assert not any(c.startswith("region load") for c in commands) + + +# --- the edits fold into the table the way the firmware applies them ------------------- + + +def test_each_accepted_edit_leaves_the_table_the_repeater_would_dump() -> None: + """Random edits against the simulator: the folded table equals a fresh dump, every time. + + This is the claim the editor rests on — it redraws from a reply instead of re-reading — + so it is checked against the firmware transcription over many sequences rather than + one example of each verb. + """ + rng = random.Random(7) + pool = ["lakeside", "lakeside-north", "lakeside-south", "harbour", "bay", "cove", "*"] + for _ in range(60): + sim = SimulatedRegionMap(_TREE) + table = parse_region_dump(sim.command("region")).with_default(sim.command("region default")) + for _ in range(8): + name = rng.choice(pool) + known = [r.name for r in table.rows] + verb = rng.choice(["allow", "deny", "home", "default", "put", "remove"]) + if verb == "allow": + command = allow_command(name) + elif verb == "deny": + command = deny_command(name) + elif verb == "home": + command = home_command(name) + elif verb == "default": + if name == "*": + continue + command = default_command(name if rng.random() < 0.8 else None) + elif verb == "put": + if name in known or name == "*": + continue # the editor refuses these (a put would move the region) + command = put_command(name, rng.choice([n for n in known])) + else: + if name == "*" or name not in known: + continue + command = remove_command(name) + reply = sim.command(command) + table = table.after(command, reply) + fresh = parse_region_dump(sim.command("region")).with_default( + sim.command("region default") + ) + assert _rows(table) == _rows(fresh), (command, reply) + assert table.default == fresh.default, command + + +def test_a_refused_edit_changes_nothing() -> None: + """A refusal leaves the very same table.""" + table = parse_region_dump(SMALL_DUMP) + assert table.after("region remove lakeside", "Err - not empty") is table + assert table.after("region allowf nowhere", "Err - unknown region") is table + + +def test_a_put_on_old_firmware_is_denied_until_allowed() -> None: + """Before 1.15 a new region was created denied; the reply says which firmware answered.""" + table = parse_region_dump(SMALL_DUMP) + assert not table.after("region put bay", "OK").get("bay").flood + assert table.after("region put bay", "OK - (flood allowed)").get("bay").flood + + +# --- the simulator keeps the firmware's awkward edges --------------------------------- + + +def test_the_simulator_behaves_like_the_firmware() -> None: + """Prefix matching, a put that moves, a remove that refuses, and a reboot that forgets.""" + sim = SimulatedRegionMap(_TREE) + assert sim.command("region remove lakeside") == "Err - not empty" + assert sim.command("region allowf lakeside-s") == "OK" # a prefix is enough on the radio + assert sim.command("region put harbour lakeside") == "OK - (flood allowed)" # moves it + assert " harbour" not in sim.command("region").split("\n") # no longer at the top + assert sim.command("region list denied") == "-none-" + sim.reboot() # nothing was saved + assert sim.command("region") == SMALL_DUMP + sim.command("region denyf harbour") + assert sim.command("region save") == "OK" + sim.reboot() + assert "harbour\n" in sim.command("region") + assert sim.command("region frobnicate") == "Err - ??" + + +async def test_the_mock_repeater_answers_the_region_cli_and_the_request_alike() -> None: + """The anonymous request reads the same table the CLI edits.""" + device = MockDevice() + await device.connect() + assert await device.admin_login(NODE, "admin") + assert await device.send_remote_command(NODE, "region") == SMALL_DUMP + assert await device.request_regions(NODE) == ["*", "lakeside", "lakeside-north", "harbour"] + await device.send_remote_command(NODE, "region denyf *") + assert await device.request_regions(NODE) == ["lakeside", "lakeside-north", "harbour"] + await device.send_remote_command(NODE, "reboot") # unsaved, so it comes back + assert (await device.request_regions(NODE))[0] == "*" + await device.disconnect() + + +# --- the region store remembers the whole answer ---------------------------------------- + + +def test_the_store_keeps_whether_a_repeater_relays_unscoped_floods(tmp_path: Path) -> None: + """The ``*`` names no region, so it is kept beside the regions — and survives a reload.""" + store = RegionStore(tmp_path / "regions.json") + assert store.answer_of("a1b2c3d4e5f6") is None + store.learn_carried("a1b2c3d4e5f6aa", ["*", "lakeside"]) + answer = store.answer_of("a1b2c3d4e5f6") + assert answer is not None and answer.unscoped + assert store.carried_by("a1b2c3d4e5f6") == ["lakeside"] + + again = RegionStore(tmp_path / "regions.json") # read back from disk + assert again.answer_of("a1b2c3d4e5f6").unscoped + again.learn_carried("a1b2c3d4e5f6", []) + assert not again.answer_of("a1b2c3d4e5f6").unscoped + assert again.carried_by("a1b2c3d4e5f6") == [] + + +# --- the editor ------------------------------------------------------------------------ + + +class _ScriptedUi: + """A UI surface that answers each question from a script and records what was asked.""" + + def __init__(self, *answers) -> None: # noqa: ANN002 + self.answers = list(answers) + self.asked: list[tuple[str, str]] = [] + self.messages: list[str] = [] + self.session = SimpleNamespace(message_dialog=self._message, invalidate=lambda: None) + + def _next(self, kind: str, title: str): # noqa: ANN202 + self.asked.append((kind, title)) + return self.answers.pop(0) if self.answers else None + + async def select(self, title, items, **kwargs): # noqa: ANN001, ANN003, ANN201 + self.last_items = items + self.last_prompt = kwargs.get("prompt", "") + return self._next("select", title) + + async def text(self, title, **kwargs): # noqa: ANN001, ANN003, ANN201 + answer = self._next("text", title) + check = kwargs.get("validate") + if answer is not None and check is not None: + assert check(answer) is True, check(answer) + return answer + + async def dialog(self, prompt, buttons, **kwargs): # noqa: ANN001, ANN003, ANN201 + self.last_dialog = kwargs + return self._next("dialog", kwargs.get("title", "")) + + @asynccontextmanager + async def busy_overlay(self, *args, **kwargs): # noqa: ANN002, ANN003, ANN201 + yield + + async def _message(self, body, *, title: str = "") -> None: # noqa: ANN001 + self.messages.append(body.plain if isinstance(body, Text) else str(body)) + + +@pytest.fixture() +async def region_device(monkeypatch): + """The simulator, logged in to both repeaters, recording every command, unpaced.""" + real_sleep = asyncio.sleep + + async def no_wait(_delay, result=None): + return await real_sleep(0, result) + + monkeypatch.setattr(asyncio, "sleep", no_wait) + device = MockDevice() + await device.connect() + assert await device.admin_login(NODE, "admin") + assert await device.admin_login(BIG, "admin") + device.sent = [] + original = device.send_remote_command + + async def recording(node, command, *, timeout=8.0): + device.sent.append(command) + return await original(node, command, timeout=timeout) + + monkeypatch.setattr(device, "send_remote_command", recording) + yield device + await device.disconnect() + + +def _ctx(tmp_path: Path, *answers) -> SimpleNamespace: # noqa: ANN002 + return SimpleNamespace( + ui=_ScriptedUi(*answers), + region_store=RegionStore(tmp_path / "regions.json"), + preferences=SimpleNamespace(trace_cooldown_s=0), + ) + + +async def _table(device) -> RegionTable: # noqa: ANN001 + dump = await device.send_remote_command(NODE, "region") + default = await device.send_remote_command(NODE, "region default") + device.sent.clear() + return parse_region_dump(dump).with_default(default) + + +@pytest.mark.parametrize( + "region,pick,command", + [ + ("lakeside", "deny", "region denyf lakeside"), + ("lakeside-south", "allow", "region allowf lakeside-south"), + ("harbour", "home", "region home harbour"), + ("harbour", "default", "region default harbour"), + ], +) +async def test_each_region_action_sends_its_one_command( + tmp_path, region_device, region, pick, command +) -> None: + """One pick, one command; the folded table matches the repeater's next dump.""" + ctx = _ctx(tmp_path, pick) + table = await _table(region_device) + table, unsaved = await region_editor._region_actions(ctx, region_device, NODE, table, 0, region) + assert region_device.sent == [command] + assert unsaved == (0 if pick == "default" else 1) # a default saves the table itself + fresh = parse_region_dump(await region_device.send_remote_command(NODE, "region")) + assert _rows(table) == _rows(fresh) + + +async def test_denying_unscoped_floods_asks_first(tmp_path, region_device) -> None: + """Every plain flood would stop at this repeater: Cancel sends nothing at all.""" + ctx = _ctx(tmp_path, "deny", None) + table = await _table(region_device) + await region_editor._region_actions(ctx, region_device, NODE, table, 0, "*") + assert region_device.sent == [] + assert ctx.ui.last_dialog.get("danger") + + ctx = _ctx(tmp_path, "deny", "deny") + table, unsaved = await region_editor._region_actions(ctx, region_device, NODE, table, 0, "*") + assert region_device.sent == ["region denyf *"] and unsaved == 1 + assert not table.wildcard.flood + + +async def test_the_wildcard_clears_a_home_elsewhere(tmp_path, region_device) -> None: + """Home on the wildcard means no home region: ``region home *``.""" + await region_device.send_remote_command(NODE, "region home harbour") + table = await _table(region_device) + ctx = _ctx(tmp_path, "home") + table, _ = await region_editor._region_actions(ctx, region_device, NODE, table, 0, "*") + assert region_device.sent == ["region home *"] and table.home == "*" + + +async def test_clearing_the_default_sends_null(tmp_path, region_device) -> None: + """Clearing the default saves the table too, so nothing is left unsaved.""" + await region_device.send_remote_command(NODE, "region default harbour") + table = await _table(region_device) + ctx = _ctx(tmp_path, "undefault") + table, unsaved = await region_editor._region_actions( + ctx, region_device, NODE, table, 3, "harbour" + ) + assert region_device.sent == ["region default "] + assert table.default is None and unsaved == 0 + + +async def test_adding_under_a_region_puts_it_there(tmp_path, region_device) -> None: + """Asked from a row, only the name is asked; the parent is the row.""" + ctx = _ctx(tmp_path, "add", "harbour-bay") + table = await _table(region_device) + table, unsaved = await region_editor._region_actions( + ctx, region_device, NODE, table, 0, "harbour" + ) + assert region_device.sent == ["region put harbour-bay harbour"] + assert table.get("harbour-bay").parent == "harbour" and table.get("harbour-bay").flood + assert unsaved == 1 + + +async def test_adding_from_the_actions_asks_where_then_the_name(tmp_path, region_device) -> None: + """Asked from Actions, the parent comes first, then the name.""" + ctx = _ctx(tmp_path, "*", "cove") + table = await _table(region_device) + table, _ = await region_editor._add_region(ctx, region_device, NODE, table, 0, None) + assert [kind for kind, _ in ctx.ui.asked] == ["select", "text"] + assert region_device.sent == ["region put cove"] + + +async def test_esc_on_the_name_steps_back_to_where(tmp_path, region_device) -> None: + """The add flow is a stack: Esc on the name re-asks the parent, then Esc abandons.""" + ctx = _ctx(tmp_path, "harbour", None, None) + table = await _table(region_device) + await region_editor._add_region(ctx, region_device, NODE, table, 0, None) + assert [kind for kind, _ in ctx.ui.asked] == ["select", "text", "select"] + assert region_device.sent == [] + + +async def test_removing_asks_in_red_and_sends_remove(tmp_path, region_device) -> None: + """A single-record delete: a red Cancel/Remove confirm, then one command.""" + ctx = _ctx(tmp_path, "remove", "remove") + table = await _table(region_device) + table, unsaved = await region_editor._region_actions( + ctx, region_device, NODE, table, 0, "lakeside-south" + ) + assert ctx.ui.last_dialog.get("destructive") + assert region_device.sent == ["region remove lakeside-south"] + assert table.get("lakeside-south") is None and unsaved == 1 + + +async def test_a_region_with_sub_regions_is_not_removed(tmp_path, region_device) -> None: + """The firmware refuses it, so the page never sends it and says why.""" + ctx = _ctx(tmp_path, "blocked") + table = await _table(region_device) + await region_editor._region_actions(ctx, region_device, NODE, table, 0, "lakeside") + assert region_device.sent == [] + assert "lakeside-north" in ctx.ui.messages[0] + # …and Del on it asks nothing and sends nothing either. + ctx = _ctx(tmp_path) + await region_editor._remove(ctx, region_device, NODE, table, 0, "lakeside") + assert region_device.sent == [] and ctx.ui.asked == [] + + +async def test_saving_clears_the_unsaved_count(tmp_path, region_device) -> None: + """``region save`` is the commit.""" + ctx = _ctx(tmp_path) + table = await _table(region_device) + _, unsaved = await region_editor._edit(ctx, region_device, NODE, table, 3, "region save") + assert region_device.sent == ["region save"] and unsaved == 0 + + +async def test_a_refused_edit_says_so_and_changes_nothing(tmp_path, region_device) -> None: + """The repeater's own words are shown, and the table stays as it was.""" + ctx = _ctx(tmp_path) + table = await _table(region_device) + after, unsaved = await region_editor._edit( + ctx, region_device, NODE, table, 0, "region remove lakeside" + ) + assert after is table and unsaved == 0 + assert "Err - not empty" in ctx.ui.messages[0] + + +async def test_an_accepted_edit_teaches_the_store(tmp_path, region_device) -> None: + """What the table says it relays is what the node page will show.""" + ctx = _ctx(tmp_path) + table = await _table(region_device) + await region_editor._edit(ctx, region_device, NODE, table, 0, "region allowf lakeside-south") + node_id = region_editor.node_id_of(NODE) + assert "lakeside-south" in ctx.region_store.carried_by(node_id) + assert ctx.region_store.answer_of(node_id).unscoped + + +async def test_reading_a_table_that_fits_asks_two_questions(tui_ctx, region_device) -> None: + """The dump and the default — no list reads when nothing was cut.""" + table = await region_editor.read_table(tui_ctx, region_device, NODE) + assert region_device.sent == ["region", "region default"] + assert table is not None and table.complete and table.default_known + + +async def test_reading_a_cut_table_recovers_the_rest_from_the_lists(tui_ctx, region_device) -> None: + """Cut at the cap: the lists are asked, the rest joins unplaced, the store learns all.""" + table = await region_editor.read_table(tui_ctx, region_device, BIG) + assert region_device.sent == [ + "region", + "region default", + "region list allowed", + "region list denied", + ] + assert table.cut and table.lists_read and table.complete + assert not table.get("hilltop").placed and table.get("hilltop").flood + assert not table.get("riverside-lower").flood + carried = tui_ctx.region_store.carried_by(region_editor.node_id_of(BIG)) + assert "hilltop" in carried and "riverside-lower" not in carried + + +# --- the page ---------------------------------------------------------------------------- + + +def _plain_rows(items: list) -> list[str]: + out = [] + for item in items: + text = item.text(72) + out.append(text.plain if isinstance(text, Text) else str(text)) + return out + + +def test_the_page_draws_the_tree_and_says_where_it_was_cut() -> None: + """A cut table says where, and that ^R reads again when the lists never came.""" + sim = SimulatedRegionMap([(f"region-number-{i:02d}", "*", i % 2 == 0) for i in range(10)]) + table = parse_region_dump(sim.command("region")) + title, items = region_items(BIG, table, 0) + rows = _plain_rows(items) + assert title == "Regions — Local-Repeater" + assert any("⚠ the reply ran out at 160 bytes after" in r for r in rows) + assert any("^R reads again" in r for r in rows) # the lists never came + assert not any("Save" in r for r in rows) # nothing unsaved, no save pair + + +def test_unsaved_edits_put_the_save_pair_on_the_page() -> None: + """The Apply/discard pair, worded for a table that is live but not saved.""" + table = parse_region_dump(SMALL_DUMP) + title, items = region_items(NODE, table, 2) + rows = _plain_rows(items) + assert title.endswith("· 2 unsaved") + assert rows[-2:] == ["✓ Save 2 changes to the repeater", "✗ Back — a reboot undoes them"] + + +def test_only_a_childless_region_is_deletable() -> None: + """Del lights only where ``region remove`` would succeed.""" + table = parse_region_dump(SMALL_DUMP) + _, items = region_items(NODE, table, 0) + deletable = { + item.value.name + for item in items + if isinstance(getattr(item, "value", None), RegionPick) and item.deletable + } + assert deletable == {"lakeside-north", "lakeside-south", "harbour"} + + +async def test_ctrl_r_reads_again_and_f3_is_read_over_remove() -> None: + """A full-screen page; ``^R`` re-reads; the Shift half of F3 lights only on a removable row.""" + table = parse_region_dump(SMALL_DUMP) + title, items = region_items(NODE, table, 0) + menu = RegionMenu(title, items) + menu.future = asyncio.get_running_loop().create_future() + assert not menu.floating + lane = menu.fkey_lane + assert (lane[2].label, lane[2].opp_label) == ("Read", "Remove") + assert not lane[2].opp_enabled # the wildcard row is highlighted first + assert "Del remove" not in menu.footer_hint + menu.handle("down") + menu.handle("down") # lakeside-north + assert menu.fkey_lane[2].opp_enabled + assert "Del remove" in menu.footer_hint + menu.handle("retry") + assert menu.future.result() == region_editor._READ + + +async def _step_until(predicate, *, limit: int = 2000): # noqa: ANN001, ANN202 + """Yield to the event loop until ``predicate()`` is truthy; return its value.""" + value = predicate() + for _ in range(limit): + if value: + return value + await asyncio.sleep(0) + value = predicate() + return value + + +async def test_a_visit_is_one_page_that_asks_before_leaving_edits_unsaved( + tui_ctx, region_device +) -> None: + """The page stays pushed for the visit; Esc with an edit live but unsaved asks first. + + Keep editing leaves the page where it was; Leave then ends the visit with the stack + exactly as it was found. + """ + from meshterm.ui.tui.prompt import ButtonDialog + + session = tui_ctx.ui.session + task = asyncio.ensure_future(region_editor.open_region_editor(tui_ctx, region_device, NODE)) + try: + page = await _step_until(lambda: isinstance(session.top, RegionMenu) and session.top) + assert page is not None, "the region page never opened" + assert region_device.sent == ["region", "region default"] + assert page.title == "Regions — Yagi-Repeater" + + region_device.sent.clear() + page.resolve(region_editor._SAVE) # nothing is unsaved, but a save is still a save + await _step_until(lambda: region_device.sent) + assert region_device.sent == ["region save"] + + # An edit through the row's own popup: deny lakeside. + await _step_until(lambda: session.top is page) + page.resolve(RegionPick("lakeside")) + popup = await _step_until( + lambda: session.top if session.top is not page and session.top else None + ) + popup.resolve("deny") + await _step_until(lambda: "· 1 unsaved" in page.title) + assert region_device.sent[-1] == "region denyf lakeside" + + page.handle("escape") + confirm = await _step_until( + lambda: session.top if isinstance(session.top, ButtonDialog) else None + ) + confirm.resolve("keep") + await _step_until(lambda: session.top is page) + assert not task.done() + + page.handle("escape") + confirm = await _step_until( + lambda: session.top if isinstance(session.top, ButtonDialog) else None + ) + confirm.resolve("leave") + await task + finally: + if not task.done(): + task.cancel() + assert session._stack == [] + + +# --- the node page ------------------------------------------------------------------- + + +def test_the_node_page_row_says_each_state_in_its_own_words(tmp_path: Path) -> None: + """Answered, not asked, no answer — never one read as another.""" + from meshterm.ui.node_detail_screen import regions_value + + store = RegionStore(tmp_path / "regions.json") + node_id = "a1a1a1a1a1a1" + assert regions_value(store, node_id, routed=True).plain == "not asked yet" + assert "neighbour" in regions_value(store, node_id, routed=False).plain + assert regions_value(store, node_id, routed=True, failed=True).plain.startswith("no answer") + store.learn_carried(node_id, ["*", "lakeside", "harbour"]) + shown = regions_value(store, node_id, routed=True).plain + assert shown.startswith("lakeside, harbour · unscoped too · answered now") + store.learn_carried(node_id, ["*"]) + assert regions_value(store, node_id, routed=True).plain.startswith("unscoped floods only") + store.learn_carried(node_id, []) + assert regions_value(store, node_id, routed=True).plain.startswith("none") + stale = regions_value(store, node_id, routed=True, failed=True).plain + assert stale.endswith("no answer now") + + +async def test_asking_from_the_node_page_learns_or_says_why_not(tmp_path: Path) -> None: + """One request: learned on an answer, explained on silence, the old answer kept.""" + from meshterm.ui import node_detail_screen + + device = MockDevice() + await device.connect() + ctx = _ctx(tmp_path) + + async def the_device(): # noqa: ANN202 + return device + + ctx.device = the_device + node_id = NODE.public_key[:12] + failed = await node_detail_screen._ask_regions(ctx, NODE, node_id, NODE.name, routed=True) + assert not failed + assert ctx.region_store.carried_by(node_id) == ["lakeside", "lakeside-north", "harbour"] + + device._unreachable.add(NODE.name) + failed = await node_detail_screen._ask_regions(ctx, NODE, node_id, NODE.name, routed=False) + assert failed and "only a neighbour answers" in ctx.ui.messages[0] + assert ctx.region_store.carried_by(node_id) # the earlier answer is kept + await device.disconnect() + + +async def test_an_unreachable_repeater_raises_rather_than_answering_empty() -> None: + """Silence is not "carries nothing": the request raises, and nothing is learned.""" + device = MockDevice() + await device.connect() + device._unreachable.add(NODE.name) + with pytest.raises(DeviceCommandError): + await device.request_regions(NODE) + await device.disconnect() + + +# --- shared fixture ------------------------------------------------------------------- + + +@pytest.fixture() +def tui_ctx(tmp_path: Path): # noqa: ANN201 + """A mock-backed context wired to a headless TUI session (as the admin tests use).""" + import io + + from rich.console import Console + + from meshterm.context import AppContext + from meshterm.core.admin_store import AdminStore + from meshterm.core.config import Settings + from meshterm.core.device_store import DeviceStore + from meshterm.persistence.repository import Repository + from meshterm.ui.surface import TuiUi + from meshterm.ui.tui.session import TuiSession + + settings = Settings(config_dir=tmp_path, db_path=tmp_path / "regions.db") + ctx = AppContext( + console=Console(file=io.StringIO()), + settings=settings, + repo=Repository(settings.db_path), + device_store=DeviceStore(tmp_path / "devices.json"), + admin_store=AdminStore(tmp_path / "admin.json"), + mock=True, + ) + ctx.ui = TuiUi(TuiSession()) + yield ctx + ctx.repo.close() diff --git a/tests/test_regions.py b/tests/test_regions.py index 0a21550..5cf8818 100644 --- a/tests/test_regions.py +++ b/tests/test_regions.py @@ -36,7 +36,7 @@ from meshterm.core.regions import ( from meshterm.persistence.repository import Repository #: A channel-text payload: channel hash, 2-byte MAC, ciphertext (contents are arbitrary). -_PAYLOAD = bytes.fromhex("a7" "1c2d" "00112233445566778899aabbccddeeff") +_PAYLOAD = bytes.fromhex("a71c2d00112233445566778899aabbccddeeff") _GRP_TXT = 5