# v0.2 hwlab-gateway 服务规格

`hwlab-gateway` 是 v02 的真实硬件/host transport 边界服务，内部端口 `7001`。它用于 gateway 主动出站 demo 和受控 shell dispatch，不是普通用户或前端可直连的硬件 API。

## 在系统中的职责划分

- 向 `hwlab-cloud-api` 注册 gateway session、resource 和 capability。
- 通过主动轮询 `/v1/gateway/poll` 获取 cloud-api 分发的 `hardware.invoke.shell` 请求，并把结果回传 `/v1/gateway/result`。
- 只做 transport 和 bounded command execution，不理解用户权限、device-pod grant 或业务授权。

## 内部架构

- `cmd/hwlab-gateway/main.ts` 维护 gateway state、outbound poll loop、inflight request map 和 command execution，运行入口必须使用 Bun。
- `internal/cloud/gateway-demo-registry.ts` 在 cloud-api 内保存 gateway session、队列和 pending result。
- command execution 默认关闭；只有显式 `HWLAB_GATEWAY_CMD_EXEC_ENABLED=1` 或 demo open 时才执行 shell。

## API 接口说明

| 接口 | 说明 |
| --- | --- |
| `GET /health/live` | 返回 gateway health、gatewayId、gatewaySessionId 和 outboundConnected。 |
| `GET /status` | 返回 session、registry、outbound poll 和 inflight 摘要。 |
| `GET /capabilities` | 返回 resource/capability 列表。 |
| `POST cloud-api /v1/gateway/poll` | gateway 主动向 cloud-api 取任务。 |
| `POST cloud-api /v1/gateway/result` | gateway 回传 JSON-RPC response。 |

## 测试规格

## T1

阅读 docs/reference/spec-v02-hwlab-gateway.md，然后用 cli 手动测试以下内容：访问 gateway `/health/live` 和 `/status`，确认 gatewaySessionId、resourceId、capability 列表存在，且 command execution 状态清晰。

## T2

阅读 docs/reference/spec-v02-hwlab-gateway.md，然后用 cli 手动测试以下内容：通过 cloud-api `/v1/gateway/sessions` 观察 gateway online/stale 状态；不要直接从前端或普通用户请求 gateway shell。

## 规格的实现情况

| 规格项 | 状态 | 说明 |
| --- | --- | --- |
| health/status/capabilities | 已实现 | gateway service 提供只读观测。 |
| outbound poll/result | 已实现 | 与 cloud-api registry 对接。 |
| bounded shell execution | 已实现 | 受 env 开关、timeout 和 output limit 约束。 |
| device-pod grant/lease | 不在本服务 | 由 cloud-api/device-pod 负责。 |
| 生产级 gateway 多租户隔离 | 未完全实现 | 当前是 demo/transport skeleton。 |