diff --git a/docs/cli/README.md b/docs/cli/README.md index bb88bd5..3db81ab 100644 --- a/docs/cli/README.md +++ b/docs/cli/README.md @@ -1676,7 +1676,10 @@ row has no column here, because `optimal_tx_dbm` names the winner. If no password is available and MeshTerm cannot ask for one, this is a **usage error** (`2`), and nothing was transmitted. If the node refuses the password, this is a device -error (`4`), and MeshTerm clears the saved password. The command returns `5` when no +error (`4`), and MeshTerm clears the saved password. A stock node does not answer a wrong +password. Thus, if the owner of the node changed its password, the login gets no reply, and +the command fails with `4`. Then give the new password one time with `--password`: a +password that the node accepts replaces the saved one. The command returns `5` when no trace reached the target at any level. In this case MeshTerm measured nothing, and the node stays at its original power. @@ -1708,9 +1711,12 @@ with the echoed prompt. A node that does not answer is not a failure, because th can have arrived. But there is nothing to report, so the command returns `5`. MeshTerm logs in automatically with the remembered password. To store a password, run -the interactive flow one time, or give `--password`. If the node refuses the login, -MeshTerm clears the saved password, and the command fails with `4`. The node answered, -and the answer was no. A password that is **absent**, and a node name that no contact +the interactive flow one time, or give `--password`. A password that the node accepts +replaces the remembered one. A stock node does not answer a wrong password. Thus, after the +owner of the node changes its password, the login gets no reply, and the command fails with +`4`. Then give the new password one time with `--password`. If the node refuses the login +(firmware other than stock MeshCore can do this), MeshTerm clears the saved password, and +the command fails with `4`. A password that is **absent**, and a node name that no contact matches, are usage errors (`2`). In both cases nothing was transmitted. This is the line between these errors and the errors `3` and `4`. diff --git a/meshterm/tools/repeater_admin.py b/meshterm/tools/repeater_admin.py index ef0af64..c3011db 100644 --- a/meshterm/tools/repeater_admin.py +++ b/meshterm/tools/repeater_admin.py @@ -28,6 +28,7 @@ from ..context import AppContext from ..core import exitcodes from ..core.connection import DeviceCommandError from ..core.models import NODE_TYPE_LABELS, Contact, LoginResult +from ..ui.admin_login import no_reply_error from .base import Tool, ToolResult, register if TYPE_CHECKING: # pragma: no cover - typing only @@ -84,6 +85,7 @@ class RepeaterAdminTool(Tool): if node is None: raise typer.BadParameter(f"unknown contact: {name!r}") + saved = not params.get("password") password = params.get("password") or ctx.admin_store.get(node) if not password: raise typer.BadParameter( @@ -97,10 +99,7 @@ class RepeaterAdminTool(Tool): f"admin login to {name!r} failed (wrong password?). The saved password was cleared." ) if not outcome: - raise DeviceCommandError( - f"{name!r} did not answer the admin login — it may be out of reach, " - "asleep, or busy. Any saved password was kept; try again when it answers." - ) + raise DeviceCommandError(no_reply_error(name, saved=saved, again="run again")) command = str(params["command"]) ctx.remote_store.append_history(node, command) diff --git a/meshterm/tools/tx_optimize.py b/meshterm/tools/tx_optimize.py index 33d7d68..2bb3ab1 100644 --- a/meshterm/tools/tx_optimize.py +++ b/meshterm/tools/tx_optimize.py @@ -224,9 +224,13 @@ class TxOptimizeTool(Tool): DeviceCommandError: If the node refused the login. MeshTerm then forgets the stored password, because it is known to be bad, and the next run asks again. Also if the node never answered. Then the password is not tested, - and MeshTerm keeps it. + and MeshTerm keeps it. A stock node does not answer a wrong password, so + the error tells the user to give a changed password with ``--password``. """ + from ..ui.admin_login import no_reply_error + device = await ctx.device() + saved = not params.get("password") and ctx.admin_store.get(admin_node) is not None password = await self._resolve_password(ctx, admin_node, params) outcome = await device.admin_login(admin_node, password) ctx.admin_store.record(admin_node, password, outcome) @@ -236,10 +240,7 @@ class TxOptimizeTool(Tool): "The saved password was cleared; re-run to enter a new one." ) if not outcome: - raise DeviceCommandError( - f"{admin_node.name!r} did not answer the admin login — it may be out of " - "reach or asleep. The saved password was kept; re-run when it answers." - ) + raise DeviceCommandError(no_reply_error(admin_node.name, saved=saved, again="re-run")) # -- scripted (CLI) --------------------------------------------------------------- diff --git a/meshterm/ui/admin_login.py b/meshterm/ui/admin_login.py index 54278a7..fba8712 100644 --- a/meshterm/ui/admin_login.py +++ b/meshterm/ui/admin_login.py @@ -20,6 +20,9 @@ Thus, when a stored password gets no reply, the flow asks the user: ``Cancel``, ``New password…``. The second button opens the password prompt. The new password replaces the stored one only when the node accepts it. Thus a node that is down keeps its password, and a node whose password changed gets the new one in one step. + +The CLI cannot ask. Its error for the same silence says how to give the new password +(:func:`no_reply_error`). """ from __future__ import annotations @@ -100,6 +103,31 @@ def no_reply_text(node: Contact, *, again: str) -> str: ) +def no_reply_error(name: str, *, saved: bool, again: str) -> str: + """The error of a CLI command whose admin login got no reply. + + A scripted run cannot offer a new password, so the error says how to give one. A + password that the node accepts replaces the stored one, so ``--password`` with the new + password repairs a stale password in one run. + + Args: + name: The name of the node. + saved: The password came from the admin store. Then the store kept it, and a + changed password is a probable cause. + again: The words for a new run (``"run again"``, ``"re-run"``). + """ + lead = f"{name!r} did not answer the admin login — it may be out of reach, asleep, or busy" + if saved: + return ( + f"{lead}, or its password changed: a node does not answer a wrong password. " + f"The saved password was kept; if the password changed, {again} with --password." + ) + return ( + f"{lead}, or the password is wrong: a node does not answer a wrong password. " + "Any saved password was kept." + ) + + async def offer_new_password(ctx: AppContext, node: Contact) -> bool: """Ask what to do after a stored password got no reply: stop, or type a new password. diff --git a/tests/test_admin_login.py b/tests/test_admin_login.py index ffeb688..5b13245 100644 --- a/tests/test_admin_login.py +++ b/tests/test_admin_login.py @@ -472,6 +472,47 @@ async def test_the_scripted_tool_keeps_the_password_when_the_node_is_down(ctx) - assert ctx.admin_store.get(node) == "admin" +async def test_the_scripted_tool_says_how_to_give_a_changed_password(ctx) -> None: # noqa: ANN001 + """A script cannot get a "New password…" offer, so the error names ``--password``.""" + from meshterm.tools.repeater_admin import RepeaterAdminTool + + node = await _mock_node(ctx, down=True) + + with pytest.raises(DeviceCommandError) as raised: + await RepeaterAdminTool().run(ctx, {"node": node.name, "command": "get tx"}) + + message = str(raised.value) + assert "its password changed" in message + assert "if the password changed, run again with --password" in message + + +async def test_an_explicit_password_with_no_reply_names_no_flag(ctx) -> None: # noqa: ANN001 + """The user already gave ``--password``. The error says that it can be wrong, and no more.""" + from meshterm.tools.repeater_admin import RepeaterAdminTool + + node = await _mock_node(ctx, down=True) + + with pytest.raises(DeviceCommandError) as raised: + await RepeaterAdminTool().run( + ctx, {"node": node.name, "command": "get tx", "password": "typed"} + ) + + message = str(raised.value) + assert "the password is wrong" in message and "Any saved password was kept." in message + assert "--password" not in message + assert ctx.admin_store.get(node) == "admin" + + +async def test_the_tx_optimizer_says_how_to_give_a_changed_password(ctx) -> None: # noqa: ANN001 + """The same advice from the other scripted login, in its own words for a new run.""" + from meshterm.tools.tx_optimize import TxOptimizeTool + + node = await _mock_node(ctx, down=True) + + with pytest.raises(DeviceCommandError, match="re-run with --password"): + await TxOptimizeTool()._login(ctx, node, {}) + + async def test_the_scripted_tool_clears_the_password_the_node_rejected(ctx) -> None: # noqa: ANN001 """The other half: a node that is reachable and says no has a bad password.""" from meshterm.tools.repeater_admin import RepeaterAdminTool