错误 - Lager

每一个可能失败的调用都返回 lager::Result<T>，它是 std::result::Result<T, lager::Error> 的别名。

pub type Result<T> = std::result::Result<T, Error>;

Error 带有 #[non_exhaustive]，因此对它做 match 需要一个兜底分支，而新增变体不会破坏您的构建。

变体

变体	触发时机
`Connection(String)`	联系不上 Box —— DNS、TCP 连接或传输层失败
`Timeout(String)`	客户端侧的截止时间到了
`Box { status, message }`	Box 接受了请求，并报告了一次失败
`DfuFailed { status, exit_code, stdout, stderr }`	Box 端的 `dfu-util` 以非零状态退出
`FlashFailed { error, output }`	调试烧录运行了，但没有烧写任何内容
`ProbeBusy { message }`	另一个操作占用调试探针的时间过长
`SafetyRefused { message }`	该 Net 的安全设置拒绝了一次烧录或擦除
`UnsupportedByBox { message }`	端点存在，但这台 Box 的软件太旧
`NotSupportedByBox { feature, details }`	该 crate 根本没有对应的路由
`Decode(String)`	响应无法解析
`AuthRequired { box_host, auth_url, message }`	Box 受网关保护，而且没有可用的凭据
`Config(String)`	客户端侧的配置问题
`Stream(String)`	流式会话（UART 或 RTT）失败
`UartInUse { message, held_by }`	另一个会话占用了该 UART Net 或其串行设备

变体参考

`Connection(String)`

该 crate 根本没有连上 Box。这个变体也涵盖 Socket.IO 连接失败。

cannot reach the Lager box: {msg}. Check network/Tailscale and that the box is
online and updated

`Timeout(String)`

客户端侧的截止时间到了：HTTP 请求、流式会话的连接确认，或者一直没等到的 wait_for 目标。 HTTP 截止时间覆盖整个响应，包括响应体：盒子发出响应头之后，JSON 响应体停滞超过截止时间，同样返回 Error::Timeout。lager-net 0.12 之前，阻塞客户端把这种情况报告为 Error::Decode。

request to the Lager box timed out: {msg}

硬件等待超时不是这个变体。wait_for_level 在 Box 上超时，返回的是 Error::Box、HTTP 502 和 GPIO 'gpio24' did not reach level 1 within 2.0s，因为 Box 完成了请求并报告了结果。Error::Timeout 表示传输层放弃了。

`Box { status: u16, message: String }`

Box 接受了请求，并报告了一次失败。这是您最常见到的变体，其中的 message 是 Box 自己的文本。

box error (HTTP {status}): {message}

常见形态：

情形	状态码	信息
Net 不存在	404	`[Supply] Net 'x' not found. Create it with 'lager nets add'.`
Net 存在，但角色不对	404	`Net 'gpio24 (role adc)' not found`
调试 Net，角色不对	404	`net 'adc1' exists but is not a debug net`
调试 Net 不存在	404	`debug net 'nosuch' not found on this box`
设定值超过硬件限制	400	`Voltage 999.0V exceeds hardware limit 60.0V`
设定值超过安全上限	502	`Refused voltage(5.0) on net 'supply2': exceeds max_voltage of 3.6`
Box 锁被别人持有	409	`Box is locked by <holder>`
仪器不在总线上	502	`Could not open instrument at <address>: No device found.`

路由器 Net 的”未找到”信息是 Net 'router1' not found，不带角色，因为路由器 Net 有意不发送角色提示。 Box 也可能用 HTTP 200 加 success: false 来报告失败 —— 跨角色的仪器冲突就是这样。那仍然是 Error::Box。

`UnsupportedByBox { message }`

该端点在 API 中是存在的，但这台 Box 太旧，提供不了它。已知所需版本时，信息中会指明它。 Box 对它不提供的路由，会用三种方式之一回应：HTTP 501、带有 "error": "Not found" 的 JSON 404，或 HTML 405 页面。crate 会把这三种都报告为该变体。路由自身的 404（例如未知的 Net）仍然是 Error::Box。在 lager-net 0.11 之前，JSON 404 会以 Error::Box 返回。

{message}. This box image does not support this endpoint; update the box

示例：

调用	所需 Box 版本
`UsbPort::state()`	0.29.0
`usb_devices()`, `dfu()`	0.33.0
安全限值、交互式 RTT	0.35.0
`DebugNet::erase_range()`	0.50.0
`scope()`	0.55.0
`hsm()`, `custom()`	0.59.0
`DebugNet::halt()`, `Arm::get_acceleration()`	0.60.0
`dmm()`, the GATT methods on `ble()`, JTAG on `DebugNet::connect_with()`	0.62.0
`admin()` metadata, bench manifest and drivers	0.46.0, 0.50.0 and 0.59.0

erase_range()、halt() 和 JTAG 连接在发送任何内容之前，会先检查调试服务的功能。因此旧 Box 会在碰到目标之前就以这个变体失败。

