services/dashboards
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(ups): offer every advertised command and gate its aliases too

Browse Source 
Two halves of the same bug: the page offered less than the hardware does, and the gate
matched only the name it rendered.

`available_commands()` drops anything `COMMANDS.get()` misses, and 12 of the 23 commands
the two real UPSes advertise had no entry (`beeper.on/off`, `load.on/off.delay`,
`shutdown.default/reboot/stayoff`, `driver.reload*`, `driver.killpower`,
`test.panel.stop`) — an invisible button the operator had no way to learn about. Every one
is catalogued now with a risk tier, and the power-cutting ones are pinned to
`RISK_DANGEROUS` (`shutdown.stop` is the exception the name hides: it cancels a shutdown).

Both real drivers advertise `beeper.enable` *and* `beeper.on`, `beeper.disable` *and*
`beeper.off`, so rendering every advertised name drew "Beeper on" twice. `COMMAND_ALIASES`
collapses one action to one entry (named for a name this driver answers, so a driver that
only implements the alias still gets its button) and records the other names in `also`.

The POST gate resolved the request through that table instead of comparing the literal
string: previously `beeper.off` walked past a `disabled` verdict recorded against
`beeper.disable` — the same action, and the gate is the control, not the button.

LLM-Generated: true
This commit is contained in:
ducoterra
2026-10-17 12:27:02 -04:00
parent 1f20a5e57f
commit 9041683179
3 changed files with 193 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/dashboards/api.py
+6 -3
View File
@@ -446,9 +446,12 @@ def ups_router() -> APIRouter:
if advice["risk"] == nut.RISK_DANGEROUS and confirm != "DANGER":
raise HTTPException(422, f"{advice['label']} can cut power: send "
f"confirm=\"DANGER\" to prove you read the warning")
if any(item["command"] == command and not item["enabled"] for item in card["commands"]):
blocked = next(item for item in card["commands"] if item["command"] == command)
raise HTTPException(409, blocked["reason"] or f"{command} is not available")
# Resolved through the alias table: `beeper.off` and `beeper.disable` are one action,
# and only one of them is listed. Matching the literal name would let the unlisted
# alias past a `disabled` verdict — on battery, that is a power cut with a typo.
entry = nut.resolve_command(card["commands"], command)
if entry is not None and not entry["enabled"]:
raise HTTPException(409, entry["reason"] or f"{command} is not available")
try:
if monitor.simulated:
src/dashboards/sources/nut.py
+86
View File
@@ -675,6 +675,8 @@ COMMANDS: dict[str, dict[str, str]] = {
"help": "Aborts a running battery test and returns to line power."},
"test.panel.start": {"label": "Panel test", "risk": RISK_SAFE,
"help": "Lights and beeps the front panel for a few seconds."},
"test.panel.stop": {"label": "Stop panel test", "risk": RISK_SAFE,
"help": "Ends a front-panel test."},
"test.system.start": {"label": "Full system self-test", "risk": RISK_CAUTION,
"help": "Vendor self-test; behaviour varies by model and may move "
"the load to battery."},
@@ -682,6 +684,12 @@ COMMANDS: dict[str, dict[str, str]] = {
"beeper.disable": {"label": "Beeper off", "risk": RISK_SAFE,
"help": "Silences audible alarms. Faults are still reported in this dashboard."},
"beeper.mute": {"label": "Beeper mute", "risk": RISK_SAFE, "help": "Silence the current alarm only."},
# `beeper.on`/`beeper.off` are what the APC and CyberPower drivers actually advertise;
# `beeper.enable`/`beeper.disable` are the names other drivers use. Both pairs are real,
# so both are catalogued — a command the driver offers must never go missing from the page.
"beeper.on": {"label": "Beeper on", "risk": RISK_SAFE, "help": "Re-enable audible alarms."},
"beeper.off": {"label": "Beeper off", "risk": RISK_SAFE,
"help": "Silences audible alarms. Faults are still reported in this dashboard."},
"calibrate.start": {
"label": "Start calibration",
"risk": RISK_DANGEROUS,
@@ -693,8 +701,15 @@ COMMANDS: dict[str, dict[str, str]] = {
"help": "Clears the recorded input voltage extremes."},
"load.on": {"label": "Energise output", "risk": RISK_CAUTION,
"help": "Turns the outlets on."},
"load.on.delay": {"label": "Energise output after delay", "risk": RISK_CAUTION,
"help": "Turns the outlets on after the driver's shutdown delay. "
"Cancels a pending power-down on some models."},
"load.off": {"label": "Cut output power", "risk": RISK_DANGEROUS,
"help": "Kills power to everything plugged in, immediately, on battery or not."},
"load.off.delay": {"label": "Cut output power after delay", "risk": RISK_DANGEROUS,
"help": "Cuts outlet power after the driver's shutdown delay. Attached "
"systems are not asked to shut down first — this is a hard cut "
"on a timer."},
"load.reboot": {"label": "Power-cycle outlets", "risk": RISK_DANGEROUS,
"help": "Cuts and restores output power. Everything attached reboots."},
"shutdown.return": {"label": "Graceful shutdown, then restore", "risk": RISK_DANGEROUS,
@@ -704,6 +719,32 @@ COMMANDS: dict[str, dict[str, str]] = {
"help": "Shuts attached systems down and stays off."},
"shutdown.stop": {"label": "Cancel shutdown", "risk": RISK_SAFE,
"help": "Aborts a pending shutdown sequence."},
"shutdown.stayoff": {"label": "Shut down and stay off", "risk": RISK_DANGEROUS,
"help": "Cuts output power after the delay and does not bring it back "
"when utility returns."},
"shutdown.default": {"label": "Default shutdown sequence", "risk": RISK_DANGEROUS,
"help": "The driver's own shutdown sequence — usually the same as "
"shutdown.return, but the order and timing are the driver's "
"choice, not yours."},
"shutdown.reboot": {"label": "Shut down, then power-cycle", "risk": RISK_DANGEROUS,
"help": "Shuts attached systems down, cuts power, and restores it after "
"the delay. Everything attached comes back on its own."},
# Driver-level commands. `driver.reload` re-reads the driver's configuration; it interrupts
# status reporting for a moment but leaves the load alone. `driver.killpower` does not.
"driver.reload": {"label": "Reload driver config", "risk": RISK_CAUTION,
"help": "Makes the driver re-read ups.conf. Status reporting blips for a "
"few seconds; output power is unaffected."},
"driver.reload-or-error": {"label": "Reload config, exit on error", "risk": RISK_CAUTION,
"help": "Reloads the driver configuration and stops the driver if "
"it is invalid — this UPS then stops reporting until it is "
"started again."},
"driver.reload-or-exit": {"label": "Reload config, or exit", "risk": RISK_CAUTION,
"help": "Reloads the driver configuration, exiting if the reload "
"cannot be done."},
"driver.killpower": {"label": "Kill power now", "risk": RISK_DANGEROUS,
"help": "Cuts inverter output immediately with no shutdown sequencing "
"and no delay — the fastest way to take everything attached "
"down hard."},
}
@@ -711,6 +752,39 @@ def command_advice(command: str) -> dict[str, str] | None:
return COMMANDS.get(command)
# Driver names that mean the same action. Both real drivers advertise `beeper.enable` AND
# `beeper.on`, and `beeper.disable` AND `beeper.off`, so offering every advertised command
# drew "Beeper on" and "Beeper off" twice each. Both names stay in `COMMANDS` — a driver that
# offers only one of them must still get a button — but one action gets one entry, named for a
# name this driver actually answers, in the preference order below.
COMMAND_ALIASES: tuple[tuple[str, ...], ...] = (
("beeper.enable", "beeper.on"),
("beeper.disable", "beeper.off"),
)
def alias_group(command: str) -> tuple[str, ...]:
"""Every driver name for the same action, preferred first. Just itself if not an alias."""
for group in COMMAND_ALIASES:
if command in group:
return group
return (command,)
def resolve_command(commands: list[dict[str, Any]], command: str) -> dict[str, Any] | None:
"""The offered entry a command name refers to, aliases included.
The POST gate compares the request against the command list. Matching on `command` alone
would let an alias the page never rendered (`beeper.off`) walk past a `disabled` verdict
recorded against the name the page did render (`beeper.disable`) — the same action, and
the gate is the control, not the button.
"""
for item in commands:
if item["command"] == command or command in (item.get("also") or []):
return item
return None
def available_commands(advertised: list[str], *, allow_actions: bool,
read_only: bool, has_credentials: bool,
on_battery: bool = False) -> list[dict[str, Any]]:
@@ -718,12 +792,21 @@ def available_commands(advertised: list[str], *, allow_actions: bool,
Filtering server-side (not just hiding buttons) is the point: the response says
`enabled: false` plus `reason`, so the page never offers a button that 403s.
One entry per *action*: where a driver advertises both names of an alias group, the
preferred name is emitted and the others ride along in `also`, so the page cannot draw the
same button twice while `resolve_command()` still refuses the alias when the action is off.
"""
out: list[dict[str, Any]] = []
advertised_set = set(advertised)
for name in advertised:
advice = COMMANDS.get(name)
if advice is None:
continue
group = alias_group(name)
preferred = next(candidate for candidate in group if candidate in advertised_set)
if name != preferred:
continue # already represented by the preferred name of this action
reason = None
if read_only:
reason = "the server is in DASH_READ_ONLY mode"
@@ -741,6 +824,9 @@ def available_commands(advertised: list[str], *, allow_actions: bool,
"enabled": reason is None,
"reason": reason,
"confirm_text": None if advice["risk"] != RISK_DANGEROUS else "DANGER",
# other names this driver answers for the same action; the page shows one button,
# and POSTing any of them hits this same entry's verdict
"also": [other for other in advertised if other in group and other != name],
})
order = {RISK_SAFE: 0, RISK_CAUTION: 1, RISK_DANGEROUS: 2}
out.sort(key=lambda item: (order[item["risk"]], item["label"]))