From 4c81c2e0b420b17b71a8b4911d8e9dbfd9fc0a60 Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Thu, 19 Nov 2026 16:48:19 -0600 Subject: [PATCH 1/5] Sync the error catalog and feature table from benchpod-firmware#191 The catalog gains BP0030 client_too_old; features.json gains api and min_client_api. Co-Authored-By: Claude Opus 5.5 --- internal/errcatalog/errors.json | 78 ++++++++++++++++++++------------- internal/features/features.json | 78 ++++++++++++++++++--------------- 2 files changed, 91 insertions(+), 65 deletions(-) diff --git a/internal/errcatalog/errors.json b/internal/errcatalog/errors.json index 80fe3a0..9549d8d 100644 --- a/internal/errcatalog/errors.json +++ b/internal/errcatalog/errors.json @@ -1,13 +1,13 @@ { "_generated": "GENERATED by tools/gen_errors.py from errors/catalog.toml. DO NOT EDIT: edit the catalog.", "version": 1, - "catalog_sha256": "ef614af22c086dc10994ecb05d7148b8f27cf1483a34bc3309a39e5ef9768550", + "catalog_sha256": "1fdf57bcda663e4e263d034fc81e30b23d565347daafb03b09b5cd7d7e63a332", "docs_url": "https://embeddedci.com/docs/errors#{code}", "codes": { "BP0001": { "name": "la_voltage_not_set", "area": "io", - "since": "next", + "since": "3.10.8", "message": "The I/O voltage is not set", "cause": "The pod starts with its I/O voltage unset and never picks one on its own, so it cannot drive a board at a voltage the board does not take. Anything that uses the LA pins (UART, flashing, captures, GPIO, I2C, SPI, sensor emulation) needs it first.", "args": {}, @@ -21,7 +21,7 @@ "BP0002": { "name": "unknown_command", "area": "protocol", - "since": "next", + "since": "3.10.8", "message": "The pod does not know the command {cmd}", "cause": "The firmware on the pod is older than the tool that sent the command, or the command name is wrong. Newer SDK, CLI and MCP versions check the pod's capabilities first and say which firmware a feature needs.", "args": { @@ -37,7 +37,7 @@ "BP0003": { "name": "i2c_session_open", "area": "i2c", - "since": "next", + "since": "3.10.8", "message": "An I2C session is already open", "cause": "The pod runs one I2C master session at a time.", "args": {}, @@ -51,7 +51,7 @@ "BP0004": { "name": "spi_session_open", "area": "spi", - "since": "next", + "since": "3.10.8", "message": "An SPI session is already open", "cause": "The pod runs one SPI master session at a time.", "args": {}, @@ -65,7 +65,7 @@ "BP0005": { "name": "bus_engine_busy", "area": "spi", - "since": "next", + "since": "3.10.8", "message": "The engine that runs SWD, SPI and I2C is in use, so {want} cannot start", "cause": "Flashing (SWD), the SPI master and the I2C master share one engine on the pod. While one of them runs, the other two wait.", "args": { @@ -81,7 +81,7 @@ "BP0006": { "name": "missing_argument", "area": "protocol", - "since": "next", + "since": "3.10.8", "message": "The request is missing {arg}", "cause": "A required value was not sent. The SDK, CLI and MCP always send it, so this usually means a hand-written protocol request or a tool older than the firmware.", "args": { @@ -97,7 +97,7 @@ "BP0007": { "name": "wiring_profile_not_found", "area": "wiring", - "since": "next", + "since": "3.10.8", "message": "The pod has no wiring profile named {name}", "cause": "Wiring profiles live on the pod. This one was never saved there, was deleted, or was saved on another pod.", "args": { @@ -113,7 +113,7 @@ "BP0008": { "name": "wiring_bad_name", "area": "wiring", - "since": "next", + "since": "3.10.8", "message": "{name} is not a valid wiring profile name", "cause": "Profile names are 1 to 40 characters: lowercase letters, digits and dashes, not starting with a dash.", "args": { @@ -129,7 +129,7 @@ "BP0009": { "name": "wiring_revision_conflict", "area": "wiring", - "since": "next", + "since": "3.10.8", "message": "The wiring profile {name} changed since it was loaded (it is now at revision {rev})", "cause": "Someone saved {name} from another connection (the web app, another script or agent) after this one loaded it. Saving now would overwrite their change, so the pod refuses.", "args": { @@ -146,7 +146,7 @@ "BP0010": { "name": "wiring_store_full", "area": "wiring", - "since": "next", + "since": "3.10.8", "message": "The pod cannot hold another wiring profile (at most {max}, and 16 KB in all)", "cause": "Wiring profiles live on the pod, in a fixed amount of storage.", "args": { @@ -162,7 +162,7 @@ "BP0011": { "name": "wiring_profile_too_large", "area": "wiring", - "since": "next", + "since": "3.10.8", "message": "The wiring profile is {bytes} bytes; the pod takes at most {max}", "cause": "One wiring profile fits in {max} bytes of JSON. Long signal descriptions or many signals add up.", "args": { @@ -179,7 +179,7 @@ "BP0012": { "name": "wiring_not_json_object", "area": "wiring", - "since": "next", + "since": "3.10.8", "message": "The wiring profile is not one JSON object", "cause": "The pod stores a profile as the JSON object the tools send. This one is cut off or not an object, which points at a damaged upload or a hand-written request.", "args": {}, @@ -193,7 +193,7 @@ "BP0013": { "name": "wiring_delete_default", "area": "wiring", - "since": "next", + "since": "3.10.8", "message": "{name} is the pod's default wiring profile and cannot be deleted", "cause": "A connection that names no profile uses the default, so the pod always keeps one.", "args": { @@ -209,7 +209,7 @@ "BP0014": { "name": "wiring_upload_out_of_order", "area": "wiring", - "since": "next", + "since": "3.10.8", "message": "The wiring profile upload skipped ahead (the pod expected offset {expected})", "cause": "Profiles are sent to the pod in pieces, in order, starting at offset 0. A piece went missing or another upload started in between.", "args": { @@ -225,7 +225,7 @@ "BP0015": { "name": "wiring_storage_failed", "area": "wiring", - "since": "next", + "since": "3.10.8", "message": "The pod could not read or write its wiring profiles", "cause": "The flash chip that holds the profiles did not answer or a write did not verify. Profiles saved before are kept: a write never replaces them until it has been read back.", "args": {}, @@ -239,7 +239,7 @@ "BP0016": { "name": "storage_busy", "area": "wiring", - "since": "next", + "since": "3.10.8", "message": "The pod cannot save now: the DAC or a capture is using the bus the storage shares", "cause": "The flash chip that holds the wiring profiles shares a bus with the DAC replay and the captures. Saving would stop a running waveform, so the pod refuses instead. Reading profiles always works.", "args": {}, @@ -253,7 +253,7 @@ "BP0017": { "name": "gateware_too_old", "area": "firmware", - "since": "next", + "since": "3.10.11", "message": "{feature} needs gateware v{min} or later", "cause": "The pod's FPGA image is older than the feature. Firmware updates bring the matching gateware with them.", "args": { @@ -270,7 +270,7 @@ "BP0018": { "name": "uart_same_pin", "area": "uart", - "since": "next", + "since": "3.10.11", "message": "UART rx and tx are both LA{la}; a one-wire UART needs half_duplex", "cause": "A normal UART drives its TX pin all the time, so it cannot share the pin with RX. In half duplex the pod only pulls the line low and lets the pull-up hold it high, so both sides can talk on one wire.", "args": { @@ -286,7 +286,7 @@ "BP0019": { "name": "uart_half_duplex_two_pins", "area": "uart", - "since": "next", + "since": "3.10.11", "message": "half_duplex runs on one pin, but rx is LA{rx} and tx is LA{tx}", "cause": "In half duplex the pod sends and receives on the same wire, so rx and tx name the same LA channel.", "args": { @@ -303,7 +303,7 @@ "BP0020": { "name": "uart_entry_no_reset_pin", "area": "uart", - "since": "next", + "since": "3.10.11", "message": "The UART entry sequence needs the pod's reset pin, which this board does not have", "cause": "The entry sequence holds the target in reset with the pod's own reset pin while it holds TX low. Pods before v3 have no reset pin.", "args": {}, @@ -317,7 +317,7 @@ "BP0021": { "name": "uart_entry_invalid", "area": "uart", - "since": "next", + "since": "3.10.11", "message": "The UART entry option {arg} is out of range (0 to {max})", "cause": "The entry sequence times are milliseconds, each up to a limit, and the first bytes are at most a few dozen hex bytes.", "args": { @@ -334,7 +334,7 @@ "BP0022": { "name": "uart_de_pin", "area": "uart", - "since": "next", + "since": "3.10.11", "message": "The UART's DE pin LA{la} is also its rx or tx", "cause": "DE switches an RS-485 transceiver between sending and listening, so it is a wire of its own, from an LA channel to the transceiver's DE and /RE pins.", "args": { @@ -350,7 +350,7 @@ "BP0023": { "name": "la_no_pull", "area": "io", - "since": "next", + "since": "3.10.12", "message": "LA{la} has no pull resistor on this board", "cause": "Only some LA channels have a pull resistor the pod can switch, and which ones depends on the board. la_pins lists each channel's pull and the directions it supports.", "args": { @@ -366,7 +366,7 @@ "BP0024": { "name": "la_pull_direction", "area": "io", - "since": "next", + "since": "3.10.12", "message": "LA{la} supports pull-{have} only on this board", "cause": "The pull resistor on LA{la} is wired one way on this board, so it cannot pull {want}. Which way each channel pulls depends on the board; la_pins lists it.", "args": { @@ -384,7 +384,7 @@ "BP0025": { "name": "lease_busy", "area": "lease", - "since": "next", + "since": "3.10.13", "message": "{holder} holds this pod ({purpose}, {left_s} s left)", "cause": "Someone took the pod's lease (a CI run, an SDK or CLI session, or a cloud job). While it is held, only its owners may drive the pod; everyone else may still read status and other light reads. The lease ends when its owner releases it, when it is not renewed in time, or when the pod restarts.", "args": { @@ -402,7 +402,7 @@ "BP0026": { "name": "lease_lost", "area": "lease", - "since": "next", + "since": "3.10.13", "message": "The pod's lease was stopped by {by}", "cause": "This connection or this lease id owned the pod's lease, and {by} stopped it from the web app or the cloud. The command was not run. A connection that owned it hears this once. A command, lease_acquire or lease_renew that carries the stopped lease's id keeps getting it for 30 minutes, so a run that was stopped does not take the pod back; a new id gets a new lease.", "args": { @@ -418,7 +418,7 @@ "BP0027": { "name": "lease_not_held", "area": "lease", - "since": "next", + "since": "3.10.13", "message": "The pod holds no lease with id {id}", "cause": "lease_renew found no lease: it ran out (it was not renewed before its deadline), it was released, or the pod restarted, which clears it. A lease that was stopped answers BP0026 instead.", "args": { @@ -434,7 +434,7 @@ "BP0028": { "name": "vref_5v_missing", "area": "io", - "since": "next", + "since": "3.10.13", "message": "5 V did not come up on pin 21 ({mv} mV)", "cause": "In 5 V mode the pod switches pin 21, the rail every pull-up pulls to, to its USB supply. The pod measures pin 21 and found it below 4.3 V, so it went back to the previous I/O voltage. A weak USB supply, a hub without power, or a load on pin 21 causes it.", "args": { @@ -450,7 +450,7 @@ "BP0029": { "name": "pull_rail_down", "area": "io", - "since": "next", + "since": "3.10.13", "message": "pin 21 is down ({mv} mV): the pull resistors are off until it is back", "cause": "The pull resistors pull up to J1 pin 21. The pod measures pin 21 and found it down, so it holds both pull expanders off (with pin 21 down they would answer on the same address). Pin 21 is shorted, overloaded, or a DUT holds it down.", "args": { @@ -462,6 +462,24 @@ "mcp": "ask the user to check what is wired to J1 pin 21 (set_la_voltage with no voltage shows its state), then set the pull again", "web": "Pin 21 is down, so the pull resistors are off. Check what is wired to pin 21." } + }, + "BP0030": { + "name": "client_too_old", + "area": "protocol", + "since": "next", + "message": "This client is too old for the pod's firmware: it needs client API {min_client_api} or newer (this client sent {client_api})", + "cause": "The firmware on the pod changed a reply or a message in a way that clients built for client API {client_api} would misread, so it refuses their commands instead of giving them answers they get wrong. The firmware speaks client API {api} and takes {min_client_api} or newer. A client that sends no client_api counts as 0. status, diag, ping and lease_release still work.", + "args": { + "client_api": "int", + "min_client_api": "int", + "api": "int" + }, + "fix": { + "sdk": "update the SDK (pip install -U embeddedci), then run again", + "cli": "update the CLI (`brew upgrade --cask benchpod`, or the latest release from GitHub), then run the command again", + "mcp": "tell the user the BenchPod MCP server is too old for this pod's firmware; they can update it (run `uvx embeddedci-mcp@latest`, or pip install -U embeddedci-mcp; with the benchpod plugin, update the plugin), then reconnect", + "web": "Reload the page to get the latest web app." + } } } } diff --git a/internal/features/features.json b/internal/features/features.json index 7d42158..bbc5dbd 100644 --- a/internal/features/features.json +++ b/internal/features/features.json @@ -1,8 +1,10 @@ { "_generated": "GENERATED by tools/gen_features.py from features/features.toml. DO NOT EDIT: edit the table.", "schema": 1, - "revision": 7, - "table_sha256": "a6a88ef88c0925212fcfa41f87409572bc0210a9fd02f2f418fc2a50b86eba64", + "revision": 8, + "api": 1, + "min_client_api": 0, + "table_sha256": "02f6411c240dcbc0cedda72648ba8713eb498a9a878ecca7f9fc817a3da586b2", "floor": "3.9.2", "docs_base": "https://github.com/embeddedci-com/benchpod-firmware/blob/main/docs/", "facts": { @@ -140,35 +142,35 @@ "firmware": "3.9.2", "board": "any", "legacy_caps": "gpio", - "docs": "API.md#gpio" + "docs": "API.md#gpio--use-la-pins-as-gpio" }, "power": { "rev": 1, "firmware": "3.9.2", "board": "any", "legacy_caps": "power", - "docs": "API.md#power" + "docs": "API.md#target_power--enabledisable-a-target-power-efuse" }, "swd": { "rev": 1, "firmware": "3.9.2", "board": "any", "legacy_caps": "swd", - "docs": "API.md#swd" + "docs": "dap-over-tunnel.md" }, "uart": { "rev": 1, "firmware": "3.9.2", "board": "any", "legacy_caps": "uart", - "docs": "API.md#uart_proxy_start" + "docs": "API.md#uart_proxy_start--transparent-uart-bridge" }, "la": { "rev": 1, "firmware": "3.9.2", "board": "any", "legacy_caps": "la", - "docs": "API.md#la_capture" + "docs": "API.md#la_capture--deep-raw-logic-analyzer-capture" }, "analyzer": { "rev": 1, @@ -197,7 +199,7 @@ "board": "any", "legacy_caps": "ota", "legacy_frame": "ota", - "docs": "API.md#ota_begin" + "docs": "API.md#firmware-and-blob-updates-ota" }, "la_pins": { "rev": 1, @@ -205,7 +207,7 @@ "board": "any", "legacy_caps": "la_pins", "legacy_frame": "la_pins", - "docs": "API.md#la_pins" + "docs": "API.md#la_pins--report-every-la-pin" }, "power_profile": { "rev": 1, @@ -213,7 +215,7 @@ "board": "any", "legacy_caps": "power_profile", "legacy_frame": "power_profile", - "docs": "API.md#power_profile" + "docs": "API.md#power_profile--record-a-rail-current-profile" }, "capture_b64": { "rev": 1, @@ -221,7 +223,7 @@ "board": "any", "legacy_caps": "capture_b64", "legacy_frame": "capture_b64", - "docs": "API.md#capture" + "docs": "API.md#base64-samples-encb64" }, "blob_slots": { "rev": 1, @@ -235,7 +237,7 @@ "board": "any", "legacy_caps": "can", "legacy_frame": "can", - "docs": "API.md#can_config" + "docs": "API.md#can_config--bring-can-up" }, "ota_sig": { "rev": 1, @@ -290,14 +292,14 @@ "firmware": "3.9.2", "board": "any", "legacy_caps": "usb_net", - "docs": "API.md#usb_network" + "docs": "API.md#usb_network--the-usb-network-adapter-on-or-off" }, "usb_net_setting": { "rev": 1, "firmware": "3.9.2", "board": "any", "legacy_caps": "usb_net_setting", - "docs": "API.md#usb_network" + "docs": "API.md#usb_network--the-usb-network-adapter-on-or-off" }, "lan_tls": { "rev": 1, @@ -324,7 +326,7 @@ "board": "any", "legacy_caps": "sensors", "legacy_frame": "sensors", - "docs": "API.md#sensor_define" + "docs": "API.md#emulated-sensors" }, "sensors_format_1": { "rev": 1, @@ -337,7 +339,7 @@ "firmware": "3.10.4", "board": "any", "legacy_caps": "sensor_la_trigger", - "docs": "API.md#sensor_la" + "docs": "API.md#sensor_la--raw-i2c-bus-capture" }, "can_fd": { "rev": 1, @@ -345,20 +347,20 @@ "board": "any", "legacy_caps": "can_fd", "legacy_frame": "can_fd", - "docs": "API.md#can_config" + "docs": "API.md#can_config--bring-can-up" }, "la_dir": { "rev": 1, "firmware": "3.10.4", "board": "any", - "docs": "API.md#la_dir" + "docs": "API.md#la_dir--which-way-each-pins-dut-signal-goes" }, "wiring_store": { "rev": 1, "firmware": "3.10.8", "board": "any", "legacy_frame": "wiring_store", - "docs": "API.md#wiring_list" + "docs": "API.md#wiring-profiles-wiring_list-wiring_get-wiring_put-wiring_delete-wiring_default" }, "error_codes": { "rev": 1, @@ -390,7 +392,7 @@ "board": "any", "legacy_caps": "gpio_read", "legacy_frame": "gpio_read", - "docs": "API.md#gpio_get" + "docs": "API.md#3-read-the-live-levels" }, "capture_trigger": { "rev": 1, @@ -399,7 +401,7 @@ "board": "any", "legacy_caps": "capture_trigger", "legacy_frame": "capture_trigger", - "docs": "API.md#capture" + "docs": "API.md#capture-triggers" }, "spi_master": { "rev": 1, @@ -408,7 +410,7 @@ "board": "any", "legacy_caps": "spi_master", "legacy_frame": "spi_master", - "docs": "API.md#spi_xfer" + "docs": "API.md#spi-master-flash-an-spi-device" }, "spi_stream": { "rev": 1, @@ -417,7 +419,7 @@ "board": "any", "legacy_caps": "spi_stream", "legacy_frame": "spi_stream", - "docs": "API.md#spi_stream" + "docs": "API.md#spi_stream--send-a-staged-upload-in-one-cs-frame" }, "la_rate_48mhz": { "rev": 1, @@ -439,14 +441,14 @@ "firmware": "3.10.4", "gateware": 55, "board": "any", - "docs": "API.md#i2c_start" + "docs": "API.md#i2c-master" }, "spi_modes_1_2": { "rev": 1, "firmware": "3.10.4", "gateware": 55, "board": "any", - "docs": "API.md#spi_xfer" + "docs": "API.md#spi_xfer--raw-full-duplex-transfer" }, "uart_frame": { "rev": 1, @@ -455,7 +457,7 @@ "board": "any", "legacy_caps": "uart_frame", "legacy_frame": "uart_frame", - "docs": "API.md#uart_proxy_start" + "docs": "API.md#uart_proxy_start--transparent-uart-bridge" }, "uart_hd": { "rev": 1, @@ -473,7 +475,7 @@ "emu_image" ], "legacy_frame": "sensors_digital", - "docs": "API.md#sensor_start" + "docs": "API.md#sensor_start--start-an-instance" }, "scope": { "rev": 1, @@ -481,7 +483,7 @@ "board": "analog", "legacy_caps": "scope", "legacy_frame": "scope", - "docs": "API.md#capture" + "docs": "API.md#capture--adc-snapshot" }, "dac": { "rev": 1, @@ -489,7 +491,7 @@ "board": "analog", "legacy_caps": "dac", "legacy_frame": "dac", - "docs": "API.md#generate" + "docs": "API.md#generate--dac-waveform-output" }, "dac_dc": { "rev": 1, @@ -497,7 +499,7 @@ "board": "analog", "legacy_caps": "dac_dc", "legacy_frame": "dac_dc", - "docs": "API.md#dac_out" + "docs": "API.md#dac_out--route-an-output-path-and-set-a-calibrated-voltage" }, "dac_replay": { "rev": 1, @@ -505,7 +507,7 @@ "board": "analog", "legacy_caps": "dac_replay", "legacy_frame": "dac_replay", - "docs": "API.md#replay" + "docs": "API.md#replay--play-a-recorded-trace-out-the-dac" }, "signal_alias": { "rev": 1, @@ -529,7 +531,7 @@ ], "legacy_caps": "dac_deep_replay", "legacy_frame": "dac_deep_replay", - "docs": "API.md#replay" + "docs": "API.md#replay--play-a-recorded-trace-out-the-dac" }, "dac_control_loop": { "rev": 1, @@ -541,7 +543,7 @@ ], "legacy_caps": "dac_control_loop", "legacy_frame": "dac_control_loop", - "docs": "API.md#dac_loop" + "docs": "API.md#dac_control_loop--arm-the-closed-loop-dac" }, "dac_cotrig": { "rev": 1, @@ -573,7 +575,7 @@ "board": "analog", "legacy_caps": "dac_limits", "legacy_frame": "dac_limits", - "docs": "API.md#dac_limits" + "docs": "API.md#dac_limits--dac-output-limits-for-an-external-output-stage" }, "calibrate": { "rev": 1, @@ -581,7 +583,7 @@ "board": "analog", "legacy_caps": "calibrate", "legacy_frame": "calibrate", - "docs": "API.md#calibrate" + "docs": "API.md#calibrate--calibrate-the-adc-offset-on-the-current_in-input-j8" }, "current_out": { "rev": 1, @@ -696,6 +698,12 @@ "vref_out" ], "docs": "API.md#pull-resistors-on-digital-v3r4" + }, + "client_api": { + "rev": 8, + "firmware": "next", + "board": "any", + "docs": "API.md#client-compatibility" } } } From 8b728e8a73c08c4aaf10da0779c5ff1267ba942c Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Thu, 19 Nov 2026 16:54:44 -0600 Subject: [PATCH 2/5] Classify pod refusals by their error code One table in tcpclient maps every catalog code (BP0001-BP0030) to its refusal kind, so the exit code follows the code; a coded refusal's hint is the catalog's fix.cli. Text matching stays as the fallback for replies without a code, each match marked with the code that replaces it or "no code yet". The six "unknown cmd" checks (and four more) use one helper, isUnknownCommand (BP0002, else the text). The pinned lease_busy text is marked removed: firmware after 3.10.13 builds it from macros and sends BP0025 with it. Co-Authored-By: Claude Opus 5.5 --- README.md | 9 +++- cmd/benchpod-cli/adcrange.go | 2 +- cmd/benchpod-cli/adcrange_test.go | 10 ++-- cmd/benchpod-cli/blobs_target.go | 3 +- cmd/benchpod-cli/busmaster.go | 6 +-- cmd/benchpod-cli/ci_lease.go | 10 ++-- cmd/benchpod-cli/cloudcfg.go | 4 +- cmd/benchpod-cli/errors.go | 53 ++++++++++++++------ cmd/benchpod-cli/errors_test.go | 69 +++++++++++++++++++++++++ cmd/benchpod-cli/flash_esp.go | 2 +- cmd/benchpod-cli/lantls.go | 2 +- cmd/benchpod-cli/lavoltage.go | 2 +- cmd/benchpod-cli/lavoltage_test.go | 10 ++-- cmd/benchpod-cli/loglevel.go | 2 +- cmd/benchpod-cli/loglevel_test.go | 10 ++-- cmd/benchpod-cli/policy.go | 3 +- cmd/benchpod-cli/policy_test.go | 10 ++-- cmd/benchpod-cli/refusals_test.go | 10 +++- cmd/benchpod-cli/usbnetwork.go | 2 +- cmd/benchpod-cli/usbnetwork_test.go | 10 ++-- cmd/benchpod-cli/wiring.go | 5 +- internal/cloudpod/cloudpod_test.go | 13 +++++ internal/errcatalog/errcatalog.go | 11 ++++ internal/fwrefusals/refusals.json | 2 +- internal/tcpclient/codes_test.go | 78 +++++++++++++++++++++++++++++ internal/tcpclient/errors.go | 61 ++++++++++++++++++++-- internal/tcpclient/lease.go | 6 ++- 27 files changed, 340 insertions(+), 65 deletions(-) create mode 100644 internal/tcpclient/codes_test.go diff --git a/README.md b/README.md index c92f6ea..5871674 100644 --- a/README.md +++ b/README.md @@ -1042,7 +1042,14 @@ stderr with a `[benchpod]` prefix. `benchpod ci` has its own exit codes (a CI result, not a command's): see [Exit codes of `benchpod ci`](#exit-codes-of-benchpod-ci). -A refusal is printed word for word as the pod sent it. For a `locked:` (LAN policy), +Firmware 3.10.8 and later sends more and more refusals with a stable error code (`BP0001` and up). +The CLI then shows the code, what went wrong and what to run, from the error catalog it ships +with, plus a link to the code's page; `benchpod explain ` prints the whole entry. The +exit code follows the code: a session, the bus engine, the storage or a lease in use +(`BP0003`, `BP0004`, `BP0005`, `BP0016`, `BP0025`) is `4`, every other code `3`. + +A refusal without a code (older firmware, or one that has no code yet) is printed word for +word as the pod sent it. For a `locked:` (LAN policy), `busy:` (cloud lease) or `forbidden:` (missing role) refusal the CLI adds what to do next. So it does for `la voltage not set` (run `benchpod la voltage 3.3V` or 1.8V, or set it on the web app's Wiring tab) and for a `pin conflict: LA4 is in use by ...`, where the raw diff --git a/cmd/benchpod-cli/adcrange.go b/cmd/benchpod-cli/adcrange.go index 13ebd8c..b0a1c47 100644 --- a/cmd/benchpod-cli/adcrange.go +++ b/cmd/benchpod-cli/adcrange.go @@ -95,7 +95,7 @@ func adcRange(ctx context.Context, c podCommander, via, action, what string, out } data, err := c.Command(ctx, req) if err != nil { - if strings.Contains(err.Error(), "unknown cmd") { + if isUnknownCommand(err) { return errors.New(adcRangeMissing) } if pe, ok := tcpclient.AsPodError(err); ok { diff --git a/cmd/benchpod-cli/adcrange_test.go b/cmd/benchpod-cli/adcrange_test.go index 217c926..2059b89 100644 --- a/cmd/benchpod-cli/adcrange_test.go +++ b/cmd/benchpod-cli/adcrange_test.go @@ -66,9 +66,11 @@ func TestADCRangeSelfTest(t *testing.T) { } func TestADCRangeOnOlderFirmware(t *testing.T) { - addr, _ := fakeLANPod(t, `{"status":"error","message":"unknown cmd"}`) - err := runADCRange(&globalFlags{connection: addr}, "show", &bytes.Buffer{}) - if err == nil || !strings.Contains(err.Error(), "3.9.5 or later") { - t.Fatalf("err = %v", err) + for _, reply := range unknownCmdReplies { + addr, _ := fakeLANPod(t, reply) + err := runADCRange(&globalFlags{connection: addr}, "show", &bytes.Buffer{}) + if err == nil || !strings.Contains(err.Error(), "3.9.5 or later") { + t.Fatalf("err = %v", err) + } } } diff --git a/cmd/benchpod-cli/blobs_target.go b/cmd/benchpod-cli/blobs_target.go index a5f4ccd..fd56abf 100644 --- a/cmd/benchpod-cli/blobs_target.go +++ b/cmd/benchpod-cli/blobs_target.go @@ -13,7 +13,6 @@ import ( "time" "github.com/embeddedci-com/benchpod-cli/internal/serialconsole" - "github.com/embeddedci-com/benchpod-cli/internal/tcpclient" ) // blobTarget is where install-blobs reads the pod's W25Q slots and sends blobs: the pod's network @@ -105,7 +104,7 @@ func (l lanBlobs) Blobs(ctx context.Context) ([]serialconsole.BlobSlot, error) { } `json:"blobs"` } if err := l.lan.cmd(ctx, map[string]any{"cmd": "blob_status"}, &rep); err != nil { - if pe, ok := tcpclient.AsPodError(err); ok && strings.Contains(pe.Reason, "unknown cmd") { + if isUnknownCommand(err) { return nil, serialconsole.ErrNoBlobSlots } return nil, err diff --git a/cmd/benchpod-cli/busmaster.go b/cmd/benchpod-cli/busmaster.go index 605f787..a20ac7c 100644 --- a/cmd/benchpod-cli/busmaster.go +++ b/cmd/benchpod-cli/busmaster.go @@ -33,12 +33,12 @@ func tooOldForBusMaster(feature string) string { } // busCommand sends one command and words the reply for the user: a firmware without the command -// ("unknown cmd") says which update it needs, other refusals get the usual hints. +// (BP0002, "unknown cmd" before codes) says which update it needs, other refusals get the usual hints. func busCommand(ctx context.Context, t *podTarget, what, feature string, req map[string]any, out any) error { raw, err := t.client.Command(ctx, req) if err != nil { if pe, ok := tcpclient.AsPodError(err); ok { - if strings.TrimSpace(pe.Reason) == "unknown cmd" { + if isUnknownCommand(err) { return &shownRefusal{msg: what + ": " + tooOldForBusMaster(feature), pe: pe} } return refusedError(what, pe, !t.spec.IsCloud()) @@ -574,7 +574,7 @@ type laPinsCommander interface { func laPinsFetch(ctx context.Context, c laPinsCommander, pins []int) (json.RawMessage, error) { if pins == nil { raw, err := c.Command(ctx, map[string]any{"cmd": "la_pins"}) - if err == nil || !strings.Contains(err.Error(), "reply too large") { + if err == nil || !strings.Contains(err.Error(), "reply too large") { // no code yet return raw, err } first, err1 := laPinsQuery(ctx, c, []int{1, 2, 3, 4, 5, 6, 7}) diff --git a/cmd/benchpod-cli/ci_lease.go b/cmd/benchpod-cli/ci_lease.go index efe9d2e..5f95655 100644 --- a/cmd/benchpod-cli/ci_lease.go +++ b/cmd/benchpod-cli/ci_lease.go @@ -266,7 +266,7 @@ const ( ) func isLeaseBusy(pe *tcpclient.PodError) bool { - return pe.Code == codeLeaseBusy || pe.Kind() == tcpclient.Busy + return pe.Code == codeLeaseBusy || pe.Kind() == tcpclient.Busy // Kind: the text fallback without a code } // busyText is " holds this pod (, N s left)" from a lease_busy refusal. @@ -285,6 +285,7 @@ func busyText(pe *tcpclient.PodError) string { } return s } + // fallback: BP0025's holder/purpose/left_s args replace it (firmware without codes) return strings.TrimPrefix(strings.TrimSpace(pe.Reason), "busy: ") } @@ -301,8 +302,11 @@ func leaseLostText(pe *tcpclient.PodError) string { // isLeaseLost is a command refused because the run's lease was stopped (BP0026) or expired (BP0027). func isLeaseLost(pe *tcpclient.PodError) bool { - r := strings.TrimSpace(pe.Reason) - return pe.Code == codeLeaseLost || pe.Code == codeLeaseNotHeld || strings.HasPrefix(r, "lease lost") + if pe.Code == codeLeaseLost || pe.Code == codeLeaseNotHeld { + return true + } + // fallback: BP0026 / BP0027 replace it (firmware without codes) + return strings.HasPrefix(strings.TrimSpace(pe.Reason), "lease lost") } // ── the server's lease (embeddedci.com) ───────────────────────────────────── diff --git a/cmd/benchpod-cli/cloudcfg.go b/cmd/benchpod-cli/cloudcfg.go index b16eca4..2911a94 100644 --- a/cmd/benchpod-cli/cloudcfg.go +++ b/cmd/benchpod-cli/cloudcfg.go @@ -414,8 +414,8 @@ func cloudCfgError(what, missing string, lan bool, err error) error { if errors.Is(err, serialconsole.ErrUnknownCommand) { return errors.New(missing) } - msg := err.Error() - if strings.Contains(msg, "unknown cmd") || strings.Contains(msg, "unknown target") { + // "unknown target": no code yet (a cloud_ca / cloud_proxy target older firmware lacks) + if isUnknownCommand(err) || strings.Contains(err.Error(), "unknown target") { return errors.New(missing) } if pe, ok := tcpclient.AsPodError(err); ok { diff --git a/cmd/benchpod-cli/errors.go b/cmd/benchpod-cli/errors.go index e1aeea9..76fd0f7 100644 --- a/cmd/benchpod-cli/errors.go +++ b/cmd/benchpod-cli/errors.go @@ -15,8 +15,12 @@ import ( // ── refusals ──────────────────────────────────────────────────────────────── // // Every refusal from the pod, over the LAN JSON API or the USB console, is a *tcpclient.PodError. -// The policy refusals carry a firmware prefix (locked:, busy:, forbidden:; internal/fwrefusals -// pins the texts) and explainRefusal is the one place that says what to do about each. +// A refusal with a stable code (BP0001...) is classified by tcpclient's code table (the exit code) +// and worded from the catalog (internal/errcatalog: its message and fix.cli, codedRefusal). A +// refusal without one (older firmware, or a refusal with no code yet) falls back to its text: the +// policy refusals carry a firmware prefix (locked:, busy:, forbidden:; internal/fwrefusals pins +// the texts) and explainRefusal is the one place that says what to do about each. Each text match +// below names what replaces it: a code, or "no code yet". const ( lockedUSBHint = "the pod's external LAN policy is locked; run this over USB with --connection usb" @@ -69,28 +73,29 @@ var i2cPullupRE = regexp.MustCompile(`^(I2C needs pull-ups): switch on LA(\d+)'s // text to show and the hint to add ("" for none). Other refusals come back unchanged with no hint. func translateRefusal(msg string) (shown, hint string) { msg = strings.TrimSpace(msg) - if strings.HasPrefix(msg, "la voltage not set") { + if strings.HasPrefix(msg, "la voltage not set") { // fallback: BP0001 replaces it return msg, laVoltageUnsetHint } - if m := i2cPullupRE.FindStringSubmatch(msg); m != nil { + if m := i2cPullupRE.FindStringSubmatch(msg); m != nil { // no code yet return m[1], fmt.Sprintf("pull LA%s up with `benchpod la pull %s up`, or pass --pullups external "+ "when the board has its own", m[2], m[2]) } + // fallback: BP0017 (gateware_too_old) replaces it if strings.HasSuffix(msg, "need gateware v55+: update the pod's firmware") || strings.HasSuffix(msg, "needs gateware v55+: update the pod's firmware") { return msg, "update it with `benchpod flash-self`" } - if m := emulationImageRE.FindStringSubmatchIndex(msg); m != nil { + if m := emulationImageRE.FindStringSubmatchIndex(msg); m != nil { // no code yet image := msg[m[2]:m[3]] return strings.TrimSuffix(strings.TrimSpace(msg[:m[0]]), ":"), fmt.Sprintf( "stop the sensors with `benchpod sensor stop`, then switch with `benchpod sensor image %s`", image) } - if strings.HasPrefix(msg, "image switch refused:") { + if strings.HasPrefix(msg, "image switch refused:") { // no code yet if i := strings.Index(msg, "; stop them first ("); i > 0 { return msg[:i], "stop them with `benchpod sensor stop` first" } } - if m := pinConflictRE.FindStringSubmatch(msg); m != nil { + if m := pinConflictRE.FindStringSubmatch(msg); m != nil { // no code yet owner := m[2] if m[3] != "" { owner += " (" + m[3] + ")" @@ -109,36 +114,52 @@ func translateRefusal(msg string) (shown, hint string) { return msg, "" } -// explainRefusal returns the hint for a policy refusal, or "" when the message says it all. -// overLAN is whether the refusal came over the LAN JSON API: only the LAN refuses with locked: -// or a cloud lease, so elsewhere those texts stand alone. +// explainRefusal returns the hint for a refusal without a code, by its text, or "" when the +// message says it all. overLAN is whether the refusal came over the LAN JSON API: only the LAN +// refuses with locked: or a cloud lease, so elsewhere those texts stand alone. A coded refusal +// gets the catalog's fix.cli instead (refusalHint). func explainRefusal(msg string, overLAN bool) string { msg = strings.TrimSpace(msg) switch tcpclient.ClassifyRefusal(msg) { - case tcpclient.Locked: + case tcpclient.Locked: // no code yet if overLAN { return lockedUSBHint } case tcpclient.Busy: switch { - case overLAN && strings.HasPrefix(msg, "busy: a cloud job holds"): + case overLAN && strings.HasPrefix(msg, "busy: a cloud job holds"): // fallback: BP0025 replaces it return leaseBusyHint - case msg == "busy": + case msg == "busy": // no code yet return heavyBusyHint } - case tcpclient.Forbidden: + case tcpclient.Forbidden: // no code yet return forbiddenHint } _, hint := translateRefusal(msg) return hint } +// refusalHint is what to do about a refusal: the catalog's fix.cli for a coded one, else +// explainRefusal's hint from the text ("" for none). +func refusalHint(pe *tcpclient.PodError, overLAN bool) string { + if pe.Code != "" { + if e, ok := errcatalog.Lookup(pe.Code); ok { + return errcatalog.Fill(e.Fix["cli"], pe.Args) + } + } + return explainRefusal(pe.Reason, overLAN) +} + // refusedError is the one line for a refusal from a command: ": the pod refused: ", -// plus explainRefusal's hint. +// plus refusalHint's hint (a coded refusal: the catalog's message and fix.cli). func refusedError(what string, pe *tcpclient.PodError, overLAN bool) error { - return refusedWithHint(what, pe, explainRefusal(pe.Reason, overLAN)) + return refusedWithHint(what, pe, refusalHint(pe, overLAN)) } +// isUnknownCommand says the pod does not know the command it was sent: its firmware is older +// than the command. BP0002, else (firmware without codes) the text "unknown cmd". +func isUnknownCommand(err error) bool { return tcpclient.IsUnknownCommand(err) } + // refusedWithHint is refusedError with the hint given ("" for none). func refusedWithHint(what string, pe *tcpclient.PodError, hint string) error { if coded, ok := codedRefusal(pe); ok { diff --git a/cmd/benchpod-cli/errors_test.go b/cmd/benchpod-cli/errors_test.go index 8cdbd72..cece660 100644 --- a/cmd/benchpod-cli/errors_test.go +++ b/cmd/benchpod-cli/errors_test.go @@ -9,6 +9,7 @@ import ( "strings" "testing" + "github.com/embeddedci-com/benchpod-cli/internal/errcatalog" "github.com/embeddedci-com/benchpod-cli/internal/fwrefusals" "github.com/embeddedci-com/benchpod-cli/internal/serverapi" "github.com/embeddedci-com/benchpod-cli/internal/tcpclient" @@ -138,3 +139,71 @@ func TestShownRefusalsKeepTheirExitCode(t *testing.T) { } } } + +// Every code in the catalog: the exit code follows its kind, and the refusal shows the catalog's +// message and fix.cli with the args filled in, whatever the pod's text. +func TestEveryCodedRefusal(t *testing.T) { + wantExit := map[tcpclient.RefusalKind]int{ + tcpclient.Refused: exitRefused, tcpclient.Locked: exitRefused, + tcpclient.Forbidden: exitRefused, tcpclient.Busy: exitBusy, + } + args := map[string]any{"cmd": "x", "arg": "la", "name": "k66", "rev": 3, "max": 8, "bytes": 9000, + "expected": 0, "feature": "i2c", "min": 55, "la": 4, "rx": 1, "tx": 2, "have": "up", "want": "down", + "holder": "benchpod ci: alice", "purpose": "smoke", "left_s": 30, "by": "bob", "id": "L-1", "mv": 12, + "client_api": 1, "min_client_api": 2, "api": 2} + for _, code := range errcatalog.Codes() { + t.Run(code, func(t *testing.T) { + e, _ := errcatalog.Lookup(code) + kind, ok := tcpclient.CodeKind(code) + if !ok { + t.Fatal("no kind") + } + pe := &tcpclient.PodError{Reason: "pod returned an error", Code: code, Args: args} + if got := exitCode(fmt.Errorf("x: %w", pe)); got != wantExit[kind] { + t.Errorf("exit %d, want %d", got, wantExit[kind]) + } + fix := errcatalog.Fill(e.Fix["cli"], args) + if got := refusalHint(pe, true); got != fix { + t.Errorf("hint %q, want %q", got, fix) + } + msg := refusedError("cmd", pe, true).Error() + if !strings.Contains(msg, code+": "+errcatalog.Fill(e.Message, args)) || !strings.Contains(msg, fix) { + t.Errorf("refusedError = %q", msg) + } + if msg := withRefusalHint(fmt.Errorf("cmd: %w", pe)).Error(); !strings.Contains(msg, fix) { + t.Errorf("withRefusalHint = %q", msg) + } + }) + } +} + +// The text fallbacks still classify a refusal without a code as before (older firmware). +func TestUncodedRefusalsKeepTheirExitCodes(t *testing.T) { + for id, want := range map[string]int{ + "lan_locked": exitRefused, "lan_locked_v39": exitRefused, "tunnel_forbidden": exitRefused, + "lease_busy": exitBusy, "heavy_busy": exitBusy, "psram_bus_busy": exitBusy, "swd_busy": exitBusy, + "uart_busy": exitBusy, "spi_busy": exitBusy, "swd_or_spi_busy": exitBusy, "unknown_cmd": exitRefused, + "la_voltage_unset": exitRefused, "pin_conflict": exitRefused, + } { + if got := exitCode(&tcpclient.PodError{Reason: fwrefusals.Example(id)}); got != want { + t.Errorf("%s: exit %d, want %d", id, got, want) + } + } +} + +// One helper says "the firmware lacks this command": BP0002, or the old text. +func TestIsUnknownCommandHelper(t *testing.T) { + if !isUnknownCommand(fmt.Errorf("x: %w", &tcpclient.PodError{Code: "BP0002", Reason: "pod returned an error"})) || + !isUnknownCommand(&tcpclient.PodError{Reason: fwrefusals.Example("unknown_cmd")}) || + isUnknownCommand(&tcpclient.PodError{Code: "BP0006", Reason: "missing la"}) || + isUnknownCommand(errors.New("unknown cmd")) { + t.Fatal("isUnknownCommand") + } +} + +// unknownCmdReplies are a pod's answers to a command its firmware lacks: the text of firmware +// without codes, and BP0002 (with no text: a build without texts). +var unknownCmdReplies = []string{ + `{"status":"error","message":"unknown cmd"}`, + `{"status":"error","code":"BP0002","args":{"cmd":"x"}}`, +} diff --git a/cmd/benchpod-cli/flash_esp.go b/cmd/benchpod-cli/flash_esp.go index f136a84..d438a31 100644 --- a/cmd/benchpod-cli/flash_esp.go +++ b/cmd/benchpod-cli/flash_esp.go @@ -252,7 +252,7 @@ func runFlashESP(g *globalFlags, f *flashFlags, spec ConnSpec) error { req[k] = v } if _, err := c.Command(ctx, req); err != nil { - if pe, ok := tcpclient.AsPodError(err); ok && strings.Contains(pe.Error(), "unknown cmd") { + if isUnknownCommand(err) { return fmt.Errorf("flash: this pod's firmware cannot flash an ESP32 (no esp_flash command): update it with `benchpod flash-self`") } return fmt.Errorf("flash: %w", err) diff --git a/cmd/benchpod-cli/lantls.go b/cmd/benchpod-cli/lantls.go index 65d53a3..e9929e7 100644 --- a/cmd/benchpod-cli/lantls.go +++ b/cmd/benchpod-cli/lantls.go @@ -155,7 +155,7 @@ func lanTLSError(what string, err error) error { if pe, ok := tcpclient.AsPodError(err); ok { r := pe.Reason switch { - case strings.Contains(r, "unknown command") || strings.Contains(r, "unknown cmd"): + case isUnknownCommand(err): return errors.New(lanTLSMissing) case strings.Contains(r, "change it over TLS"): return fmt.Errorf("%s: %s", what, lanTLSPlainHint) diff --git a/cmd/benchpod-cli/lavoltage.go b/cmd/benchpod-cli/lavoltage.go index 463b396..8918d81 100644 --- a/cmd/benchpod-cli/lavoltage.go +++ b/cmd/benchpod-cli/lavoltage.go @@ -266,7 +266,7 @@ func laVoltageError(what string, err error) error { return errors.New(laVoltageMissing) } if pe, ok := tcpclient.AsPodError(err); ok { - if pe.Reason == "unknown cmd" { + if isUnknownCommand(err) { return errors.New(laVoltageMissing) } return refusedError(what, pe, pe.Cmd == "") diff --git a/cmd/benchpod-cli/lavoltage_test.go b/cmd/benchpod-cli/lavoltage_test.go index 231ee91..674821f 100644 --- a/cmd/benchpod-cli/lavoltage_test.go +++ b/cmd/benchpod-cli/lavoltage_test.go @@ -98,12 +98,14 @@ func TestLAVoltageLAN(t *testing.T) { } func TestLAVoltageLANRefusals(t *testing.T) { - addr, _ := fakeLANPod(t, `{"status":"error","message":"unknown cmd"}`) - if err := runLAVoltage(&globalFlags{connection: addr}, 0, &bytes.Buffer{}, &bytes.Buffer{}); err == nil || err.Error() != laVoltageMissing { - t.Fatalf("old firmware: %v", err) + for _, reply := range unknownCmdReplies { + addr, _ := fakeLANPod(t, reply) + if err := runLAVoltage(&globalFlags{connection: addr}, 0, &bytes.Buffer{}, &bytes.Buffer{}); err == nil || err.Error() != laVoltageMissing { + t.Fatalf("old firmware: %v", err) + } } msg := fwrefusals.Example("lan_locked") - addr, _ = fakeLANPod(t, `{"status":"error","message":"`+msg+`"}`) + addr, _ := fakeLANPod(t, `{"status":"error","message":"`+msg+`"}`) err := runLAVoltage(&globalFlags{connection: addr}, 3300, &bytes.Buffer{}, &bytes.Buffer{}) if err == nil || err.Error() != "la voltage: the pod refused: "+msg+" ("+lockedUSBHint+")" { t.Fatalf("locked: %v", err) diff --git a/cmd/benchpod-cli/loglevel.go b/cmd/benchpod-cli/loglevel.go index d9a9064..0179862 100644 --- a/cmd/benchpod-cli/loglevel.go +++ b/cmd/benchpod-cli/loglevel.go @@ -84,7 +84,7 @@ func logLevelJSON(ctx context.Context, c podCommander, set string) (string, erro } data, err := c.Command(ctx, req) if err != nil { - if strings.Contains(err.Error(), "unknown cmd") { + if isUnknownCommand(err) { return "", errors.New(logLevelMissing) } return "", err diff --git a/cmd/benchpod-cli/loglevel_test.go b/cmd/benchpod-cli/loglevel_test.go index ef67b3d..c23cb62 100644 --- a/cmd/benchpod-cli/loglevel_test.go +++ b/cmd/benchpod-cli/loglevel_test.go @@ -29,10 +29,12 @@ func TestLogLevelSet(t *testing.T) { } func TestLogLevelOnOlderFirmware(t *testing.T) { - addr, _ := fakeLANPod(t, `{"status":"error","message":"unknown cmd"}`) - err := runLogLevel(&globalFlags{connection: addr}, "", &bytes.Buffer{}) - if err == nil || !strings.Contains(err.Error(), "newer than 3.10.12") { - t.Fatalf("got %v", err) + for _, reply := range unknownCmdReplies { + addr, _ := fakeLANPod(t, reply) + err := runLogLevel(&globalFlags{connection: addr}, "", &bytes.Buffer{}) + if err == nil || !strings.Contains(err.Error(), "newer than 3.10.12") { + t.Fatalf("got %v", err) + } } } diff --git a/cmd/benchpod-cli/policy.go b/cmd/benchpod-cli/policy.go index ec590d1..e001e19 100644 --- a/cmd/benchpod-cli/policy.go +++ b/cmd/benchpod-cli/policy.go @@ -313,6 +313,7 @@ func cloudPolicyError(p podPolicy, set string, err error) error { if msg == "" { return fmt.Errorf("%s: %w", what, err) } + // "loosen": no code yet (sig_policy's "only the USB console can loosen the policy") if set != "" && p.cmd == sigPolicy.cmd && strings.Contains(strings.ToLower(msg), "loosen") { return relayedRefusal(p, fmt.Sprintf("%s: the pod refused: %s. Loosen it over the pod's USB console: benchpod sig-policy set %s --connection usb", what, msg, set), msg) @@ -400,7 +401,7 @@ func runPolicyLAN(g *globalFlags, p podPolicy, addr string, out io.Writer) error client := &tcpclient.Client{Addr: addr} data, err := client.Command(ctx, map[string]any{"cmd": p.jsonCmd}) if err != nil { - if strings.Contains(err.Error(), "unknown cmd") { + if isUnknownCommand(err) { return errors.New(p.missing) } if p.cmd == lanPolicy.cmd { diff --git a/cmd/benchpod-cli/policy_test.go b/cmd/benchpod-cli/policy_test.go index 2982c6b..fb9181a 100644 --- a/cmd/benchpod-cli/policy_test.go +++ b/cmd/benchpod-cli/policy_test.go @@ -313,10 +313,12 @@ func TestPolicyLANShowOnly(t *testing.T) { } func TestPolicyLANOldFirmware(t *testing.T) { - addr, _ := fakeLANPod(t, `{"status":"error","message":"unknown cmd"}`) - _, _, err := runPolicyCapture(t, &globalFlags{connection: addr}, lanPolicy, policyTarget{}, "") - if err == nil || err.Error() != "this firmware has no LAN policy; update the pod's firmware" { - t.Fatalf("err = %v", err) + for _, reply := range unknownCmdReplies { + addr, _ := fakeLANPod(t, reply) + _, _, err := runPolicyCapture(t, &globalFlags{connection: addr}, lanPolicy, policyTarget{}, "") + if err == nil || err.Error() != "this firmware has no LAN policy; update the pod's firmware" { + t.Fatalf("err = %v", err) + } } } diff --git a/cmd/benchpod-cli/refusals_test.go b/cmd/benchpod-cli/refusals_test.go index e7dc293..ab7e24c 100644 --- a/cmd/benchpod-cli/refusals_test.go +++ b/cmd/benchpod-cli/refusals_test.go @@ -1,7 +1,6 @@ package main import ( - "errors" "fmt" "net/http" "strings" @@ -46,12 +45,19 @@ func TestTheCloudLinkGateRefusalsGetTheLANHint(t *testing.T) { } func TestOldFirmwareRefusalsMeanTheFeatureIsMissing(t *testing.T) { + // Firmware without codes: the texts. for _, id := range []string{"unknown_cmd", "unknown_target"} { - err := cloudCfgError("cloud ca set", caMissing, true, errors.New(fwrefusals.Example(id))) + err := cloudCfgError("cloud ca set", caMissing, true, &tcpclient.PodError{Reason: fwrefusals.Example(id)}) if err.Error() != caMissing { t.Errorf("%s: got %v", id, err) } } + // With codes: BP0002, whatever the text (a build without texts sends none). + err := cloudCfgError("cloud ca set", caMissing, true, &tcpclient.PodError{Reason: "pod returned an error", Code: "BP0002", + Args: map[string]any{"cmd": "cloud_ca"}}) + if err.Error() != caMissing { + t.Errorf("BP0002: got %v", err) + } } func TestACloudRefusalToLoosenTheSignaturePolicyPointsAtUSB(t *testing.T) { diff --git a/cmd/benchpod-cli/usbnetwork.go b/cmd/benchpod-cli/usbnetwork.go index 552bff6..408a961 100644 --- a/cmd/benchpod-cli/usbnetwork.go +++ b/cmd/benchpod-cli/usbnetwork.go @@ -122,7 +122,7 @@ func usbNetworkJSON(ctx context.Context, c podCommander, set string) (string, er } data, err := c.Command(ctx, req) if err != nil { - if strings.Contains(err.Error(), "unknown cmd") { + if isUnknownCommand(err) { return "", errors.New(usbNetworkMissing) } return "", err diff --git a/cmd/benchpod-cli/usbnetwork_test.go b/cmd/benchpod-cli/usbnetwork_test.go index 60870a0..ee5febe 100644 --- a/cmd/benchpod-cli/usbnetwork_test.go +++ b/cmd/benchpod-cli/usbnetwork_test.go @@ -45,10 +45,12 @@ func TestUSBNetworkOffOverTheUSBLink(t *testing.T) { // Older firmware: a clear "update the firmware". func TestUSBNetworkOnOlderFirmware(t *testing.T) { - addr, _ := fakeLANPod(t, `{"status":"error","message":"unknown cmd"}`) - err := runUSBNetwork(&globalFlags{connection: addr}, "", &bytes.Buffer{}) - if err == nil || !strings.Contains(err.Error(), "3.9.0 or later") { - t.Fatalf("err = %v", err) + for _, reply := range unknownCmdReplies { + addr, _ := fakeLANPod(t, reply) + err := runUSBNetwork(&globalFlags{connection: addr}, "", &bytes.Buffer{}) + if err == nil || !strings.Contains(err.Error(), "3.9.0 or later") { + t.Fatalf("err = %v", err) + } } } diff --git a/cmd/benchpod-cli/wiring.go b/cmd/benchpod-cli/wiring.go index 18a4507..a84db28 100644 --- a/cmd/benchpod-cli/wiring.go +++ b/cmd/benchpod-cli/wiring.go @@ -20,7 +20,6 @@ import ( "time" "github.com/embeddedci-com/benchpod-cli/internal/errcatalog" - "github.com/embeddedci-com/benchpod-cli/internal/tcpclient" "github.com/spf13/cobra" ) @@ -69,10 +68,10 @@ func wiringList(ctx context.Context, c podCommander) (*wiringListReply, error) { // errNoWiringStore: the pod's firmware stores no wiring profiles. var errNoWiringStore = errors.New("this pod's firmware does not store wiring profiles; update it with `benchpod flash-self`") -// wiringStoreList is wiringList, with an older firmware's "unknown cmd" as errNoWiringStore. +// wiringStoreList is wiringList, with an older firmware's BP0002 ("unknown cmd") as errNoWiringStore. func wiringStoreList(ctx context.Context, c podCommander) (*wiringListReply, error) { l, err := wiringList(ctx, c) - if pe, ok := tcpclient.AsPodError(err); ok && (pe.Code == "BP0002" || strings.TrimSpace(pe.Reason) == "unknown cmd") { + if isUnknownCommand(err) { return nil, errNoWiringStore } return l, err diff --git a/internal/cloudpod/cloudpod_test.go b/internal/cloudpod/cloudpod_test.go index d6c8ab4..d919122 100644 --- a/internal/cloudpod/cloudpod_test.go +++ b/internal/cloudpod/cloudpod_test.go @@ -113,6 +113,19 @@ func TestPodRefusalIsAPodError(t *testing.T) { } } +// A coded refusal keeps its code and args through embeddedci.com, and its kind follows the code. +func TestCodedPodRefusalThroughTheCloud(t *testing.T) { + f := &fakeServer{reply: func(w http.ResponseWriter) { + _, _ = w.Write([]byte(`{"status":"error","code":"BP0025","args":{"holder":"a cloud job","purpose":"ci","left_s":7}}`)) + }} + c := &Client{API: f.start(t), Credential: "tok", DeviceID: "id-b", Name: "bench-b"} + _, err := c.Command(context.Background(), map[string]any{"cmd": "la"}) + pe, ok := tcpclient.AsPodError(err) + if !ok || pe.Code != "BP0025" || pe.Args["holder"] != "a cloud job" || pe.Kind() != tcpclient.Busy { + t.Fatalf("err = %#v", err) + } +} + func TestTransportFailures(t *testing.T) { for _, c := range []struct { status int diff --git a/internal/errcatalog/errcatalog.go b/internal/errcatalog/errcatalog.go index 6f5de01..17dc182 100644 --- a/internal/errcatalog/errcatalog.go +++ b/internal/errcatalog/errcatalog.go @@ -9,6 +9,7 @@ import ( "encoding/json" "fmt" "regexp" + "sort" "strings" ) @@ -47,6 +48,16 @@ func Lookup(code string) (Entry, bool) { return e, ok } +// Codes is every code in the catalog, sorted. +func Codes() []string { + out := make([]string, 0, len(cat.Codes)) + for c := range cat.Codes { + out = append(out, c) + } + sort.Strings(out) + return out +} + // Count is how many codes the catalog has. func Count() int { return len(cat.Codes) } diff --git a/internal/fwrefusals/refusals.json b/internal/fwrefusals/refusals.json index 7cc6c16..4b4dff4 100644 --- a/internal/fwrefusals/refusals.json +++ b/internal/fwrefusals/refusals.json @@ -7,7 +7,7 @@ {"id": "lan_locked", "file": "stm32h563/src/cmd_gate.c", "removed": "3.9.0", "kind": "json", "format": "locked: %s needs the cloud or the USB console", "example": "locked: cloud_set needs the cloud or the USB console"}, - {"id": "lease_busy", "file": "stm32h563/src/cmd_gate.c", "kind": "json", + {"id": "lease_busy", "file": "stm32h563/src/cmd_gate.c", "removed": "3.10.14", "kind": "json", "format": "busy: a cloud job holds this pod (%s, %lu s left)", "example": "busy: a cloud job holds this pod (ci-run-42, 37 s left)"}, {"id": "tunnel_forbidden", "file": "stm32h563/src/cmd_gate.c", "kind": "json", diff --git a/internal/tcpclient/codes_test.go b/internal/tcpclient/codes_test.go new file mode 100644 index 0000000..6fd848a --- /dev/null +++ b/internal/tcpclient/codes_test.go @@ -0,0 +1,78 @@ +package tcpclient + +import ( + "testing" + + "github.com/embeddedci-com/benchpod-cli/internal/errcatalog" +) + +// Every code in the catalog has a kind in codeKinds, and the table has no code the catalog lacks. +func TestCodeKindsCoverTheCatalog(t *testing.T) { + for _, code := range errcatalog.Codes() { + if _, ok := CodeKind(code); !ok { + t.Errorf("%s is in the catalog but not in codeKinds", code) + } + } + for code := range codeKinds { + if _, ok := errcatalog.Lookup(code); !ok { + t.Errorf("%s is in codeKinds but not in the catalog", code) + } + } +} + +// A coded refusal is classified by its code, whatever its text. +func TestPodErrorKindByCode(t *testing.T) { + for _, c := range []struct { + code, reason string + want RefusalKind + }{ + {"BP0001", "la voltage not set", Refused}, + {"BP0002", "unknown cmd", Refused}, + {"BP0003", "", Busy}, + {"BP0004", "", Busy}, + {"BP0005", "swd or spi busy: ...", Busy}, + {"BP0016", "pod returned an error", Busy}, + {"BP0025", "busy: a cloud job holds this pod (ci, 3 s left)", Busy}, + {"BP0025", "pod returned an error", Busy}, // a build without texts + {"BP0026", "lease lost", Refused}, + {"BP0027", "", Refused}, + {"BP0017", "busy", Refused}, // the code wins over the text + {"bp0003", "", Busy}, + } { + if got := (&PodError{Code: c.code, Reason: c.reason}).Kind(); got != c.want { + t.Errorf("%s %q: kind %v, want %v", c.code, c.reason, got, c.want) + } + } + // Without a code, or with one this table does not know (newer firmware), the text decides. + for _, c := range []struct { + code, reason string + want RefusalKind + }{ + {"", "locked: x needs the cloud or USB", Locked}, + {"", "forbidden: x needs an organization owner or admin", Forbidden}, + {"", "uart busy", Busy}, + {"", "unknown cmd", Refused}, + {"BP9999", "busy", Busy}, + } { + if got := (&PodError{Code: c.code, Reason: c.reason}).Kind(); got != c.want { + t.Errorf("%s %q: kind %v, want %v", c.code, c.reason, got, c.want) + } + } +} + +func TestIsUnknownCommand(t *testing.T) { + for _, c := range []struct { + pe *PodError + want bool + }{ + {&PodError{Code: "BP0002", Reason: "pod returned an error"}, true}, + {&PodError{Reason: "unknown cmd"}, true}, + {&PodError{Reason: "unknown command 'x'"}, true}, + {&PodError{Code: "BP0006", Reason: "missing la"}, false}, + {&PodError{Reason: "uart busy"}, false}, + } { + if got := IsUnknownCommand(c.pe); got != c.want { + t.Errorf("%+v: got %v", c.pe, got) + } + } +} diff --git a/internal/tcpclient/errors.go b/internal/tcpclient/errors.go index 1ac1402..541f4f3 100644 --- a/internal/tcpclient/errors.go +++ b/internal/tcpclient/errors.go @@ -44,19 +44,72 @@ const ( Forbidden ) -// Kind classifies the refusal. -func (e *PodError) Kind() RefusalKind { return ClassifyRefusal(e.Reason) } +// codeKinds is the one table from a refusal's stable code (benchpod-firmware errors/catalog.toml, +// internal/errcatalog) to its kind, for every code in the catalog; the exit code follows the kind, +// and the CLI's hint for a coded refusal is the catalog's fix.cli. A test keeps it in step with +// the catalog. A code the table does not have (newer firmware) falls back to the text. +var codeKinds = map[string]RefusalKind{ + "BP0001": Refused, // la_voltage_not_set + "BP0002": Refused, // unknown_command: also IsUnknownCommand, for "this firmware lacks it" messages + "BP0003": Busy, // i2c_session_open + "BP0004": Busy, // spi_session_open + "BP0005": Busy, // bus_engine_busy + "BP0006": Refused, // missing_argument + "BP0007": Refused, // wiring_profile_not_found + "BP0008": Refused, // wiring_bad_name + "BP0009": Refused, // wiring_revision_conflict + "BP0010": Refused, // wiring_store_full + "BP0011": Refused, // wiring_profile_too_large + "BP0012": Refused, // wiring_not_json_object + "BP0013": Refused, // wiring_delete_default + "BP0014": Refused, // wiring_upload_out_of_order + "BP0015": Refused, // wiring_storage_failed + "BP0016": Busy, // storage_busy + "BP0017": Refused, // gateware_too_old + "BP0018": Refused, // uart_same_pin + "BP0019": Refused, // uart_half_duplex_two_pins + "BP0020": Refused, // uart_entry_no_reset_pin + "BP0021": Refused, // uart_entry_invalid + "BP0022": Refused, // uart_de_pin + "BP0023": Refused, // la_no_pull + "BP0024": Refused, // la_pull_direction + "BP0025": Busy, // lease_busy: args holder, purpose, left_s + "BP0026": Refused, // lease_lost: args by (benchpod ci handles it: the run is invalid) + "BP0027": Refused, // lease_not_held + "BP0028": Refused, // vref_5v_missing + "BP0029": Refused, // pull_rail_down + "BP0030": Refused, // client_too_old +} + +// CodeKind is the kind of a refusal code; ok is false for a code the table does not have. +func CodeKind(code string) (kind RefusalKind, ok bool) { + kind, ok = codeKinds[strings.ToUpper(strings.TrimSpace(code))] + return kind, ok +} + +// Kind classifies the refusal: by its code, else (a reply without one, from older firmware or a +// refusal with no code yet) by its text. +func (e *PodError) Kind() RefusalKind { + if k, ok := CodeKind(e.Code); ok { + return k + } + return ClassifyRefusal(e.Reason) +} // ClassifyRefusal classifies a firmware refusal text by its prefix: "locked:", "forbidden:", // or a first clause ending in "busy" ("busy", "busy: ...", "swd busy", "swd or spi busy: ..."). +// It is the fallback for a refusal without a code. func ClassifyRefusal(msg string) RefusalKind { msg = strings.TrimSpace(msg) switch { - case strings.HasPrefix(msg, "locked:"): + case strings.HasPrefix(msg, "locked:"): // no code yet (the LAN policy gate) return Locked - case strings.HasPrefix(msg, "forbidden:"): + case strings.HasPrefix(msg, "forbidden:"): // no code yet (the cloud tunnel role gate) return Forbidden } + // "busy: a cloud job holds ..." / "busy: holds ...": BP0025 on firmware after + // 3.10.13; the engine texts ("swd busy", "uart busy", "busy: ... PSRAM bus"): no code yet + // (BP0003-BP0005 and BP0016 cover the I2C, SPI, bus engine and storage cases). head, _, _ := strings.Cut(msg, ":") if head == "busy" || strings.HasSuffix(head, " busy") { return Busy diff --git a/internal/tcpclient/lease.go b/internal/tcpclient/lease.go index 45e4ec1..09363d0 100644 --- a/internal/tcpclient/lease.go +++ b/internal/tcpclient/lease.go @@ -36,8 +36,12 @@ func IsUnknownCommand(err error) bool { if !ok { return false } + if pe.Code == "BP0002" { + return true + } + // fallback: BP0002 replaces it (firmware without codes) r := strings.ToLower(strings.TrimSpace(pe.Reason)) - return pe.Code == "BP0002" || strings.HasPrefix(r, "unknown cmd") || strings.HasPrefix(r, "unknown command") + return strings.HasPrefix(r, "unknown cmd") || strings.HasPrefix(r, "unknown command") } func (c *Client) tagLease(req map[string]any) map[string]any { return tagLease(req, c.NoLeaseJoin) } From 32848c033dcefa4cc55720c65c553b1df9d60836 Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Thu, 19 Nov 2026 16:59:07 -0600 Subject: [PATCH 3/5] Client API level: send client_api and client, stop on newer pod firmware Every JSON command (LAN, USB networking, a session, a raw-mode start and embeddedci.com's command channel) carries "client_api":1 and "client":"cli ". A status reply announcing an api above the CLI's (1, the embedded features.json api; none counts as 1) stops with "this pod's firmware needs a newer benchpod CLI (...)" and exit code 6; a BP0030 refusal gives the same error. README: exit code 6 and how the update check works. Co-Authored-By: Claude Opus 5.5 --- README.md | 20 +++ cmd/benchpod-cli/errors.go | 8 +- cmd/benchpod-cli/errors_test.go | 79 ++++++++++ cmd/benchpod-cli/podclient_test.go | 4 + cmd/benchpod-cli/root.go | 2 + internal/cloudpod/cloudpod.go | 9 +- internal/cloudpod/cloudpod_test.go | 39 +++++ internal/features/features.go | 15 +- internal/tcpclient/client.go | 5 +- internal/tcpclient/clientapi.go | 164 ++++++++++++++++++++ internal/tcpclient/clientapi_test.go | 220 +++++++++++++++++++++++++++ internal/tcpclient/errors.go | 15 +- internal/tcpclient/lease.go | 22 +-- internal/tcpclient/session.go | 5 +- internal/tcpclient/swd.go | 2 +- 15 files changed, 578 insertions(+), 31 deletions(-) create mode 100644 internal/tcpclient/clientapi.go create mode 100644 internal/tcpclient/clientapi_test.go diff --git a/README.md b/README.md index 5871674..a0adfd4 100644 --- a/README.md +++ b/README.md @@ -1038,10 +1038,30 @@ stderr with a `[benchpod]` prefix. | `3` | Refused: the pod refused the command (a locked LAN, a missing role, a bad request). | | `4` | Busy: the pod or one of its engines is in use (a cloud job's lease, another session). | | `5` | Unreachable: nothing answered on the pod's address, no pod was found on USB, or the pod is offline on embeddedci.com. | +| `6` | Update the CLI: the pod's firmware needs a newer benchpod CLI (see [Firmware newer than the CLI](#firmware-newer-than-the-cli)). | `benchpod ci` has its own exit codes (a CI result, not a command's): see [Exit codes of `benchpod ci`](#exit-codes-of-benchpod-ci). +#### Firmware newer than the CLI + +Every JSON command the CLI sends to the pod (on the LAN, over USB networking and through +embeddedci.com) carries `"client_api"`, the pod API level this CLI was built for, and +`"client"`, its name and version (`"cli 0.9.5"`). Firmware 3.10.13 and older ignores both. +Newer firmware announces its own level in `status`; it goes up only when the firmware changes +a reply in a way an older CLI would misread. When the pod's level is above this CLI's (a pod +without one counts as level 1), a command that reads the pod's status stops with exit code +`6` and says so: + +```text +[benchpod] status: this pod's firmware 3.11.0 needs a newer benchpod CLI (pod API 2, this CLI handles 1): brew upgrade --cask benchpod, or download the latest release from https://github.com/embeddedci-com/benchpod-cli/releases/latest +``` + +A pod that no longer takes commands from a CLI this old refuses them with `BP0030`, which +the CLI reports the same way. Update the CLI as you installed it (see +[Installation](#installation)). Commands that only talk to embeddedci.com or work locally are +not affected, and neither is the USB console. + Firmware 3.10.8 and later sends more and more refusals with a stable error code (`BP0001` and up). The CLI then shows the code, what went wrong and what to run, from the error catalog it ships with, plus a link to the code's page; `benchpod explain ` prints the whole entry. The diff --git a/cmd/benchpod-cli/errors.go b/cmd/benchpod-cli/errors.go index 76fd0f7..78e5d1f 100644 --- a/cmd/benchpod-cli/errors.go +++ b/cmd/benchpod-cli/errors.go @@ -244,6 +244,7 @@ const ( exitRefused = 3 // the pod refused the command (locked LAN, missing role, bad request) exitBusy = 4 // the pod or one of its engines is in use (a cloud lease, another session) exitUnreachable = 5 // the pod did not answer on its address, no pod on USB, or offline on embeddedci.com + exitUpdateCLI = 6 // the pod's firmware needs a newer CLI (its API level is above this CLI's, or BP0030) ) // exitCodesHelp is the exit-code table for the root command's help. @@ -254,7 +255,8 @@ const exitCodesHelp = "Exit codes:\n" + " 3 refused: the pod refused the command (a locked LAN, a missing role, a bad request)\n" + " 4 busy: the pod or one of its engines is in use (a cloud job's lease, another session)\n" + " 5 unreachable: nothing answered on the pod's address, no pod found on USB, or the\n" + - " pod is offline on embeddedci.com" + " pod is offline on embeddedci.com\n" + + " 6 update the CLI: the pod's firmware needs a newer benchpod CLI" // usageError marks a command-line mistake (exit code 2). type usageError struct{ err error } @@ -280,6 +282,10 @@ func exitCode(err error) int { if strings.HasPrefix(err.Error(), "unknown command ") { return exitUsage } + var upd *tcpclient.UpdateRequiredError + if errors.As(err, &upd) { + return exitUpdateCLI + } if pe, ok := tcpclient.AsPodError(err); ok { if pe.Kind() == tcpclient.Busy { return exitBusy diff --git a/cmd/benchpod-cli/errors_test.go b/cmd/benchpod-cli/errors_test.go index cece660..ddb5365 100644 --- a/cmd/benchpod-cli/errors_test.go +++ b/cmd/benchpod-cli/errors_test.go @@ -1,13 +1,17 @@ package main import ( + "context" "encoding/json" "errors" "fmt" + "log" "net" "net/http" + "os" "strings" "testing" + "time" "github.com/embeddedci-com/benchpod-cli/internal/errcatalog" "github.com/embeddedci-com/benchpod-cli/internal/fwrefusals" @@ -153,6 +157,13 @@ func TestEveryCodedRefusal(t *testing.T) { "client_api": 1, "min_client_api": 2, "api": 2} for _, code := range errcatalog.Codes() { t.Run(code, func(t *testing.T) { + if code == tcpclient.CodeClientTooOld { + // Not a *PodError: the update-required error (TestNewerPodFirmwareNeedsANewerCLI). + if got := exitCode(tcpclient.RefusalError("", code, args)); got != exitUpdateCLI { + t.Errorf("exit %d, want %d", got, exitUpdateCLI) + } + return + } e, _ := errcatalog.Lookup(code) kind, ok := tcpclient.CodeKind(code) if !ok { @@ -207,3 +218,71 @@ var unknownCmdReplies = []string{ `{"status":"error","message":"unknown cmd"}`, `{"status":"error","code":"BP0002","args":{"cmd":"x"}}`, } + +// A pod whose firmware announces a newer API than this CLI handles stops a command that reads +// its status, with its own exit code; so does BP0030. A pod with api 1 or none works. +func TestNewerPodFirmwareNeedsANewerCLI(t *testing.T) { + newer, _ := fakeLANPod(t, `{"status":"ok","data":{"version":"3.11.0","api":2,"min_client_api":0}}`) + same, _ := fakeLANPod(t, `{"status":"ok","data":{"version":"3.10.14","api":1,"min_client_api":0}}`) + old, _ := fakeLANPod(t, `{"status":"ok","data":{"version":"3.10.13"}}`) + tooOld, _ := fakeLANPod(t, `{"status":"error","code":"BP0030","args":{"client_api":1,"min_client_api":2,"api":2},`+ + `"message":"update the BenchPod SDK, MCP or CLI: this firmware needs client API 2 or newer (this client sent 1)"}`) + var logged strings.Builder + log.SetOutput(&logged) + defer log.SetOutput(os.Stderr) + for _, c := range []struct { + args []string + want int + msg string + }{ + {[]string{"status", "--connection", newer}, exitUpdateCLI, + "this pod's firmware 3.11.0 needs a newer benchpod CLI (pod API 2, this CLI handles 1): brew upgrade --cask benchpod"}, + {[]string{"ping", "--connection", tooOld}, exitUpdateCLI, + "this pod's firmware needs a newer benchpod CLI (pod API 2, this CLI handles 1): brew upgrade --cask benchpod"}, + {[]string{"ping", "--connection", newer}, exitOK, ""}, // ping reads no status + } { + logged.Reset() + if got := run(c.args); got != c.want { + t.Errorf("%v: exit %d, want %d (%s)", c.args, got, c.want, logged.String()) + } + if !strings.Contains(logged.String(), c.msg) || (c.msg != "" && strings.Contains(logged.String(), "BP0030:")) { + t.Errorf("%v: logged %q", c.args, logged.String()) + } + } + for _, addr := range []string{same, old} { + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + _, err := (&tcpclient.Client{Addr: addr}).Command(ctx, map[string]any{"cmd": "status", "caps": false}) + cancel() + if err != nil { + t.Errorf("%s: %v", addr, err) + } + } + if got := exitCode(fmt.Errorf("x: %w", &tcpclient.UpdateRequiredError{PodAPI: 2})); got != exitUpdateCLI { + t.Errorf("wrapped: exit %d", got) + } +} + +// Every JSON command the CLI sends carries client_api and client ("cli "), on the LAN and +// through embeddedci.com. +func TestEveryRequestCarriesTheClientFields(t *testing.T) { + tcpclient.SetClientFields(true) + defer tcpclient.SetClientFields(false) + addr, got := fakeLANPod(t, `{"status":"ok","data":"pong"}`) + if code := run([]string{"ping", "--connection", addr}); code != exitOK { + t.Fatalf("exit %d", code) + } + var req map[string]any + _ = json.Unmarshal([]byte(<-got), &req) + if req["client_api"] != float64(tcpclient.ClientAPI) || req["client"] != "cli "+strings.TrimPrefix(version, "v") { + t.Fatalf("LAN request %v", req) + } + + f := &fakeCloud{reply: podReplies(map[string]string{"ping": `"pong"`})} + f.start(t) + if code := run([]string{"ping", "--connection", "embeddedci:bench-1"}); code != exitOK { + t.Fatalf("cloud exit %d", code) + } + if len(f.commands) == 0 || f.commands[0]["client_api"] != float64(tcpclient.ClientAPI) || f.commands[0]["client"] == nil { + t.Fatalf("cloud request %v", f.commands) + } +} diff --git a/cmd/benchpod-cli/podclient_test.go b/cmd/benchpod-cli/podclient_test.go index 3dd3b08..25ed5ab 100644 --- a/cmd/benchpod-cli/podclient_test.go +++ b/cmd/benchpod-cli/podclient_test.go @@ -19,6 +19,7 @@ import ( "github.com/embeddedci-com/benchpod-cli/internal/benchpodconfig" "github.com/embeddedci-com/benchpod-cli/internal/serialconsole" + "github.com/embeddedci-com/benchpod-cli/internal/tcpclient" ) // TestMain keeps every test off the real embeddedci.com session and config: the CLI's files go @@ -32,6 +33,9 @@ func TestMain(m *testing.M) { for _, k := range []string{"BENCHPOD_API_KEY", "BENCHPOD_API_BASE", "BENCHPOD_CONNECTION", "BENCHPOD_CONFIG_FILE"} { os.Unsetenv(k) } + // Requests compare whole: without client_api and client (TestEveryRequestCarriesTheClientFields + // turns them on). + tcpclient.SetClientFields(false) // Never probe this machine's USB ports for a pod's USB network adapter. usbNetwork = func(*globalFlags, string) (serialconsole.USBNet, error) { return serialconsole.USBNet{}, errors.New("no pod on USB (tests)") diff --git a/cmd/benchpod-cli/root.go b/cmd/benchpod-cli/root.go index 6ab812f..cd27d04 100644 --- a/cmd/benchpod-cli/root.go +++ b/cmd/benchpod-cli/root.go @@ -51,6 +51,8 @@ var version = "dev" // newRootCmd builds the benchpod root command, wires the persistent flags // through Viper, and registers all subcommands. func newRootCmd() *cobra.Command { + // Every JSON command names this CLI to the pod ("client"), next to its client_api. + tcpclient.SetClientName("cli " + strings.TrimPrefix(version, "v")) g := &globalFlags{} root := &cobra.Command{ Use: "benchpod", diff --git a/internal/cloudpod/cloudpod.go b/internal/cloudpod/cloudpod.go index e0055c2..87f2ec3 100644 --- a/internal/cloudpod/cloudpod.go +++ b/internal/cloudpod/cloudpod.go @@ -140,6 +140,8 @@ func (c *Client) Command(ctx context.Context, req map[string]any) (json.RawMessa } var resp *serverapi.CommandResponse var err error + // The server passes the command on as it is, so it carries client_api and client like a LAN one. + req = tcpclient.TagRequest(req) if c.ByName { resp, err = c.API.CloudDeviceCommand(ctx, c.Credential, c.Name, req, timeout) } else { @@ -153,7 +155,12 @@ func (c *Client) Command(ctx context.Context, req map[string]any) (json.RawMessa if msg == "" { msg = "pod returned an error" } - return nil, &tcpclient.PodError{Reason: msg, Code: resp.Code, Args: resp.Args} + return nil, tcpclient.RefusalError(msg, resp.Code, resp.Args) + } + if tcpclient.IsStatus(req) { + if err := tcpclient.CheckPodAPI(resp.Data); err != nil { + return nil, err + } } return resp.Data, nil } diff --git a/internal/cloudpod/cloudpod_test.go b/internal/cloudpod/cloudpod_test.go index d919122..8682539 100644 --- a/internal/cloudpod/cloudpod_test.go +++ b/internal/cloudpod/cloudpod_test.go @@ -229,3 +229,42 @@ func TestMissingScope(t *testing.T) { t.Fatal(e.Error()) } } + +// A command through embeddedci.com carries client_api and client like a LAN one (the server passes +// it on as it is), and not the LAN lease. +func TestCloudCommandCarriesTheClientFields(t *testing.T) { + tcpclient.SetLeaseJoin(&tcpclient.LeaseJoin{ID: "L-1"}) + defer tcpclient.SetLeaseJoin(nil) + f := &fakeServer{reply: func(w http.ResponseWriter) { _, _ = w.Write([]byte(`{"status":"ok","data":{}}`)) }} + c := &Client{API: f.start(t), Credential: "tok", DeviceID: "id-b", Name: "bench-b"} + req := map[string]any{"cmd": "ping"} + if _, err := c.Command(context.Background(), req); err != nil { + t.Fatal(err) + } + if f.command["client_api"] != float64(tcpclient.ClientAPI) || f.command["client"] != tcpclient.ClientName() || + f.command["lease"] != nil || len(req) != 1 { + t.Fatalf("sent %v", f.command) + } +} + +// The status check and BP0030 work through embeddedci.com too. +func TestCloudNewerPodNeedsANewerCLI(t *testing.T) { + for _, c := range []struct { + cmd, reply string + bad bool + }{ + {"status", `{"status":"ok","data":{"version":"3.11.0","api":2}}`, true}, + {"status", `{"status":"ok","data":{"version":"3.10.13"}}`, false}, + {"status", `{"status":"ok","data":{"api":1}}`, false}, + {"ping", `{"status":"ok","data":{"api":2}}`, false}, + {"la", `{"status":"error","code":"BP0030","args":{"client_api":1,"min_client_api":2,"api":2}}`, true}, + } { + f := &fakeServer{reply: func(w http.ResponseWriter) { _, _ = w.Write([]byte(c.reply)) }} + cl := &Client{API: f.start(t), Credential: "tok", DeviceID: "id-b", Name: "bench-b"} + _, err := cl.Command(context.Background(), map[string]any{"cmd": c.cmd}) + var upd *tcpclient.UpdateRequiredError + if got := errors.As(err, &upd); got != c.bad || (!c.bad && err != nil) { + t.Errorf("%s %s: err = %v", c.cmd, c.reply, err) + } + } +} diff --git a/internal/features/features.go b/internal/features/features.go index bd0fc8d..6b748e2 100644 --- a/internal/features/features.go +++ b/internal/features/features.go @@ -40,10 +40,14 @@ type Fact struct { // Table is the parsed features.json. type Table struct { - Schema int `json:"schema"` - Revision int `json:"revision"` - Facts map[string]Fact `json:"facts"` - Features map[string]Entry `json:"features"` + Schema int `json:"schema"` + Revision int `json:"revision"` + // API is the client API level of the firmware the table is from; MinClientAPI the lowest it + // takes (benchpod-firmware docs/API.md, Client compatibility). + API int `json:"api"` + MinClientAPI int `json:"min_client_api"` + Facts map[string]Fact `json:"facts"` + Features map[string]Entry `json:"features"` } var table = func() Table { @@ -57,6 +61,9 @@ var table = func() Table { // Revision is the highest table revision this CLI knows. func Revision() int { return table.Revision } +// API is the client API level of the table this CLI embeds: the highest pod API it handles. +func API() int { return table.API } + // Lookup returns the entry for a feature name. func Lookup(name string) (Entry, bool) { e, ok := table.Features[name] diff --git a/internal/tcpclient/client.go b/internal/tcpclient/client.go index cf4939f..7c4a894 100644 --- a/internal/tcpclient/client.go +++ b/internal/tcpclient/client.go @@ -87,6 +87,9 @@ func (c *Client) Command(ctx context.Context, req map[string]any) (json.RawMessa } switch r.Status { case "ok": + if err := checkReply(req, r.Data); err != nil { + return nil, err + } return r.Data, nil case "error": return nil, replyError(r) @@ -223,7 +226,7 @@ func (c *Client) dialAndSend(ctx context.Context, req map[string]any) (net.Conn, _ = conn.SetDeadline(deadline) } - line, err := json.Marshal(c.tagLease(req)) + line, err := json.Marshal(c.tagRequest(req)) if err != nil { conn.Close() return nil, nil, fmt.Errorf("marshal request: %w", err) diff --git a/internal/tcpclient/clientapi.go b/internal/tcpclient/clientapi.go new file mode 100644 index 0000000..2c3ecac --- /dev/null +++ b/internal/tcpclient/clientapi.go @@ -0,0 +1,164 @@ +package tcpclient + +import ( + "encoding/json" + "fmt" + "strings" + "sync/atomic" +) + +// ── client API level ──────────────────────────────────────────────────────── +// +// The pod announces its client API level ("api") and the lowest it takes ("min_client_api") in +// status (benchpod-firmware docs/API.md, Client compatibility). The level goes up only for a change +// an older client would misread, so this CLI stops when a pod announces a level above ClientAPI, +// and every JSON command says which level it was built for ("client_api") and who sent it +// ("client"). Older firmware ignores both fields and announces no api, which counts as 1. + +// ClientAPI is the highest pod API level this CLI handles: the "api" of the features.json it embeds +// (a test checks that). +const ClientAPI = 1 + +// CodeClientTooOld is the pod refusing a client below its min_client_api. +const CodeClientTooOld = "BP0030" + +// UpdatePath is how to get a newer CLI (README, Installation). +const UpdatePath = "brew upgrade --cask benchpod, or download the latest release from " + + "https://github.com/embeddedci-com/benchpod-cli/releases/latest" + +// maxClientName is the firmware's limit on "client": longer names are left out. +const maxClientName = 32 + +var clientName atomic.Value // string + +// clientFieldsOff: commands go without client_api and client (SetClientFields). +var clientFieldsOff atomic.Bool + +// SetClientFields turns the client_api and client fields on (the default) or off. Off is for tests +// that compare whole requests; the pod treats a command without them as client API 0. +func SetClientFields(on bool) { clientFieldsOff.Store(!on) } + +func init() { clientName.Store("cli dev") } + +// SetClientName sets the "client" every command carries ("cli 0.9.5"). The firmware takes at most +// 32 printable ASCII characters, so a longer name is cut and other characters are dropped. +func SetClientName(name string) { + var b strings.Builder + for _, r := range name { + if r >= 0x20 && r < 0x7f && b.Len() < maxClientName { + b.WriteRune(r) + } + } + clientName.Store(strings.TrimSpace(b.String())) +} + +// ClientName is the "client" every command carries. +func ClientName() string { return clientName.Load().(string) } + +// tagRequest is req as it goes on the wire: with "client_api" and "client", and the lease set +// with SetLeaseJoin unless skipLease (a copy; req is not changed). Fields req has already are kept. +func tagRequest(req map[string]any, skipLease bool) map[string]any { + out := make(map[string]any, len(req)+3) + for k, v := range req { + out[k] = v + } + if !clientFieldsOff.Load() { + if _, has := out["client_api"]; !has { + out["client_api"] = ClientAPI + } + if name := ClientName(); name != "" { + if _, has := out["client"]; !has { + out["client"] = name + } + } + } + if j := leaseJoin.Load(); j != nil && !skipLease { + if _, has := out["lease"]; !has { + out["lease"] = j.ID + } + } + return out +} + +// TagRequest is req with "client_api" and "client" (not the lease: that is this package's), for a +// JSON command that goes to the pod another way: embeddedci.com's command channel. +func TagRequest(req map[string]any) map[string]any { return tagRequest(req, true) } + +// UpdateRequiredError is a pod whose firmware needs a newer CLI: it announces an API level above +// ClientAPI, or it refused the command with BP0030. It is not a *PodError: no hint or fallback +// applies, and the CLI exits with its own code. +type UpdateRequiredError struct { + Firmware string // the pod's firmware version, "" when not known (BP0030) + PodAPI int // the pod's client API level + MinClientAPI int // the lowest level it takes + // Refusal is the pod's BP0030 refusal, nil when the CLI stopped on the status announcement. + Refusal *PodError +} + +func (e *UpdateRequiredError) Error() string { + fw := "this pod's firmware" + if e.Firmware != "" { + fw += " " + e.Firmware + } + return fmt.Sprintf("%s needs a newer benchpod CLI (pod API %d, this CLI handles %d): %s", + fw, e.PodAPI, ClientAPI, UpdatePath) +} + +func updateRequiredFromRefusal(pe *PodError) *UpdateRequiredError { + e := &UpdateRequiredError{Refusal: pe} + e.PodAPI, _ = intArg(pe.Args, "api") + e.MinClientAPI, _ = intArg(pe.Args, "min_client_api") + if e.PodAPI < e.MinClientAPI { + e.PodAPI = e.MinClientAPI + } + return e +} + +func intArg(args map[string]any, key string) (int, bool) { + switch v := args[key].(type) { + case float64: + return int(v), true + case int: + return v, true + case json.Number: + n, err := v.Int64() + return int(n), err == nil + } + return 0, false +} + +// IsStatus says req is the status command, whose reply announces the pod's API level. +func IsStatus(req map[string]any) bool { + cmd, _ := req["cmd"].(string) + return cmd == "status" +} + +// CheckPodAPI checks a status reply's API level: an *UpdateRequiredError when the pod announces +// an "api" (or a "min_client_api") above ClientAPI, nil otherwise. A reply without "api" +// (firmware 3.10.13 and older) is level 1; a reply that does not parse is left to its reader. +func CheckPodAPI(statusReply json.RawMessage) error { + var st struct { + Version string `json:"version"` + API *int `json:"api"` + MinClientAPI int `json:"min_client_api"` + } + if json.Unmarshal(statusReply, &st) != nil { + return nil + } + api := 1 + if st.API != nil { + api = *st.API + } + if api <= ClientAPI && st.MinClientAPI <= ClientAPI { + return nil + } + return &UpdateRequiredError{Firmware: st.Version, PodAPI: max(api, st.MinClientAPI), MinClientAPI: st.MinClientAPI} +} + +// checkReply is CheckPodAPI on a status command's reply, nil for any other command. +func checkReply(req map[string]any, data json.RawMessage) error { + if !IsStatus(req) { + return nil + } + return CheckPodAPI(data) +} diff --git a/internal/tcpclient/clientapi_test.go b/internal/tcpclient/clientapi_test.go new file mode 100644 index 0000000..cca7778 --- /dev/null +++ b/internal/tcpclient/clientapi_test.go @@ -0,0 +1,220 @@ +package tcpclient + +import ( + "bufio" + "context" + "encoding/json" + "errors" + "net" + "strings" + "testing" + "time" + + "github.com/embeddedci-com/benchpod-cli/internal/features" +) + +// ClientAPI is the api of the features.json this CLI embeds: a table bump that raises api needs a +// CLI that handles it. +func TestClientAPIIsTheEmbeddedTablesAPI(t *testing.T) { + if ClientAPI != features.API() { + t.Fatalf("ClientAPI = %d, the embedded features.json has api %d", ClientAPI, features.API()) + } +} + +func TestTagRequest(t *testing.T) { + SetClientName("cli 1.2.3") + defer SetClientName("cli dev") + req := map[string]any{"cmd": "ping"} + got := tagRequest(req, false) + if got["client_api"] != ClientAPI || got["client"] != "cli 1.2.3" || got["cmd"] != "ping" { + t.Fatalf("got %v", got) + } + if len(req) != 1 { + t.Fatalf("req changed: %v", req) + } + // Fields the request has are kept. + if got := tagRequest(map[string]any{"cmd": "x", "client_api": 0, "client": "me"}, false); got["client_api"] != 0 || got["client"] != "me" { + t.Fatalf("got %v", got) + } + // The lease: added unless skipped; the client fields either way. + SetLeaseJoin(&LeaseJoin{ID: "L-1"}) + defer SetLeaseJoin(nil) + if got := tagRequest(map[string]any{"cmd": "x"}, false); got["lease"] != "L-1" || got["client_api"] != ClientAPI { + t.Fatalf("got %v", got) + } + if got := TagRequest(map[string]any{"cmd": "x"}); got["lease"] != nil || got["client_api"] != ClientAPI { + t.Fatalf("TagRequest: got %v", got) + } + SetClientFields(false) + if got := tagRequest(map[string]any{"cmd": "x"}, true); len(got) != 1 { + t.Fatalf("fields off: got %v", got) + } + SetClientFields(true) +} + +// The firmware takes at most 32 printable ASCII characters. +func TestSetClientName(t *testing.T) { + defer SetClientName("cli dev") + SetClientName("cli 0.9.5-rc.1+build.abcdefghijklmnopqrstuvwxyz") + if n := ClientName(); len(n) != 32 || !strings.HasPrefix(n, "cli 0.9.5") { + t.Fatalf("%q", n) + } + SetClientName("cli é\n1") + if n := ClientName(); n != "cli 1" { + t.Fatalf("%q", n) + } +} + +// requestServer answers one reply per connection (several requests on one connection for a +// session) and hands each request it read to the test. +func requestServer(t *testing.T, reply string) (string, <-chan map[string]any) { + t.Helper() + ln, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { ln.Close() }) + got := make(chan map[string]any, 8) + go func() { + for { + conn, err := ln.Accept() + if err != nil { + return + } + go func(conn net.Conn) { + defer conn.Close() + r := bufio.NewReader(conn) + for { + line, err := r.ReadBytes('\n') + if err != nil { + return + } + var req map[string]any + _ = json.Unmarshal(line, &req) + got <- req + if _, err := conn.Write([]byte(reply + "\n")); err != nil { + return + } + } + }(conn) + } + }() + return ln.Addr().String(), got +} + +func wantClientFields(t *testing.T, what string, req map[string]any) { + t.Helper() + if req["client_api"] != float64(ClientAPI) || req["client"] != ClientName() || ClientName() == "" { + t.Errorf("%s: request %v lacks client_api %d / client %q", what, req, ClientAPI, ClientName()) + } +} + +// Every way this package sends a JSON command carries client_api and client. +func TestEveryRequestBuilderCarriesTheClientFields(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + addr, got := requestServer(t, `{"status":"ok","data":{},"more":false}`) + c := &Client{Addr: addr, TLS: TLSOff} + + if _, err := c.Command(ctx, map[string]any{"cmd": "ping"}); err != nil { + t.Fatal(err) + } + wantClientFields(t, "Command", <-got) + + if _, err := c.Chunks(ctx, map[string]any{"cmd": "capture_read"}); err != nil { + t.Fatal(err) + } + wantClientFields(t, "Chunks", <-got) + + s, err := c.Open(ctx) + if err != nil { + t.Fatal(err) + } + if _, err := s.Command(ctx, map[string]any{"cmd": "ping"}); err != nil { + t.Fatal(err) + } + wantClientFields(t, "Session.Command", <-got) + s.Close() + + conn, err := c.StartRaw(ctx, map[string]any{"cmd": "uart_proxy_start", "rx": 1, "tx": 2}) + if err != nil { + t.Fatal(err) + } + wantClientFields(t, "StartRaw", <-got) + conn.Close() +} + +func TestCheckPodAPI(t *testing.T) { + for _, c := range []struct { + status string + bad bool + }{ + {`{"version":"3.10.13"}`, false}, // no api: level 1 + {`{"version":"3.10.14","api":1,"min_client_api":0}`, false}, + {`{"version":"3.11.0","api":2,"min_client_api":0}`, true}, + {`{"version":"3.11.0","api":2,"min_client_api":2}`, true}, + {`not json`, false}, + } { + err := CheckPodAPI(json.RawMessage(c.status)) + var upd *UpdateRequiredError + if got := errors.As(err, &upd); got != c.bad { + t.Errorf("%s: err = %v", c.status, err) + } + } + err := CheckPodAPI(json.RawMessage(`{"version":"3.11.0","api":2}`)) + want := "this pod's firmware 3.11.0 needs a newer benchpod CLI (pod API 2, this CLI handles 1): " + UpdatePath + if err == nil || err.Error() != want { + t.Fatalf("err = %v, want %q", err, want) + } +} + +// Reading status checks the pod's API level, on a connection and in a session; other commands +// do not. +func TestStatusOfANewerPodStops(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + addr, _ := requestServer(t, `{"status":"ok","data":{"version":"3.11.0","api":2,"min_client_api":0}}`) + c := &Client{Addr: addr, TLS: TLSOff} + var upd *UpdateRequiredError + if _, err := c.Command(ctx, map[string]any{"cmd": "status", "caps": false}); !errors.As(err, &upd) || upd.PodAPI != 2 || upd.Firmware != "3.11.0" { + t.Fatalf("status: err = %v", err) + } + if _, err := c.Command(ctx, map[string]any{"cmd": "ping"}); err != nil { + t.Fatalf("ping: %v", err) + } + s, err := c.Open(ctx) + if err != nil { + t.Fatal(err) + } + defer s.Close() + if _, err := s.Command(ctx, map[string]any{"cmd": "status"}); !errors.As(err, &upd) { + t.Fatalf("session status: err = %v", err) + } + + for _, ok := range []string{`{"status":"ok","data":{"version":"3.10.13"}}`, `{"status":"ok","data":{"api":1}}`} { + addr, _ := requestServer(t, ok) + if _, err := (&Client{Addr: addr, TLS: TLSOff}).Command(ctx, map[string]any{"cmd": "status"}); err != nil { + t.Fatalf("%s: %v", ok, err) + } + } +} + +// BP0030 is the same error as the status check, not a *PodError. +func TestClientTooOldRefusal(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + addr, _ := requestServer(t, `{"status":"error","code":"BP0030","args":{"client_api":1,"min_client_api":2,"api":2},`+ + `"message":"update the BenchPod SDK, MCP or CLI: this firmware needs client API 2 or newer (this client sent 1)"}`) + _, err := (&Client{Addr: addr, TLS: TLSOff}).Command(ctx, map[string]any{"cmd": "la"}) + var upd *UpdateRequiredError + if !errors.As(err, &upd) || upd.PodAPI != 2 || upd.MinClientAPI != 2 || upd.Refusal == nil || upd.Refusal.Code != "BP0030" { + t.Fatalf("err = %#v", err) + } + if _, ok := AsPodError(err); ok { + t.Fatal("BP0030 is not a *PodError") + } + want := "this pod's firmware needs a newer benchpod CLI (pod API 2, this CLI handles 1): " + UpdatePath + if err.Error() != want { + t.Fatalf("err = %q, want %q", err, want) + } +} diff --git a/internal/tcpclient/errors.go b/internal/tcpclient/errors.go index 541f4f3..51639dc 100644 --- a/internal/tcpclient/errors.go +++ b/internal/tcpclient/errors.go @@ -78,7 +78,7 @@ var codeKinds = map[string]RefusalKind{ "BP0027": Refused, // lease_not_held "BP0028": Refused, // vref_5v_missing "BP0029": Refused, // pull_rail_down - "BP0030": Refused, // client_too_old + "BP0030": Refused, // client_too_old: arrives as an *UpdateRequiredError, not a *PodError (RefusalError) } // CodeKind is the kind of a refusal code; ok is false for a code the table does not have. @@ -156,6 +156,15 @@ func firmwareMessage(msg string) string { func podError(msg string) error { return &PodError{Reason: firmwareMessage(msg)} } // replyError is an error reply from the JSON API with its code and args. -func replyError(r *reply) error { - return &PodError{Reason: firmwareMessage(r.Message), Code: r.Code, Args: r.Args} +func replyError(r *reply) error { return RefusalError(r.Message, r.Code, r.Args) } + +// RefusalError is a refusal with its text, code and args, from any JSON transport (the LAN, the +// USB network, embeddedci.com's command channel): a *PodError, or for BP0030 (the pod takes no +// client this old) an *UpdateRequiredError. +func RefusalError(msg, code string, args map[string]any) error { + pe := &PodError{Reason: firmwareMessage(msg), Code: code, Args: args} + if strings.EqualFold(strings.TrimSpace(code), CodeClientTooOld) { + return updateRequiredFromRefusal(pe) + } + return pe } diff --git a/internal/tcpclient/lease.go b/internal/tcpclient/lease.go index 09363d0..f2ad7bb 100644 --- a/internal/tcpclient/lease.go +++ b/internal/tcpclient/lease.go @@ -44,22 +44,6 @@ func IsUnknownCommand(err error) bool { return strings.HasPrefix(r, "unknown cmd") || strings.HasPrefix(r, "unknown command") } -func (c *Client) tagLease(req map[string]any) map[string]any { return tagLease(req, c.NoLeaseJoin) } - -// tagLease is req with "lease": added while a lease is set (a copy; req is not changed). A -// request that names a lease already, or skip, is left as it is. -func tagLease(req map[string]any, skip bool) map[string]any { - j := leaseJoin.Load() - if j == nil || skip { - return req - } - if _, has := req["lease"]; has { - return req - } - out := make(map[string]any, len(req)+1) - for k, v := range req { - out[k] = v - } - out["lease"] = j.ID - return out -} +// tagRequest is req as this client sends it: with the client fields and, unless NoLeaseJoin, the +// lease (clientapi.go). +func (c *Client) tagRequest(req map[string]any) map[string]any { return tagRequest(req, c.NoLeaseJoin) } diff --git a/internal/tcpclient/session.go b/internal/tcpclient/session.go index 80c23fd..6e4bebb 100644 --- a/internal/tcpclient/session.go +++ b/internal/tcpclient/session.go @@ -65,7 +65,7 @@ func (s *Session) Command(ctx context.Context, req map[string]any) (json.RawMess _ = s.conn.SetDeadline(deadline) defer watchContext(ctx, s.conn)() - line, err := json.Marshal(tagLease(req, false)) + line, err := json.Marshal(tagRequest(req, false)) if err != nil { return nil, fmt.Errorf("marshal request: %w", err) } @@ -81,6 +81,9 @@ func (s *Session) Command(ctx context.Context, req map[string]any) (json.RawMess } switch r.Status { case "ok": + if err := checkReply(req, r.Data); err != nil { + return nil, err + } return r.Data, nil case "error": return nil, replyError(r) diff --git a/internal/tcpclient/swd.go b/internal/tcpclient/swd.go index 94a9b66..493e4bb 100644 --- a/internal/tcpclient/swd.go +++ b/internal/tcpclient/swd.go @@ -59,7 +59,7 @@ func (c *Client) StartRaw(ctx context.Context, req map[string]any) (net.Conn, er _ = conn.SetDeadline(deadline) } - line, err := json.Marshal(c.tagLease(req)) + line, err := json.Marshal(c.tagRequest(req)) if err != nil { conn.Close() return nil, fmt.Errorf("marshal request: %w", err) From 076e4d129e5b4a01919fe3050c88886968053490 Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Thu, 19 Nov 2026 17:02:00 -0600 Subject: [PATCH 4/5] fwrefusals: the cloud-lease busy text is still sent (firmware spells the format out again in #191) Co-Authored-By: Claude Opus 5.5 --- internal/fwrefusals/refusals.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/fwrefusals/refusals.json b/internal/fwrefusals/refusals.json index 4b4dff4..7cc6c16 100644 --- a/internal/fwrefusals/refusals.json +++ b/internal/fwrefusals/refusals.json @@ -7,7 +7,7 @@ {"id": "lan_locked", "file": "stm32h563/src/cmd_gate.c", "removed": "3.9.0", "kind": "json", "format": "locked: %s needs the cloud or the USB console", "example": "locked: cloud_set needs the cloud or the USB console"}, - {"id": "lease_busy", "file": "stm32h563/src/cmd_gate.c", "removed": "3.10.14", "kind": "json", + {"id": "lease_busy", "file": "stm32h563/src/cmd_gate.c", "kind": "json", "format": "busy: a cloud job holds this pod (%s, %lu s left)", "example": "busy: a cloud job holds this pod (ci-run-42, 37 s left)"}, {"id": "tunnel_forbidden", "file": "stm32h563/src/cmd_gate.c", "kind": "json", From 9bdd5b3f6f8e0bab95a8054c78ec55a3fedae393 Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Thu, 19 Nov 2026 17:16:59 -0600 Subject: [PATCH 5/5] Firmware newer than the CLI: status, flash-self and the other firmware commands still run status prints the update line as a warning instead of stopping, and flash-self, install-blobs, dfu, bootsel, discover and identity skip the check, so an old CLI can still show such a pod and update or roll back its firmware. The toggle is set before each command (SetAllowNewerPod). Co-Authored-By: Claude Opus 5.5 --- README.md | 6 ++++-- cmd/benchpod-cli/errors_test.go | 8 ++++--- cmd/benchpod-cli/newerpod_test.go | 36 +++++++++++++++++++++++++++++++ cmd/benchpod-cli/root.go | 15 ++++++++++++- cmd/benchpod-cli/status.go | 6 ++++++ internal/cloudpod/cloudpod.go | 2 +- internal/tcpclient/clientapi.go | 17 +++++++++++++-- 7 files changed, 81 insertions(+), 9 deletions(-) create mode 100644 cmd/benchpod-cli/newerpod_test.go diff --git a/README.md b/README.md index a0adfd4..8e1b391 100644 --- a/README.md +++ b/README.md @@ -1051,10 +1051,12 @@ embeddedci.com) carries `"client_api"`, the pod API level this CLI was built for Newer firmware announces its own level in `status`; it goes up only when the firmware changes a reply in a way an older CLI would misread. When the pod's level is above this CLI's (a pod without one counts as level 1), a command that reads the pod's status stops with exit code -`6` and says so: +`6` and says so. `status`, `flash-self`, `install-blobs`, `dfu`, `bootsel`, `discover` and +`identity` still run: `status` prints the same line as a warning, and the firmware commands are +how such a pod is updated or rolled back. ```text -[benchpod] status: this pod's firmware 3.11.0 needs a newer benchpod CLI (pod API 2, this CLI handles 1): brew upgrade --cask benchpod, or download the latest release from https://github.com/embeddedci-com/benchpod-cli/releases/latest +[benchpod] la voltage: this pod's firmware 3.11.0 needs a newer benchpod CLI (pod API 2, this CLI handles 1): brew upgrade --cask benchpod, or download the latest release from https://github.com/embeddedci-com/benchpod-cli/releases/latest ``` A pod that no longer takes commands from a CLI this old refuses them with `BP0030`, which diff --git a/cmd/benchpod-cli/errors_test.go b/cmd/benchpod-cli/errors_test.go index ddb5365..27038db 100644 --- a/cmd/benchpod-cli/errors_test.go +++ b/cmd/benchpod-cli/errors_test.go @@ -223,6 +223,7 @@ var unknownCmdReplies = []string{ // its status, with its own exit code; so does BP0030. A pod with api 1 or none works. func TestNewerPodFirmwareNeedsANewerCLI(t *testing.T) { newer, _ := fakeLANPod(t, `{"status":"ok","data":{"version":"3.11.0","api":2,"min_client_api":0}}`) + newerPing, _ := fakeLANPod(t, `{"status":"ok","data":{"version":"3.11.0","api":2,"min_client_api":0}}`) same, _ := fakeLANPod(t, `{"status":"ok","data":{"version":"3.10.14","api":1,"min_client_api":0}}`) old, _ := fakeLANPod(t, `{"status":"ok","data":{"version":"3.10.13"}}`) tooOld, _ := fakeLANPod(t, `{"status":"error","code":"BP0030","args":{"client_api":1,"min_client_api":2,"api":2},`+ @@ -235,11 +236,12 @@ func TestNewerPodFirmwareNeedsANewerCLI(t *testing.T) { want int msg string }{ - {[]string{"status", "--connection", newer}, exitUpdateCLI, - "this pod's firmware 3.11.0 needs a newer benchpod CLI (pod API 2, this CLI handles 1): brew upgrade --cask benchpod"}, + // status still shows the pod (it is how the user finds out), with the update line as a warning. + {[]string{"status", "--connection", newer}, exitOK, + "Warning: this pod's firmware 3.11.0 needs a newer benchpod CLI (pod API 2, this CLI handles 1): brew upgrade --cask benchpod"}, {[]string{"ping", "--connection", tooOld}, exitUpdateCLI, "this pod's firmware needs a newer benchpod CLI (pod API 2, this CLI handles 1): brew upgrade --cask benchpod"}, - {[]string{"ping", "--connection", newer}, exitOK, ""}, // ping reads no status + {[]string{"ping", "--connection", newerPing}, exitOK, ""}, // ping reads no status } { logged.Reset() if got := run(c.args); got != c.want { diff --git a/cmd/benchpod-cli/newerpod_test.go b/cmd/benchpod-cli/newerpod_test.go new file mode 100644 index 0000000..e2b56b2 --- /dev/null +++ b/cmd/benchpod-cli/newerpod_test.go @@ -0,0 +1,36 @@ +package main + +import ( + "testing" + + "github.com/spf13/cobra" +) + +// The commands that show or change a pod's firmware still run against firmware this CLI is too +// old for; everything else stops with exit code 6. +func TestAllowsNewerPod(t *testing.T) { + root := &cobra.Command{Use: "benchpod"} + sub := func(name string, parent *cobra.Command) *cobra.Command { + c := &cobra.Command{Use: name} + parent.AddCommand(c) + return c + } + for _, name := range []string{"status", "flash-self", "install-blobs", "dfu", "bootsel", "discover", "identity"} { + if !allowsNewerPod(sub(name, root)) { + t.Errorf("%s: want allowed", name) + } + } + for _, name := range []string{"uart", "la", "power"} { + if allowsNewerPod(sub(name, root)) { + t.Errorf("%s: want stopped", name) + } + } + // A nested "status" (sensor status, bus status) is not the top-level status. + sensor := sub("sensor", root) + if allowsNewerPod(sub("status", sensor)) { + t.Error("sensor status: want stopped") + } + if allowsNewerPod(root) { + t.Error("root: want stopped") + } +} diff --git a/cmd/benchpod-cli/root.go b/cmd/benchpod-cli/root.go index cd27d04..fe93b43 100644 --- a/cmd/benchpod-cli/root.go +++ b/cmd/benchpod-cli/root.go @@ -87,7 +87,8 @@ func newRootCmd() *cobra.Command { SilenceUsage: true, SilenceErrors: true, // Apply Viper precedence (flag > env > default) into g before any RunE. - PersistentPreRunE: func(_ *cobra.Command, _ []string) error { + PersistentPreRunE: func(c *cobra.Command, _ []string) error { + tcpclient.SetAllowNewerPod(allowsNewerPod(c)) g.connection = viper.GetString("connection") g.configFile = viper.GetString("config-file") g.outputFilename = viper.GetString("output-filename") @@ -197,3 +198,15 @@ func run(args []string) int { } return exitCode(err) } + +// newerPodCommands still run against a pod whose firmware needs a newer CLI (exit code 6 +// otherwise): they show the pod's state or change its firmware, which is how such a pod is +// rolled back or looked at. `status` prints a warning instead. +var newerPodCommands = map[string]bool{ + "status": true, "flash-self": true, "install-blobs": true, "dfu": true, "bootsel": true, + "discover": true, "identity": true, +} + +func allowsNewerPod(c *cobra.Command) bool { + return c.Parent() != nil && !c.Parent().HasParent() && newerPodCommands[c.Name()] +} diff --git a/cmd/benchpod-cli/status.go b/cmd/benchpod-cli/status.go index 04ff702..e92a04c 100644 --- a/cmd/benchpod-cli/status.go +++ b/cmd/benchpod-cli/status.go @@ -5,7 +5,9 @@ import ( "encoding/json" "fmt" "github.com/embeddedci-com/benchpod-cli/internal/features" + "github.com/embeddedci-com/benchpod-cli/internal/tcpclient" "io" + "log" "net/http" "strconv" "strings" @@ -54,6 +56,10 @@ func newStatusCmd(g *globalFlags) *cobra.Command { if err != nil { return fmt.Errorf("status: %w", err) } + if upd := tcpclient.CheckPodAPI(data); upd != nil { + // Shown, not refused: status is how the user finds out (see allowsNewerPod). + log.Printf("Warning: %v", upd) + } out, closeOut, err := resolveOutput(g.outputFilename) if err != nil { return fmt.Errorf("status: open output: %w", err) diff --git a/internal/cloudpod/cloudpod.go b/internal/cloudpod/cloudpod.go index 87f2ec3..3b50b18 100644 --- a/internal/cloudpod/cloudpod.go +++ b/internal/cloudpod/cloudpod.go @@ -157,7 +157,7 @@ func (c *Client) Command(ctx context.Context, req map[string]any) (json.RawMessa } return nil, tcpclient.RefusalError(msg, resp.Code, resp.Args) } - if tcpclient.IsStatus(req) { + if tcpclient.IsStatus(req) && !tcpclient.NewerPodAllowed() { if err := tcpclient.CheckPodAPI(resp.Data); err != nil { return nil, err } diff --git a/internal/tcpclient/clientapi.go b/internal/tcpclient/clientapi.go index 2c3ecac..61d4706 100644 --- a/internal/tcpclient/clientapi.go +++ b/internal/tcpclient/clientapi.go @@ -155,9 +155,22 @@ func CheckPodAPI(statusReply json.RawMessage) error { return &UpdateRequiredError{Firmware: st.Version, PodAPI: max(api, st.MinClientAPI), MinClientAPI: st.MinClientAPI} } -// checkReply is CheckPodAPI on a status command's reply, nil for any other command. +// newerPodAllowed turns the status check off for the commands that must work against firmware +// this CLI is too old for: showing the status, updating or rolling back the firmware and blobs, +// DFU, discovery. Set before each command runs (SetAllowNewerPod). +var newerPodAllowed atomic.Bool + +// SetAllowNewerPod lets status replies through (true) even when the pod's API level is above +// ClientAPI, or checks them again (false). +func SetAllowNewerPod(allow bool) { newerPodAllowed.Store(allow) } + +// NewerPodAllowed says whether SetAllowNewerPod(true) is in effect. +func NewerPodAllowed() bool { return newerPodAllowed.Load() } + +// checkReply is CheckPodAPI on a status command's reply, nil for any other command and when +// SetAllowNewerPod(true) is in effect. func checkReply(req map[string]any, data json.RawMessage) error { - if !IsStatus(req) { + if !IsStatus(req) || NewerPodAllowed() { return nil } return CheckPodAPI(data)