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:
1 parent
88d0d94ca7
commit
8260ab057e
3 files changed
+1230
No files matched your search
@@ -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
|
||||
|
||||
@@ -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),
|
||||
},
|
||||
)
|
||||
@@ -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
|
||||
Reference in new issue
Block a user