# Gateway 主动出站 demo

本文是 `hwlab-gateway` 最小主动出站闭环的长期参考。该 demo 只验证 gateway 主动连接 cloud、cloud 下发命令、gateway 执行并回传结果；不得把它当作 M3 `DEV-LIVE` 虚拟硬件可信闭环，也不得替代 `BOX-SIMU / Gateway-SIMU / hwlab-patch-panel` 的 M3 验收链路。

## 边界

- `hwlab-gateway` 运行在用户 PC 或本地环境，主动访问 `hwlab-cloud-api`；cloud 不需要也不应入站访问 gateway。
- demo 采用普通 HTTP poll/result：gateway 调 `POST /v1/gateway/poll` 拉取命令，执行后调 `POST /v1/gateway/result` 回传 JSON-RPC response。
- `hardware.invoke.shell` 仍是 cloud-api 对外 RPC 方法；有在线 gateway 时通过主动出站链路派发，没有在线 gateway 时保留 `not_connected` 降级返回。
- 当前命令执行能力只用于受限 demo；正式真实硬件控制仍应沿用统一 capability、audit、evidence 和后续 WebSocket/设备身份设计。

## Cloud API 入口

- `GET /v1/gateway/sessions`：只读查看在线 gateway、队列深度和 last-seen。
- `POST /v1/gateway/poll`：gateway 主动注册、心跳并领取下一条待执行 JSON-RPC 请求。
- `POST /v1/gateway/result`：gateway 主动回传 JSON-RPC response，cloud-api 用 request id 完成等待中的 `hardware.invoke.shell`。
- `POST /json-rpc` 或 `POST /v1/rpc/hardware.invoke.shell`：用户、agent 或 smoke 仍只调用 cloud-api，不直连 gateway。

## Poll Loop 和长命令并发

Gateway 的 poll loop 不能等待单条 shell 命令结束后才继续 poll。Keil build/download、烧录或 Windows skill 可能运行数分钟；这些长命令必须在 gateway 内作为 in-flight 请求后台执行，poll loop 继续注册心跳并领取短状态读取、日志读取和取消/诊断请求。

判断问题类型时区分两种 timeout：

- `shellExecuted=true` 且有 `operationId`：命令已经到达 gateway，本次 shell 超过了命令超时；下一步应读取 job state、日志或产物时间戳，而不是盲目把超时继续调大。
- `shellExecuted=false`、`dispatchStatus=timed_out` 且旧链路可能 `operationId=null`：cloud-api 等不到 gateway 领取或回传，通常是 gateway poll loop 被前一个长命令队头阻塞，或 gateway 离线；修复重点是非阻塞 poll 和 in-flight 可观测性，不是只加大 dispatch timeout。

Gateway 必须在 registration payload 和 `/v1/gateway/sessions` 中暴露 `inflightCount`、`maxInflightRequests` 和当前 in-flight 摘要。默认允许少量并发，使一个长 Keil 操作不会阻塞后续只读 `job-status`、state/log 读取或健康探测；超过并发上限时应返回结构化 `gateway_busy`，不能让请求静默排队到 cloud dispatch timeout。

## Gateway 环境变量

| 变量 | 作用 |
| --- | --- |
| `HWLAB_GATEWAY_CLOUD_URL` | cloud-api 或 edge-proxy 地址；本地可用 `http://127.0.0.1:6667`，DEV 可用 `http://74.48.78.17:16667`。 |
| `HWLAB_GATEWAY_ID` | gateway 稳定身份，例如 `gtw_windows_1`。 |
| `HWLAB_GATEWAY_SESSION_ID` | gateway session id；不填时默认为 `gws_${HWLAB_GATEWAY_ID}`。 |
| `HWLAB_GATEWAY_CMD_EXEC_ENABLED=1` | 允许执行 shell 命令；未设置时 gateway 拒绝 `hardware.invoke.shell`。 |
| `HWLAB_GATEWAY_DEMO_OPEN=1` | demo 明确打开标记；本地 smoke 会设置。 |
| `HWLAB_GATEWAY_POLL_INTERVAL_MS` | poll 间隔，默认 500ms。 |
| `HWLAB_GATEWAY_MAX_INFLIGHT` | 同一 gateway 同时执行的 cloud 请求数，默认 3；用于避免长 Keil/UV4 命令阻塞短状态查询。 |
| `HWLAB_GATEWAY_CMD_TIMEOUT_MS` | 单条命令超时，默认 120000ms；Workbench 发起 Code Agent 请求时可通过“Gateway 命令超时”控件把本轮 wrapper `--timeout-ms` 调到 1/2/3/5/10 分钟。 |
| `HWLAB_GATEWAY_CMD_OUTPUT_LIMIT_BYTES` | stdout/stderr 单路输出上限，默认 65536 bytes。 |

本地或内网存在代理时，必须显式设置：

```powershell
$env:NO_PROXY="localhost,127.0.0.1,::1"
$env:no_proxy="localhost,127.0.0.1,::1"
```

## 本地验证

优先使用一键 smoke，避免手动多终端状态不一致：

```powershell
npm run gateway:demo:smoke
npm run gateway:demo:edge-smoke
```

- `gateway:demo:smoke` 启动本地 `hwlab-cloud-api` 和 `hwlab-gateway`，验证 `hardware.invoke.shell` 返回 `stdout=hwlab-demo`。
- `gateway:demo:edge-smoke` 额外启动本地 `hwlab-edge-proxy`，验证普通 HTTP proxy 能转发 `/v1/gateway/poll`、`/v1/gateway/result` 和 `/json-rpc`。
- 两个 smoke 都会设置 `NO_PROXY/no_proxy`，用于规避本地代理误触发。
- 对 D601 pod 内部 `127.0.0.1:6667` 或 service `:6667` 做 Node 探测时，不要用 Web/undici `fetch`；`6667` 属于 WHATWG bad port，Node 会直接报 `bad port`。gateway 传输层和 repo-owned 探测脚本应使用 `http/https` 原生 request，公网 `:16667` 或浏览器入口不受这个限制。

## DEV 使用

DEV cloud-api 部署包含 `/v1/gateway/*` 后，Windows gateway 可用以下方式主动连接：

```powershell
$env:HWLAB_GATEWAY_CLOUD_URL="http://74.48.78.17:16667"
$env:HWLAB_GATEWAY_ID="gtw_windows_1"
$env:HWLAB_GATEWAY_SESSION_ID="gws_gtw_windows_1"
$env:HWLAB_GATEWAY_CMD_EXEC_ENABLED="1"
$env:HWLAB_GATEWAY_DEMO_OPEN="1"
node .\cmd\hwlab-gateway\main.mjs
```

验证时从 cloud-api 侧调用 `hardware.invoke.shell`，不要尝试从 cloud 入站访问 Windows gateway。若 `GET /v1/gateway/sessions` 能看到对应 `gatewaySessionId` 且 JSON-RPC 返回 `dispatch.shellExecuted=true`，说明主动出站 demo 链路成立。

## 后续替换为 WebSocket

HTTP poll 是最小 demo 形态。后续替换成 WebSocket 时，应保留：

- `hardware.invoke.shell` 对外 RPC 方法名；
- JSON-RPC request/response envelope；
- gateway 执行器的 stdout/stderr/exitCode/timedOut 返回形态；
- audit/evidence 由 gateway/cloud 硬件通道产生的原则；
- cloud-web、agent 和 CLI 不直连 gateway 的边界。

只替换传输层：`/v1/gateway/poll` 和 `/v1/gateway/result` 合并到 gateway 主动建立的 `/v1/gateway/ws` 长连接。