diff --git a/docs/cli/README.md b/docs/cli/README.md index 9ce3a8e..64a958e 100644 --- a/docs/cli/README.md +++ b/docs/cli/README.md @@ -1665,6 +1665,112 @@ or a hop that is not whole bytes of hex, is a usage error (`2`). `{"site", "active", "paths"}`. Each change prints the object that it wrote, for example `{"active": "Foulab"}`. +#### `meshterm route` + +Show, change, and keep the device routes. The companion holds one *device route* for each +contact: the relays from your node to the contact. With no route, the radio floods the next +message. With an empty route, the contact is a neighbour. The radio replaces the route each +time that it learns a new one, and it never forgets a route that stopped to work. A route +that you **keep** belongs to the active site (or to a fixed device). MeshTerm writes a kept +route back each time that the radio replaces it. + +A contact is its name, or the first digits of its key. A `SPEC` is the same as `--path` of a +trace: hops in hex, separated by commas (`a1,3d`). An empty `SPEC` (`--path ""`) means no +relay. + +| Command | What it does | +| --- | --- | +| `route` or `route list` | Each contact that has a device route or a kept route. | +| `route show CONTACT` | The route to one contact, how the radio got it, and where you keep it. | +| `route set CONTACT --path SPEC` | Write a route to the radio. `--keep` also keeps it. | +| `route forget CONTACT --yes` | Clear the route, so that the next message floods. A kept route stays kept. | +| `route keep CONTACT [--path SPEC]` | Keep a route. With no `--path`, MeshTerm keeps the route that the radio holds now. | +| `route unkeep CONTACT` | Stop keeping the route. The radio keeps the route that it holds. | +| `route discover CONTACT [--use]` | Send one path discovery and show the route each way. `--use` writes the outward route to the radio. | +| `route sync` | Make the routes of the radio follow the active site and the kept routes now. | + +```console +$ meshterm route list +NAME TYPE HASH PATH ORIGIN KEPT ROUTE +Alice companion d4 a1b2c3d4 kept a1 MockCompanion (00) → Yagi-Repeater (a1b2c3d4) → Alice (d4) +Local-Repeater repeater b2 direct learned - MockCompanion (00) → Local-Repeater (b2) +$ meshterm route show Alice +node Alice +type companion +hash d4 +key d4e5f6a700000000000000000000000000000000000000000000000000000000 +path a1b2c3d4 +origin kept +kept a1 +kept_by site Home +kept_in_radio yes +skipped no +first_hop_heard - +route MockCompanion (00) → Yagi-Repeater (a1b2c3d4) → Alice (d4) +``` + +`path` is the route that the radio holds, and `kept` is the route that you keep. Both are +specs, and a spec goes back into `--path` as it is. `direct` is the plain word for an empty +spec, and `-` means no route. `origin` is `kept`, `set` (you wrote it in this run), `learned` +(the radio got it from a path return), or `flood` (no route). The drawn `route` has your node +and the contact at its ends. `skipped` is `yes` when MeshTerm does not write the kept route +back because its first hop is silent, and `first_hop_heard` then says when MeshTerm last heard +that hop. + +`discover` sends one path discovery. It is one transmission, and the command waits for the +answer. It prints the route in each direction, because a radio link is not symmetric. The +radio does not change its route for this request. With `--use`, MeshTerm writes the outward +route. + +```console +$ meshterm route discover Alice +node Alice +hash d4 +answered yes +out_path a1 +in_path a1 +used no +out_route MockCompanion (00) → Yagi-Repeater (a1) → Alice (d4) +in_route Alice (d4) → Yagi-Repeater (a1) → MockCompanion (00) +``` + +`sync` does what MeshTerm does at each connection. It saves the routes that the radio +learned at another site, and clears them from the radio. It writes back the routes that +belong to the active site, and the routes that you keep. It prints what it did on stderr, +and the counts on stdout. + +Each command that changes a route prints the route as it is afterwards, in the shape of +`show`. All these commands open the device. A command that keeps a route (`keep`, and +`set --keep`) needs a record to hold it. When no site is active and the device is not +fixed, the command fails with `1`, and nothing is written. Its sentence names +`meshterm outbound use `. + +`list` returns `5` when no contact has a route. `unkeep` returns `5` when no route was kept. +`discover` returns `5` when no answer comes. A bad `SPEC`, a route that the radio cannot +hold, and a contact that does not exist are usage errors (`2`). `keep` with no `--path` +is also a usage error when the radio has no route to keep. + +**`--json`** gives `list` as an array, and each other command as one object. They have +these fields: + +| Field | Type | Meaning | +| --- | --- | --- | +| `node` | object | The contact: the shared node object. | +| `path` | string \| null | The route in the radio, as a spec. `""` is no relay. `null` is no route. | +| `origin` | string | `kept`, `set`, `learned`, or `flood`. | +| `kept` | string \| null | The route that you keep, as a spec. `null` when you keep none. | +| `kept_by` | object \| null | `{"source": "site" or "device", "name": …}`. `null` when you keep no route. `show` only. | +| `kept_in_radio` | boolean \| null | Whether the radio holds the kept route. `show` only. | +| `skipped` | boolean \| null | Whether the kept route is not written because its first hop is silent. `show` only. | +| `first_hop_heard_at` | string \| null | When MeshTerm last heard that first hop (UTC). `show` only. | +| `route` | array \| null | The nodes from your node to the contact, each as a node object. `null` when there is no route. | + +`discover` gives `node`, `answered`, `out_path`, `in_path`, `used`, `out_route`, and +`in_route`. Each is `null` when no answer came. `sync` gives `site` (the active site, or +`null`), `saved` (an array of `{"site", "routes"}`), `restored`, `kept_written`, +`kept_skipped` (the names of the contacts), and `failed` (the names of the contacts that the +radio refused). + #### `meshterm tx-optimize` Sweep the transmit power of a remote node against a target. Then select the lowest level diff --git a/meshterm/tools/route.py b/meshterm/tools/route.py new file mode 100644 index 0000000..2e60c08 --- /dev/null +++ b/meshterm/tools/route.py @@ -0,0 +1,716 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The ``route`` tool: the device routes that the companion holds to its contacts. + +The companion holds one *device route* for each contact: the relays from our node to the +contact (refer to :mod:`meshterm.services.device_routes`). No route means that the radio +floods the next message. An empty route means no relay: the contact is a neighbour. The +radio replaces the route each time that it learns a new one, and it never forgets a route +that stopped to work. This tool lets the user see, change, and keep these routes. + +This tool has only a command-line face. In the menu, the same actions are on the node page +of a contact. Thus the menu has no row for this tool. + +On the CLI: + +* ``route`` (or ``route list``): each contact that has a device route or a kept route. + The exit status is ``5`` when there is none. +* ``route show CONTACT``: the route of one contact, how the radio got it, and where the + user keeps it. +* ``route set CONTACT --path SPEC [--keep]``: write a route to the radio. ``--path ""`` + means no relay. ``--keep`` also keeps the route. +* ``route forget CONTACT --yes``: clear the route, so that the next message floods. A kept + route stays kept. +* ``route keep CONTACT [--path SPEC]``: keep a route. With no ``--path``, MeshTerm keeps the + route that the radio holds now. +* ``route unkeep CONTACT``: stop keeping the route. The exit status is ``5`` when the + route was not kept. +* ``route discover CONTACT [--use]``: send one path discovery (one transmission) and show + the route in each direction. ``--use`` writes the outward route to the radio. The exit + status is ``5`` when no answer comes. +* ``route sync``: make the routes of the radio follow the active site and the kept routes, + as MeshTerm does at each connection. + +A contact is given by its name or by the first digits of its key. A ``SPEC`` is a list of +hops in hex, separated by commas (``a1,3d``), the same as ``--path`` of a trace. A bad +spec is a usage error (``2``). ``keep`` fails (``1``) when no site is active and the +device is not fixed, because no record can hold the route. + +Each action that changes a route prints the route as it is afterwards, in the shape of +``show``. +""" + +from __future__ import annotations + +from dataclasses import dataclass, replace +from typing import TYPE_CHECKING, Any + +import typer + +from ..context import AppContext +from ..core import exitcodes +from ..core.models import NODE_TYPE_LABELS, Contact +from ..core.outbound_store import NoRouteOwnerError, RouteOwner, RoutePath, clean_route +from ..services.device_routes import RouteStatus, report_notice, silent_before_now +from .base import Tool, ToolResult, register + +if TYPE_CHECKING: # pragma: no cover - typing only + from datetime import datetime + + from ..services.topology import MeshTopology + from ..ui.fields import NodeRef + from ..ui.report import Block, Column + +#: The plain word for a route with no relay: the contact is a neighbour. +DIRECT = "direct" + +#: The origin of a route that is not there, in both faces. +FLOOD = "flood" + + +@register +class RouteTool(Tool): + """Show, change, and keep the device routes of the contacts (command line only).""" + + name = "route" + title = "Device routes" + icon = "🧭" + help = "The routes that the radio holds to your contacts" + category = "Explore" + order = 36 + menu_visible = False # the menu works on a route from the node page of the contact + + async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: + """Do one CLI operation on the device routes. + + Args: + ctx: The shared application context. + params: ``op``: one of ``list``, ``show``, ``set``, ``forget``, ``keep``, + ``unkeep``, ``discover``, and ``sync``. The operations on one contact also + take ``contact``. ``set`` takes ``path`` and ``keep``. ``keep`` takes an + optional ``path``. ``discover`` takes ``use``. + + Returns: + A :class:`ToolResult` with the report of the operation. + + Raises: + typer.BadParameter: If the contact is not known, or if a spec is not valid. + DeviceConfigError: If ``keep`` has no site or fixed device to keep the route. + """ + op = params.get("op", "list") + if op == "sync": + return await _sync(ctx) + scene = await _Scene.load(ctx) + if op == "list": + return _list(ctx, scene) + contact = _resolve(scene.contacts, str(params["contact"])) + if op == "show": + status = scene.status(ctx, contact) + return ToolResult( + summary={"contact": contact.name, "origin": status.origin or FLOOD}, + report=(_show_facts(scene, contact, status),), + ) + if op == "set": + return await _set(ctx, scene, contact, str(params["path"]), bool(params.get("keep"))) + if op == "forget": + return await _forget(ctx, scene, contact) + if op == "keep": + return await _keep_op(ctx, scene, contact, params.get("path")) + if op == "unkeep": + return await _unkeep(ctx, scene, contact) + if op == "discover": + return await _discover(ctx, scene, contact, bool(params.get("use"))) + raise typer.BadParameter(f"unknown operation {op!r}") # pragma: no cover - the CLI sets it + + # -- CLI -------------------------------------------------------------------- + + def register_cli(self, app: typer.Typer) -> None: + """Register the ``route`` subcommand group. + + Args: + app: The Typer application. + """ + from ..cli import run_tool_command + + group = typer.Typer(help=self.help, no_args_is_help=False, rich_markup_mode=None) + + @group.callback(invoke_without_command=True) + def _root(ctx: typer.Context) -> None: + """List the device routes when no subcommand is given.""" + if ctx.invoked_subcommand is None: + run_tool_command(self, {"op": "list"}) + + @group.command("list", help="List the contacts that have a device route or a kept route") + def _list_cmd() -> None: + run_tool_command(self, {"op": "list"}) + + @group.command("show", help="Show the route to one contact and where it is kept") + def _show_cmd( + contact: str = typer.Argument(..., help="The contact name, or the start of its key"), + ) -> None: + run_tool_command(self, {"op": "show", "contact": contact}) + + @group.command("set", help="Write a device route to the radio") + def _set_cmd( + contact: str = typer.Argument(..., help="The contact name, or the start of its key"), + path: str = typer.Option( + ..., "--path", help='The relays in hex, like a1,3d ("" for no relay)' + ), + keep: bool = typer.Option(False, "--keep", help="Also keep the route"), + ) -> None: + run_tool_command(self, {"op": "set", "contact": contact, "path": path, "keep": keep}) + + @group.command("forget", help="Clear the route, so that the next message floods") + def _forget_cmd( + contact: str = typer.Argument(..., help="The contact name, or the start of its key"), + yes: bool = typer.Option(False, "--yes", help="Confirm this destructive action"), + ) -> None: + if not yes: + raise typer.BadParameter( + "this clears the route that the radio holds, and the next message " + "floods. Run it again with --yes to confirm" + ) + run_tool_command(self, {"op": "forget", "contact": contact}) + + @group.command("keep", help="Keep a route, so that MeshTerm writes it back") + def _keep_cmd( + contact: str = typer.Argument(..., help="The contact name, or the start of its key"), + path: str | None = typer.Option( + None, "--path", help="The relays in hex (default: the route the radio holds)" + ), + ) -> None: + run_tool_command(self, {"op": "keep", "contact": contact, "path": path}) + + @group.command("unkeep", help="Stop keeping the route to a contact") + def _unkeep_cmd( + contact: str = typer.Argument(..., help="The contact name, or the start of its key"), + ) -> None: + run_tool_command(self, {"op": "unkeep", "contact": contact}) + + @group.command("discover", help="Send one path discovery and show the route each way") + def _discover_cmd( + contact: str = typer.Argument(..., help="The contact name, or the start of its key"), + use: bool = typer.Option(False, "--use", help="Write the outward route to the radio"), + ) -> None: + run_tool_command(self, {"op": "discover", "contact": contact, "use": use}) + + @group.command("sync", help="Make the routes follow the active site and the kept routes") + def _sync_cmd() -> None: + run_tool_command(self, {"op": "sync"}) + + app.add_typer(group, name=self.name) + + +# -- what a run knows -------------------------------------------------------------------- + + +def _key(contact: Contact) -> str: + """The full public key of a contact in lowercase hex, or ``""``.""" + return (contact.public_key or "").lower().removeprefix("0x") + + +@dataclass(slots=True) +class _Scene: + """What one run needs to describe a route: the contacts, our node, and the evidence. + + Attributes: + contacts: The contacts of the companion. + device_key: The public key of the companion, or ``""``. + device_name: The name of the companion, or ``""``. + size: The bytes of each hash in the radio, or ``None`` when the radio did not say. + topo: The evidence graph, to find a first hop that is silent. + silent_before: The time before which a first hop counts as silent. + """ + + contacts: list[Contact] + device_key: str + device_name: str + size: int | None + topo: MeshTopology + silent_before: datetime | None + + @classmethod + async def load(cls, ctx: AppContext) -> _Scene: + """Read the contacts and the identity of the companion, and build the evidence graph.""" + from ..services.outbound import device_identity, session_topology + + identity = await device_identity(ctx) + contacts = list(await ctx.devstate.contacts()) + try: + mode = await ctx.devstate.path_hash_mode() + except Exception: # noqa: BLE001 - an optional read. Without it, a hash has one byte. + mode = None + size = (mode + 1) if isinstance(mode, int) and 0 <= mode <= 3 else None + return cls( + contacts=contacts, + device_key=identity.key, + device_name=identity.name, + size=size, + topo=session_topology(ctx, identity.key, contacts), + silent_before=silent_before_now(ctx), + ) + + @property + def hash_digits(self) -> int: + """The hex digits of a hash in a drawn route.""" + return (self.size or 1) * 2 + + def status(self, ctx: AppContext, contact: Contact) -> RouteStatus: + """The route status of one contact, with the first hop test.""" + return ctx.routes.status( + contact, + device_key=self.device_key, + topo=self.topo, + silent_before=self.silent_before, + ) + + def ref(self, contact: Contact) -> NodeRef: + """The identity of a contact, with its hash at the width of the radio.""" + from ..ui.fields import NodeRef + + key = _key(contact) + return NodeRef( + name=contact.name or None, + key=key or None, + hash=(key or contact.key_prefix.lower())[: self.hash_digits] or None, + type=NODE_TYPE_LABELS.get(contact.node_type), + ) + + def self_ref(self) -> NodeRef: + """The identity of our node.""" + from ..ui.fields import NodeRef + + return NodeRef( + name=self.device_name or None, + key=self.device_key or None, + hash=self.device_key[: self.hash_digits] or None, + is_self=True, + ) + + def hop(self, hop: str) -> NodeRef: + """The identity of one relay. The name is known only when one contact matches.""" + from ..ui.fields import NodeRef + + found = [ + c for c in self.contacts if (_key(c) or c.key_prefix.lower()).startswith(hop.lower()) + ] + if len(found) != 1: + return NodeRef(hash=hop) + return NodeRef( + name=found[0].name or None, + key=_key(found[0]) or None, + hash=hop, + type=NODE_TYPE_LABELS.get(found[0].node_type), + ) + + def route( + self, contact: Contact, hops: tuple[str, ...] | None, *, outward: bool = True + ) -> list[NodeRef] | None: + """The route drawn from end to end, or ``None`` for no route. + + Args: + contact: The contact at the far end. + hops: The relays, in the order of travel. + outward: ``True`` for a route from our node to the contact, ``False`` for the + route that comes back. + """ + if hops is None: + return None + relays = [self.hop(hop) for hop in hops] + ends = (self.self_ref(), self.ref(contact)) + return [ends[0], *relays, ends[1]] if outward else [ends[1], *relays, ends[0]] + + def fit(self, contact: Contact, hops: RoutePath) -> RoutePath: + """Check a route against the hash width of the radio, before anything is written. + + Raises: + typer.BadParameter: If a hop is shorter than the hash width, or if the radio + cannot hold so many hops. Nothing is transmitted in this case, thus it is a + usage error and not a device failure. + """ + if self.size is None: + return hops + from ..core.connection import DeviceCommandError, route_at_width + + try: + return route_at_width(hops, self.size, name=contact.name) + except DeviceCommandError as exc: + raise typer.BadParameter(str(exc)) from exc + + +def _resolve(contacts: list[Contact], needle: str) -> Contact: + """The contact that a name or a key prefix gives (the resolver of ``chat``).""" + from .chat import _resolve_contact + + return _resolve_contact(contacts, needle) + + +def _spec_of(hops: tuple[str, ...] | None) -> str | None: + """A route as a spec: ``None`` for no route, ``""`` for no relay.""" + return None if hops is None else ",".join(hops) + + +def _parse_route(text: str) -> RoutePath: + """The route that the user typed. A bad one is a usage error.""" + route = clean_route(text) + if route is None: + raise typer.BadParameter( + f"{text!r} is not a route: give hops in hex, separated by commas (a1,3d), " + 'each node only one time, or "" for no relay' + ) + return route + + +def _say(text: str) -> str: + """A name or a spec for a message, safe in Rich markup.""" + from rich.markup import escape + + return escape(text) + + +# -- the operations ---------------------------------------------------------------------- + + +def _list(ctx: AppContext, scene: _Scene) -> ToolResult: + """Each contact that has a device route or a kept route.""" + rows = [] + for contact in sorted(scene.contacts, key=lambda c: (c.name.casefold(), _key(c))): + status = scene.status(ctx, contact) + if status.hops is None and status.kept is None: + continue + rows.append(_row(scene, contact, status)) + return ToolResult( + summary={"routes": len(rows)}, + report=(_listing(rows),), + exit_code=exitcodes.OK if rows else exitcodes.NO_RESULT, + ) + + +async def _set( + ctx: AppContext, scene: _Scene, contact: Contact, text: str, keep: bool +) -> ToolResult: + """Write a route to the radio, and keep it when the user asks.""" + route = scene.fit(contact, _parse_route(text)) + if keep: + _require_key(contact) + await _keep_route(ctx, contact, route) + written = route + else: + written = await ctx.routes.set(contact, route) + now = replace(contact, route_hops=written) + status = scene.status(ctx, now) + spec = ",".join(written) or DIRECT + note = " and kept" if keep else "" + return ToolResult( + summary={"contact": contact.name, "path": ",".join(written), "kept": keep}, + message=f"[ok]✓[/ok] route to [brand]{_say(contact.name)}[/brand] set to {spec}{note}", + report=(_show_facts(scene, now, status),), + ) + + +async def _forget(ctx: AppContext, scene: _Scene, contact: Contact) -> ToolResult: + """Clear the route, so that the next message to the contact floods.""" + await ctx.routes.forget(contact) + now = replace(contact, route_hops=None) + status = scene.status(ctx, now) + message = f"[ok]✓[/ok] the next message to [brand]{_say(contact.name)}[/brand] floods" + if status.kept is not None: + message += ". The kept route stays kept, so run [bold]route unkeep[/bold] to drop it" + return ToolResult( + summary={"contact": contact.name}, + message=message, + report=(_show_facts(scene, now, status),), + ) + + +async def _keep_op(ctx: AppContext, scene: _Scene, contact: Contact, text: object) -> ToolResult: + """Keep the given route, or the route that the radio holds now.""" + _require_key(contact) + if text is None: + held = scene.status(ctx, contact).hops + if held is None: + raise typer.BadParameter( + f"the radio has no route to {contact.name!r} to keep: give one with --path" + ) + route: RoutePath = tuple(held) + else: + route = scene.fit(contact, _parse_route(str(text))) + owner = await _keep_route(ctx, contact, route) + now = replace(contact, route_hops=route) + status = scene.status(ctx, now) + where = f"{owner.source} [brand]{_say(owner.name)}[/brand]" + return ToolResult( + summary={"contact": contact.name, "path": ",".join(route), "owner": owner.name}, + message=f"[ok]✓[/ok] keeping the route to [brand]{_say(contact.name)}[/brand] for {where}", + report=(_show_facts(scene, now, status),), + ) + + +async def _unkeep(ctx: AppContext, scene: _Scene, contact: Contact) -> ToolResult: + """Stop keeping the route to a contact. The radio keeps the route that it holds.""" + done = await ctx.routes.unkeep(contact) + status = scene.status(ctx, contact) + return ToolResult( + summary={"contact": contact.name, "unkept": done}, + message=( + f"[ok]✓[/ok] no longer keeping the route to [brand]{_say(contact.name)}[/brand]" + if done + else f"no route to {_say(contact.name)} was kept" + ), + report=(_show_facts(scene, contact, status),), + exit_code=exitcodes.OK if done else exitcodes.NO_RESULT, + ) + + +async def _discover(ctx: AppContext, scene: _Scene, contact: Contact, use: bool) -> ToolResult: + """Send one path discovery, and write the outward route when ``use`` asks.""" + found = await ctx.routes.discover(contact) + if found is None: + return ToolResult( + summary={"contact": contact.name, "answered": False}, + message=f"no answer from {_say(contact.name)}", + report=(_discovery_facts(scene, contact, None, used=False),), + exit_code=exitcodes.NO_RESULT, + ) + used = False + if use: + await ctx.routes.set(contact, tuple(found.out_hops)) + used = True + return ToolResult( + summary={ + "contact": contact.name, + "answered": True, + "out": ",".join(found.out_hops), + "in": ",".join(found.in_hops), + "used": used, + }, + message=( + f"[ok]✓[/ok] route to [brand]{_say(contact.name)}[/brand] set to the outward route" + if used + else None + ), + report=(_discovery_facts(scene, contact, found, used=used),), + ) + + +async def _sync(ctx: AppContext) -> ToolResult: + """Make the routes of the radio follow the active site and the kept routes.""" + report = await ctx.routes.reconcile() + notice = report_notice(report) + return ToolResult( + summary={ + "restored": report.restored, + "kept_written": report.kept_written, + "saved": sum(report.saved.values()), + }, + message=f"[ok]✓[/ok] {_say(notice)}" if notice else "[ok]✓[/ok] the routes are in line", + report=(_sync_facts(report),), + ) + + +def _require_key(contact: Contact) -> None: + """A kept route belongs to the full key of the contact, so the contact must have one.""" + if not _key(contact): + raise typer.BadParameter( + f"{contact.name!r} has no full key yet, so MeshTerm cannot keep a route to it" + ) + + +async def _keep_route(ctx: AppContext, contact: Contact, route: RoutePath) -> RouteOwner: + """Keep a route and write it. Without a site or a fixed device, this fails (exit 1).""" + from ..core.device_config import DeviceConfigError + + try: + return await ctx.routes.keep(contact, route) + except NoRouteOwnerError as exc: + raise DeviceConfigError( + "keep needs a site: make one active with `meshterm outbound use `, " + "or make this device a fixed device with `meshterm outbound fix`" + ) from exc + + +# -- the report shapes ------------------------------------------------------------------- + + +def _spec_cell(spec: str | None) -> str: + """The plain cell of a spec: the spec itself, :data:`DIRECT` for no relay, or absent.""" + from ..ui import script + + if spec is None: + return script.NONE + return spec or DIRECT + + +def _spec(key: str, header: str) -> Column: + """A route as a spec. ``""`` is a real answer (no relay) and ``None`` is no route. + + The document keeps both exactly, so a program can give a spec back to ``--path``. The + plain face writes the word :data:`DIRECT` for the empty spec, because an empty cell + reads as a missing value. + """ + from ..ui.report import Column, Lane + + return Column(key=key, lanes=(Lane(header=header, render=_spec_cell),)) + + +def _owner(key: str, header: str) -> Column: + """The record that keeps a route: ``site Home`` or ``device Roof``.""" + from ..ui import script + from ..ui.report import Column, Lane + + def cell(owner: RouteOwner | None) -> str: + return script.NONE if owner is None else f"{owner.source} {script.name(owner.name)}" + + return Column( + key=key, + lanes=(Lane(header=header, render=cell),), + json=lambda o: None if o is None else {"source": o.source, "name": o.name}, + ) + + +def _names(key: str, header: str) -> Column: + """A list of contact names: joined with commas, ``none`` when empty, an array in JSON.""" + from ..ui import script + from ..ui.report import Column, Lane + + return Column( + key=key, + lanes=( + Lane(header=header, render=lambda v: ", ".join(script.name(n) for n in v) or "none"), + ), + json=list, + ) + + +def _saved(key: str, header: str) -> Column: + """The routes that a sync saved for other sites: ``Foulab 2``, or an array of objects.""" + from ..ui import script + from ..ui.report import Column, Lane + + return Column( + key=key, + lanes=( + Lane( + header=header, + render=lambda v: ", ".join(f"{script.name(s)} {n}" for s, n in v.items()) or "none", + ), + ), + json=lambda v: [{"site": site, "routes": count} for site, count in v.items()], + ) + + +def _row(scene: _Scene, contact: Contact, status: RouteStatus) -> dict[str, Any]: + """The typed values of one contact for the listing.""" + return { + "node": scene.ref(contact), + "path": _spec_of(status.hops), + "origin": status.origin or FLOOD, + "kept": _spec_of(status.kept), + "route": scene.route(contact, status.hops), + } + + +def _listing(rows: list[dict[str, Any]]) -> Block: + """The contacts that have a route: the node, the spec, the origin, the kept spec, the route.""" + from ..ui import fields + from ..ui.report import Listing + + return Listing( + key="routes", + columns=( + fields.node("node", lanes=(("name", "NAME"), ("type", "TYPE"), ("hash", "HASH"))), + _spec("path", "PATH"), + fields.word("origin", "ORIGIN"), + _spec("kept", "KEPT"), + fields.route("route", "ROUTE"), + ), + rows=rows, + ) + + +def _show_facts(scene: _Scene, contact: Contact, status: RouteStatus) -> Block: + """All that MeshTerm knows about the route to one contact, as one set of facts.""" + from ..ui import fields + from ..ui.report import Facts + + kept = status.kept is not None + values = { + **_row(scene, contact, status), + "kept_by": status.owner if kept else None, + "kept_in_radio": status.kept_in_radio if kept else None, + "skipped": status.skipped_since is not None if kept else None, + "first_hop_heard_at": status.skipped_since, + } + return Facts( + key="route", + fields=( + fields.node( + "node", + lanes=(("name", "node"), ("type", "type"), ("hash", "hash"), ("key", "key")), + ), + _spec("path", "path"), + fields.word("origin", "origin"), + _spec("kept", "kept"), + _owner("kept_by", "kept_by"), + fields.flag("kept_in_radio", "kept_in_radio"), + fields.flag("skipped", "skipped"), + fields.when("first_hop_heard_at", "first_hop_heard"), + fields.route("route", "route"), + ), + values=values, + ) + + +def _discovery_facts(scene: _Scene, contact: Contact, found: Any, *, used: bool) -> Block: + """The answer of a path discovery: the route each way, and whether MeshTerm used it.""" + from ..ui import fields + from ..ui.report import Facts + + out = None if found is None else tuple(found.out_hops) + back = None if found is None else tuple(found.in_hops) + return Facts( + key="discovery", + fields=( + fields.node("node", lanes=(("name", "node"), ("hash", "hash"))), + fields.flag("answered", "answered"), + _spec("out_path", "out_path"), + _spec("in_path", "in_path"), + fields.flag("used", "used"), + fields.route("out_route", "out_route"), + fields.route("in_route", "in_route"), + ), + values={ + "node": scene.ref(contact), + "answered": found is not None, + "out_path": _spec_of(out), + "in_path": _spec_of(back), + "used": used, + "out_route": scene.route(contact, out), + "in_route": scene.route(contact, back, outward=False), + }, + ) + + +def _sync_facts(report: Any) -> Block: + """What a sync did, in counts and in names.""" + from ..ui import fields + from ..ui.report import Facts + + return Facts( + key="sync", + fields=( + fields.word("site", "site"), + _saved("saved", "saved"), + fields.integer("restored", "restored"), + fields.integer("kept_written", "kept_written"), + _names("kept_skipped", "kept_skipped"), + _names("failed", "failed"), + ), + values={ + "site": report.site or None, + "saved": dict(report.saved), + "restored": report.restored, + "kept_written": report.kept_written, + "kept_skipped": list(report.kept_skipped), + "failed": list(report.failed), + }, + ) diff --git a/tests/test_route_cli.py b/tests/test_route_cli.py new file mode 100644 index 0000000..60da4ea --- /dev/null +++ b/tests/test_route_cli.py @@ -0,0 +1,408 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Tests for ``meshterm route``: the device routes, on both faces of the command line. + +Each test runs the real Typer app against the simulator, in a config directory of its own. +The simulator forgets what it was told at the end of each run, but the kept routes are in +the outbound store on disk. Thus a test that needs a route to persist between two runs +keeps it, and reads it back with the next run. +""" + +from __future__ import annotations + +import json +from dataclasses import replace +from pathlib import Path + +import pytest +from typer.testing import CliRunner + +from meshterm.core import exitcodes +from meshterm.core.connection import MockDevice + +ALICE = "d4e5f6a7" + "0" * 56 + + +@pytest.fixture() +def run(tmp_path: Path, monkeypatch: pytest.MonkeyPatch): # noqa: ANN201 - a closure + """Run the real CLI against the simulator, with the whole config directory in tmp_path.""" + from meshterm.cli import app + + monkeypatch.setenv("MESHTERM_HOME", str(tmp_path / "home")) + runner = CliRunner() + + def invoke(*args: str): # noqa: ANN202 + return runner.invoke(app, ["--mock", "--db", str(tmp_path / "test.db"), *args]) + + return invoke + + +@pytest.fixture() +def with_site(run) -> None: # noqa: ANN001 + """Make a site and make it active, so that a route has a record to be kept in.""" + assert run("outbound", "set", "Home", "3d63c6429436").exit_code == exitcodes.OK + + +@pytest.fixture() +def flooding(monkeypatch: pytest.MonkeyPatch) -> None: + """Take the route of each simulated contact away, so that the radio floods to all.""" + original = MockDevice.get_contacts + + async def bare(self): # noqa: ANN001, ANN202 + return [replace(c, route_hops=None) for c in await original(self)] + + monkeypatch.setattr(MockDevice, "get_contacts", bare) + + +def _document(result) -> object: # noqa: ANN001 + """The one JSON document on stdout.""" + (line,) = result.stdout.splitlines() + return json.loads(line) + + +def _facts(result) -> dict[str, str]: # noqa: ANN001 + """The plain ``route show`` block as a dictionary (the first word is the key).""" + return dict(line.split(None, 1) for line in result.stdout.splitlines() if " " in line) + + +# -- list and show ----------------------------------------------------------------------- + + +def test_list_has_the_headings_a_script_looks_for(run) -> None: # noqa: ANN001 + """The headings are the contract of the plain face. The route is the last column.""" + result = run("route", "list") + assert result.exit_code == exitcodes.OK, result.output + header, *rows = result.stdout.splitlines() + assert header.split() == ["NAME", "TYPE", "HASH", "PATH", "ORIGIN", "KEPT", "ROUTE"] + assert len(rows) == 5 + assert run("route").stdout == result.stdout, "no subcommand means list" + + +def test_list_in_json_is_an_array_of_typed_rows(run) -> None: # noqa: ANN001 + """A flood is ``null``, no relay is ``""``, and a route draws both ends.""" + rows = _document(run("--json", "route", "list")) + by_name = {row["node"]["name"]: row for row in rows} + assert by_name["Alice"]["path"] == "a1b2c3d4" + assert by_name["Yagi-Repeater"]["path"] == "" + assert by_name["Alice"]["kept"] is None + alice = by_name["Alice"]["route"] + assert [hop["self"] for hop in alice] == [True, False, False] + assert alice[-1]["key"] == ALICE + + +def test_a_neighbour_is_direct_in_plain_and_empty_in_json(run) -> None: # noqa: ANN001 + """The empty spec is a real answer. The plain face has a word for it.""" + plain = run("route", "list").stdout + line = next(row for row in plain.splitlines() if row.startswith("Yagi-Repeater")) + assert "direct" in line.split() + + +def test_list_with_nothing_is_nothing_to_report(run, flooding) -> None: # noqa: ANN001 + """No route and nothing kept: exit status 5, with the empty document on stdout.""" + plain = run("route", "list") + assert plain.exit_code == exitcodes.NO_RESULT + machine = run("--json", "route", "list") + assert machine.exit_code == exitcodes.NO_RESULT + assert _document(machine) == [] + + +def test_show_states_the_route_and_where_it_comes_from(run) -> None: # noqa: ANN001 + """The facts block has the node, the spec, the origin, and the drawn route.""" + result = run("route", "show", "Alice") + assert result.exit_code == exitcodes.OK, result.output + facts = _facts(result) + assert facts["node"] == "Alice" + assert facts["path"] == "a1b2c3d4" + assert facts["origin"] == "learned" + assert facts["kept"] == "-" + assert "→" in facts["route"] + assert "★" not in facts["route"] + document = _document(run("--json", "route", "show", "Alice")) + assert document["origin"] == "learned" + assert document["kept_by"] is None + assert document["skipped"] is None + assert document["first_hop_heard_at"] is None + + +def test_show_takes_the_start_of_a_key(run) -> None: # noqa: ANN001 + """A contact is a name or the first digits of its key.""" + document = _document(run("--json", "route", "show", "d4e5")) + assert document["node"]["name"] == "Alice" + + +def test_an_unknown_contact_is_a_usage_error(run) -> None: # noqa: ANN001 + """MeshTerm decides this before it sends anything, so it is never a device failure.""" + for args in (("show", "Nobody"), ("forget", "Nobody", "--yes"), ("discover", "Nobody")): + result = run("route", *args) + assert result.exit_code == exitcodes.USAGE, args + assert result.stdout == "" + assert "Nobody" in result.stderr + + +# -- set and forget ---------------------------------------------------------------------- + + +def test_set_writes_a_route_and_shows_it(run) -> None: # noqa: ANN001 + """The answer is the route as it is afterwards. The ✓ line is on stderr.""" + result = run("route", "set", "Alice", "--path", "b2") + assert result.exit_code == exitcodes.OK, result.output + facts = _facts(result) + assert facts["path"] == "b2" + assert facts["origin"] == "set" + assert "set to b2" in result.stderr + assert "set to" not in result.stdout + + +def test_set_with_an_empty_path_means_no_relay(run) -> None: # noqa: ANN001 + """``--path ""`` is a neighbour. It is ``""`` in JSON, and exactly that comes back in.""" + document = _document(run("--json", "route", "set", "Alice", "--path", "")) + assert document["path"] == "" + assert document["origin"] == "set" + assert [hop["self"] for hop in document["route"]] == [True, False] + again = _document(run("--json", "route", "set", "Alice", "--path", document["path"])) + assert again["path"] == "" + + +def test_a_path_in_the_output_goes_back_into_set(run) -> None: # noqa: ANN001 + """The spec of ``show`` is the spec that ``set`` takes, with nothing added.""" + first = _document(run("--json", "route", "set", "Alice", "--path", "b2,a1")) + assert first["path"] == "b2,a1" + again = _document(run("--json", "route", "set", "Alice", "--path", first["path"])) + assert again["path"] == first["path"] + + +@pytest.mark.parametrize("spec", ["zz", "a1,a1", "a", ",,x"], ids=["not-hex", "twice", "odd", "x"]) +def test_a_bad_spec_is_a_usage_error(run, spec) -> None: # noqa: ANN001 + """A spec that is not hops in hex is refused before the radio is touched.""" + result = run("route", "set", "Alice", "--path", spec) + assert result.exit_code == exitcodes.USAGE + assert result.stdout == "" + assert "is not a route" in result.stderr + + +def test_a_route_that_the_radio_cannot_hold_is_a_usage_error(run) -> None: # noqa: ANN001 + """65 hops of one byte do not fit in 64 bytes. Nothing was written, so it is not exit 4.""" + spec = ",".join(f"{i:02x}" for i in range(65)) + result = run("route", "set", "Alice", "--path", spec) + assert result.exit_code == exitcodes.USAGE + assert result.stdout == "" + + +def test_set_needs_a_path(run) -> None: # noqa: ANN001 + """The route is the point of the command.""" + assert run("route", "set", "Alice").exit_code == exitcodes.USAGE + + +def test_forget_without_yes_is_a_silent_usage_error(run) -> None: # noqa: ANN001 + """It clears what the radio holds, so it asks for the usual confirmation.""" + result = run("route", "forget", "Alice") + assert result.exit_code == exitcodes.USAGE + assert result.stdout == "" + assert "--yes" in result.stderr + + +def test_forget_makes_the_next_message_flood(run) -> None: # noqa: ANN001 + """After a forget, there is no route: ``null`` in JSON, and the origin is ``flood``.""" + result = run("--json", "route", "forget", "Alice", "--yes") + assert result.exit_code == exitcodes.OK, result.output + document = _document(result) + assert document["path"] is None + assert document["route"] is None + assert document["origin"] == "flood" + plain = _facts(run("route", "forget", "Alice", "--yes")) + assert plain["path"] == "-" and plain["origin"] == "flood" + + +# -- keep and unkeep --------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "args", + [ + ("keep", "Alice", "--path", "a1"), + ("keep", "Alice"), + ("set", "Alice", "--path", "a1", "--keep"), + ], + ids=["keep-path", "keep-radio-route", "set-keep"], +) +def test_keep_without_a_site_fails_and_names_the_way_out(run, tmp_path, args) -> None: # noqa: ANN001 + """No site and no fixed device: exit 1, a sentence on stderr, nothing on stdout.""" + result = run("route", *args) + assert result.exit_code == exitcodes.FAILURE + assert result.stdout == "" + assert "meshterm outbound use" in result.stderr + machine = run("--json", "route", *args) + assert machine.exit_code == exitcodes.FAILURE + assert machine.stdout == "" + stored = tmp_path / "home" / "outbound.json" + assert not stored.exists() or "d4e5f6a7" not in stored.read_text(encoding="utf-8") + + +def test_keep_remembers_the_route_for_the_active_site(run, with_site) -> None: # noqa: ANN001 + """The route is kept for Home, and the next run shows it.""" + result = run("route", "keep", "Alice", "--path", "a1") + assert result.exit_code == exitcodes.OK, result.output + assert "Home" in result.stderr + document = _document(run("--json", "route", "show", "Alice")) + assert document["kept"] == "a1" + assert document["kept_by"] == {"source": "site", "name": "Home"} + assert document["kept_in_radio"] is True + assert document["skipped"] is False + assert document["origin"] == "kept" + plain = _facts(run("route", "show", "Alice")) + assert plain["kept_by"] == "site Home" + + +def test_keep_with_no_path_keeps_the_route_the_radio_holds(run, with_site) -> None: # noqa: ANN001 + """The simulator holds ``a1b2c3d4`` for Alice, and that route is kept as it stands.""" + assert run("route", "keep", "Alice").exit_code == exitcodes.OK + assert _document(run("--json", "route", "show", "Alice"))["kept"] == "a1b2c3d4" + + +def test_keep_with_no_path_and_no_route_is_a_usage_error(run, with_site, flooding) -> None: # noqa: ANN001 + """There is nothing to keep, so the user must give a path.""" + result = run("route", "keep", "Alice") + assert result.exit_code == exitcodes.USAGE + assert result.stdout == "" + assert "--path" in result.stderr + + +def test_set_with_keep_writes_and_keeps(run, with_site) -> None: # noqa: ANN001 + """One command does both: the radio gets the route and the site keeps it.""" + result = run("--json", "route", "set", "Observer-Bot", "--path", "b2", "--keep") + assert result.exit_code == exitcodes.OK, result.output + document = _document(result) + assert document["path"] == "b2" and document["kept"] == "b2" + listed = _document(run("--json", "route", "list")) + kept = {row["node"]["name"]: row["kept"] for row in listed} + assert kept["Observer-Bot"] == "b2" and kept["Alice"] is None + + +def test_a_kept_route_with_no_relay_stays_empty(run, with_site) -> None: # noqa: ANN001 + """A kept neighbour route is ``""`` and not an absent route.""" + assert run("route", "keep", "Alice", "--path", "").exit_code == exitcodes.OK + document = _document(run("--json", "route", "show", "Alice")) + assert document["kept"] == "" + assert _facts(run("route", "show", "Alice"))["kept"] == "direct" + + +def test_a_kept_route_that_is_not_on_the_radio_is_listed(run, with_site, flooding) -> None: # noqa: ANN001 + """A contact with a kept route is in the list when the radio holds no route to it.""" + assert run("route", "keep", "Alice", "--path", "a1").exit_code == exitcodes.OK + rows = _document(run("--json", "route", "list")) + assert [row["node"]["name"] for row in rows] == ["Alice"] + assert rows[0]["path"] is None and rows[0]["kept"] == "a1" + assert rows[0]["origin"] == "flood" + + +def test_forget_leaves_the_kept_route_kept(run, with_site) -> None: # noqa: ANN001 + """The user forgets what the radio holds, and not the choice.""" + run("route", "keep", "Alice", "--path", "a1") + result = run("--json", "route", "forget", "Alice", "--yes") + document = _document(result) + assert document["path"] is None and document["kept"] == "a1" + assert "stays kept" in result.stderr + + +def test_unkeep_drops_the_kept_route(run, with_site) -> None: # noqa: ANN001 + """The route stays in the radio. Only the memory is gone.""" + run("route", "keep", "Alice", "--path", "a1") + result = run("--json", "route", "unkeep", "Alice") + assert result.exit_code == exitcodes.OK, result.output + assert _document(result)["kept"] is None + assert _document(run("--json", "route", "show", "Alice"))["kept"] is None + + +def test_unkeep_of_nothing_is_nothing_to_report(run, with_site) -> None: # noqa: ANN001 + """No route was kept: exit status 5, and the document is still printed.""" + plain = run("route", "unkeep", "Alice") + assert plain.exit_code == exitcodes.NO_RESULT + machine = run("--json", "route", "unkeep", "Alice") + assert machine.exit_code == exitcodes.NO_RESULT + assert _document(machine)["kept"] is None + + +# -- discover ---------------------------------------------------------------------------- + + +def test_discover_shows_the_route_each_way(run) -> None: # noqa: ANN001 + """The answer has both specs and both drawn routes. The back route ends at our node.""" + result = run("route", "discover", "Alice") + assert result.exit_code == exitcodes.OK, result.output + facts = _facts(result) + assert facts["answered"] == "yes" and facts["used"] == "no" + assert facts["out_path"] and facts["in_path"] + assert facts["out_route"].startswith("MockCompanion") + assert facts["in_route"].startswith("Alice") + document = _document(run("--json", "route", "discover", "Alice")) + assert document["answered"] is True and document["used"] is False + assert document["in_route"][0]["name"] == "Alice" + assert document["in_route"][-1]["self"] is True + + +def test_discover_does_not_change_the_route_unless_asked(run) -> None: # noqa: ANN001 + """Without ``--use``, no route is written. With it, the outward route is set.""" + plain = run("--json", "route", "discover", "Alice") + assert "set to" not in plain.stderr + used = run("--json", "route", "discover", "Alice", "--use") + assert used.exit_code == exitcodes.OK, used.output + assert _document(used)["used"] is True + assert "outward route" in used.stderr + + +def test_discover_without_an_answer_is_nothing_to_report( + run, # noqa: ANN001 + monkeypatch: pytest.MonkeyPatch, +) -> None: + """The discovery went out and nothing came back: exit status 5, nulls in the document.""" + + async def silent(self, node): # noqa: ANN001, ANN202 + return None + + monkeypatch.setattr(MockDevice, "discover_route", silent) + plain = run("route", "discover", "Alice", "--use") + assert plain.exit_code == exitcodes.NO_RESULT + machine = run("--json", "route", "discover", "Alice", "--use") + assert machine.exit_code == exitcodes.NO_RESULT + document = _document(machine) + assert document["answered"] is False and document["used"] is False + assert document["out_path"] is None and document["out_route"] is None + + +# -- sync -------------------------------------------------------------------------------- + + +def test_sync_with_nothing_to_do_says_so(run) -> None: # noqa: ANN001 + """Every count is zero, and the document has every key.""" + result = run("--json", "route", "sync") + assert result.exit_code == exitcodes.OK, result.output + assert _document(result) == { + "site": None, + "saved": [], + "restored": 0, + "kept_written": 0, + "kept_skipped": [], + "failed": [], + } + assert "in line" in result.stderr + + +def test_sync_writes_a_kept_route_the_radio_lost(run, with_site) -> None: # noqa: ANN001 + """The simulator starts each run with its own routes. A kept route that differs is written.""" + assert run("route", "keep", "Alice", "--path", "b2").exit_code == exitcodes.OK + result = run("--json", "route", "sync") + assert result.exit_code == exitcodes.OK, result.output + document = _document(result) + assert document["site"] == "Home" and document["kept_written"] == 1 + assert "Wrote back 1 route you keep" in result.stderr + assert _facts(run("route", "sync"))["site"] == "Home" + + +# -- the tool itself --------------------------------------------------------------------- + + +def test_the_tool_has_no_menu_row() -> None: + """The menu works on a route from the node page of the contact.""" + from meshterm.tools import get_tool + + tool = get_tool("route") + assert tool is not None and tool.menu_visible is False