`NotSupportedByBox { feature, details }`

该 crate 在任何 Box 上都没有这个功能的路由。从 crate 0.8 起，已经没有任何 Net 类型会返回它：Scope 是最后一个桩实现。这个变体仍然保留，因此对它做 match 的代码依然可以编译。

'{feature}' is not yet available over the box HTTP API: {details}

UnsupportedByBox 和 NotSupportedByBox 是两个不同的变体，名字却容易混淆。Unsupported 的意思是请更新 Box。Not supported 的意思是目前没有任何 Box 能做这件事。

`DfuFailed { status, exit_code, stdout, stderr }`

Box 端的 dfu-util 运行了，并以非零状态退出（POST /usb/dfu 返回 HTTP 502）。两路输出流都是完整的，错误信息会同时引用两者。dfu-util 会把某些设备故障报告在 stdout 上，而把它的后缀警告报告在 stderr 上。

box error (HTTP 502): dfu-util exited with code {exit_code}
stderr:
...
stdout:
...

`FlashFailed { error, output }`

调试烧录运行了，但没有烧写任何内容。对于这种情况，Box 会返回 HTTP 200 并带上 programmed: false（Box 0.51.0 及更高版本）。error 是 Box 的结论行，output 是后端的输出。

flash failed: {error}
output:
...

`ProbeBusy { message }`

另一个操作（例如一次烧录或擦除）占用调试探针的时间超过了 Box 的等待时长（调试服务返回 HTTP 503）。请在另一个操作完成后重试。

debug probe busy: {message}

`SafetyRefused { message }`

该 Net 配置了 allow_destructive: false，调试服务拒绝了一次烧录或擦除（HTTP 403）。

refused by the net's safety settings: {message}

`Decode(String)`

该 crate 没能把响应解析成预期的结构。原因可能是响应体被截断、字段类型出乎意料，或者缺少必填字段。

could not decode box response: {msg}

`AuthRequired { box_host, auth_url, message }`

Box 受网关保护，而且没有可用的凭据。

{message}. Sign in with `lager login {auth_url}` (this crate reuses the CLI's
session), or set LAGER_GATEWAY_TOKEN / use LagerBoxBuilder::bearer_token

请参阅认证。

`Config(String)`

客户端侧的问题，在发送任何内容之前就被发现：LAGER_BOX_HOST 未设置、主机地址无法解析、无法推断类型的固件路径，或者读不了的文件。

configuration error: {msg}

`Stream(String)`

UART 或 RTT 会话失败：设备消失，或者会话意外关闭。RTT 会话也会在这里报告另一个会话占用了它的端口。

streaming session error: {msg}

`UartInUse { message, held_by }`

当另一个会话占用了该 Net 或其串行设备时，UART 会话无法启动。要结束您不再需要的会话，请把 held_by 传给 lager.release_uart_session()，然后重新打开。held_by 指明要释放的 Net（Box 0.49.0 或更高版本）。当两个 Net 共用一台设备时，它指的是另一个 Net。

匹配

use lager::Error;

match supply.set_voltage(5.0) {
    Ok(()) => {}
    Err(Error::UnsupportedByBox { message }) => {
        eprintln!("box too old, skipping: {message}");
        return Ok(());
    }
    Err(Error::Box { status: 502, message }) => {
        panic!("refused by a safety limit: {message}");
    }
    Err(Error::AuthRequired { auth_url, .. }) => {
        panic!("run `lager login {auth_url}` first");
    }
    Err(e) => return Err(e),   // Error is #[non_exhaustive]
}

在旧 Box 上跳过测试

fn skip_if_unsupported<T>(r: lager::Result<T>) -> Option<T> {
    match r {
        Ok(v) => Some(v),
        Err(lager::Error::UnsupportedByBox { message }) => {
            eprintln!("skipping: {message}");
            None
        }
        Err(e) => panic!("{e}"),
    }
}

说明

Error 实现了 std::error::Error 和 Display，因此 ? 可以直接转换到 Box<dyn Error> 和 anyhow::Error，不需要额外转换。
From<serde_json::Error> 映射到 Error::Decode。
这些信息是写给在 CI 输出里阅读的人看的。请把错误本身打印出来，而不是只打印它的变体名。

入门

开发

电源与仿真

测量

I/O 与通信

实用工具

安全

Box 设置

指南

错误

变体

变体参考

`Connection(String)`

`Timeout(String)`

`Box { status: u16, message: String }`

`UnsupportedByBox { message }`

`NotSupportedByBox { feature, details }`

`DfuFailed { status, exit_code, stdout, stderr }`

`FlashFailed { error, output }`

`ProbeBusy { message }`

`SafetyRefused { message }`

`Decode(String)`

`AuthRequired { box_host, auth_url, message }`

`Config(String)`

`Stream(String)`

`UartInUse { message, held_by }`

匹配

在旧 Box 上跳过测试

说明