The route command lists, sets, keeps, and discovers the device routes

meshterm route works on the route that the radio holds to each contact,
with a plain face and a --json face. It has no menu row: the menu works
on a route from the node page of the contact.

- list and show: the spec, the origin (kept, set, learned, flood), the
  kept spec, where it is kept (site or fixed device), the drawn route
  from our node to the contact, and a kept route skipped because its
  first hop is silent.
- set (--keep), forget (--yes), keep, unkeep: each prints the route as
  it is afterwards. keep without a site fails with exit 1 and names
  meshterm outbound use.
- discover (--use): one path discovery, the route each way.
- sync: the reconcile of the connection, with its counts.

Refs: #34

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5.5 committed 2026-11-08 00:25:32 -05:00
1 parent 88d0d94ca7
commit 8260ab057e
3 files changed
+1230

No files matched your search

+106
View File
@@ -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 <site>`.
`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
+716
View File
@@ -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 <site>`, "
"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),
},
)
+408
View File
@@ -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