Codex
54 lines
4.9 KiB
Markdown
54 lines
4.9 KiB
Markdown
# v0.2 hwlab-device-pod 服务规格
|
|
|
|
本文描述 v02 中 `hwlab-device-pod` 微服务的部署和接口实现。逻辑 device-pod、profile authority、grant 和 job 模型的权威规格见 [spec-device-pod.md](spec-device-pod.md)。
|
|
|
|
## 在系统中的职责划分
|
|
|
|
- 承接 `cloud-api -> hwlab-device-pod -> gateway/device-host-cli` 的内部执行服务位置。
|
|
- 当前阶段只暴露 device-pod executor 边界；用户、profile、grant、lease 和 job authority 都在 `hwlab-cloud-api`，不能由该 Service 伪造或兜底。
|
|
- 普通用户和 Code Agent 不应直接调用该 Service；正式路径必须经过 `hwlab-cloud-api` 鉴权、grant 和 lease。
|
|
|
|
## 内部架构
|
|
|
|
- `cmd/hwlab-device-pod/main.ts` 提供 HTTP server，端口默认 `7601`。
|
|
- `cmd/hwlab-device-pod/main.ts` 返回 `contractVersion=device-pod-executor-v1`，并声明 `authority=hwlab-cloud-api`、`fake=false`。
|
|
- `internal/device-pod/fake-data.mjs` 只保留为 legacy 前端/smoke fixture，不是 `hwlab-device-pod` 服务运行契约。
|
|
- `HWLAB_DEVICE_POD_ID` 可指定默认 executor devicePodId；正式 profile 仍由 `hwlab-cloud-api` 的 `device_pods.profile_json` 管理。
|
|
- `HWLAB_CLOUD_API_INTERNAL_URL` 配置后，executor 可用内部服务凭据回调 `hwlab-cloud-api` 的 gateway dispatch route，把已授权 job 下发到 gateway/device-host-cli；内部 job 和 dispatch 必须同时携带 `x-hwlab-internal-service` 与 `HWLAB_DEVICE_POD_INTERNAL_TOKEN` 对应的 `x-hwlab-internal-token`。未配置内部 token、profile route 缺失或 gateway 不在线时返回 blocker/拒绝执行。
|
|
- `hwlab-cloud-api` 的用户态 device-pod job/probe 必须经 `HWLAB_DEVICE_POD_URL` 指向的 `hwlab-device-pod` executor；未配置 executor 时只创建 blocked job 并返回 `device_pod_executor_unavailable`，不得直接绕过 executor 调用 gateway/device-host-cli。
|
|
|
|
## API 接口说明
|
|
|
|
| 接口 | 说明 |
|
|
| --- | --- |
|
|
| `GET /health`、`GET /health/live` | 返回 `contractVersion=device-pod-executor-v1`、`authority=hwlab-cloud-api` 和 `fake=false`。 |
|
|
| `GET /v1/device-pods` | 返回 executor boundary 摘要，不表达用户可见 device pod authority。 |
|
|
| `GET /v1/device-pods/{devicePodId}/status` | 返回 blocked executor status；真实 profile/status 以 cloud-api `/v1/device-pods/{devicePodId}/status` 为准。 |
|
|
| `GET /v1/device-pods/{devicePodId}/events` | 返回 bounded executor boundary event，不伪造硬件事件。 |
|
|
| `POST /v1/device-pods/{devicePodId}/jobs` | 只接受带内部 token 的 `hwlab-cloud-api` 调用；创建内部 executor job 并返回 job、freshness、output/cancel URL；有可用 profile route 和 `HWLAB_CLOUD_API_INTERNAL_URL` 时通过 cloud-api gateway dispatch 下发到 device-host-cli，否则返回 `gateway_dispatch_unavailable`。 |
|
|
| `GET /v1/device-pods/{devicePodId}/jobs/{jobId}`、`GET /output`、`POST /cancel` | 只接受带内部 token 的 `hwlab-cloud-api` 调用，用于查询内部 job、最大 12000 bytes 的 bounded output 和取消非终态 job；普通用户仍必须走 cloud-api 用户态 API。 |
|
|
|
|
用户态 `POST /jobs`、job output/cancel、admin profile/grant API 和正式 `device-pod-cli` REST 调用由 `hwlab-cloud-api` 实现，应以 [spec-device-pod.md](spec-device-pod.md) 为目标。`hwlab-device-pod` 不接受 CLI、浏览器或 Code Agent 直接上传 profile snapshot。
|
|
|
|
## 测试规格
|
|
|
|
## T1
|
|
|
|
阅读 docs/reference/spec-v02-hwlab-device-pod-service.md，然后用 cli 手动测试以下内容：访问 `/health/live` 和 `/v1/device-pods`，确认响应包含 `contractVersion=device-pod-executor-v1`、`authority=hwlab-cloud-api` 和 `fake=false`。
|
|
|
|
## T2
|
|
|
|
阅读 docs/reference/spec-v02-hwlab-device-pod-service.md，然后用 cli 手动测试以下内容：通过 `hwlab-cloud-api /v1/device-pods` 访问 device pod authority，确认未登录返回认证错误，登录后只返回 actor 可见 device pod。
|
|
|
|
## 规格的实现情况
|
|
|
|
| 规格项 | 状态 | 说明 |
|
|
| --- | --- | --- |
|
|
| health 和 executor boundary REST | 已实现 | 服务声明内部 executor、cloud-api authority 和非 fake 来源。 |
|
|
| bounded events/status | 已实现 | 只返回 executor boundary/blocker，不伪造硬件事件。 |
|
|
| 正式 profile authority | 已在 cloud-api 实现 | `hwlab-device-pod` 不读取或覆盖 `device_pods.profile_json`。 |
|
|
| job lifecycle | 部分实现 | 用户态 job 由 cloud-api 鉴权、授权、lease 校验和持久化；executor 侧已提供内部 job create/get/output/cancel lifecycle，并能把 job dispatch 结果写回 bounded output。 |
|
|
| gateway/device-host-cli adapter | 部分实现 | executor 已通过 cloud-api internal dispatch 接入 gateway poll/result 和 device-host-cli 命令映射；真实执行仍依赖 profile route、在线 gateway 和 host CLI。 |
|
|
| device-pod-cli REST authority | 已实现 | `tools/device-pod-cli.ts` 默认只走 cloud-api REST，不读取 `.device-pod/*.json` 作为 profile authority；旧 `.mjs` 入口只负责启动 TypeScript CLI。 |
|
|
|