Skip to content

feat(blaze)!: remove legacy instance routes #2585

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
WeissonHan merged 1 commit into from
Aug 17, 2026
+227 −389
Merged

feat(blaze)!: remove legacy instance routes #2585

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs/user-guide/en/runtime/blaze.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,13 @@ the affected sandbox ID. Blaze leaves the rejected record in place. Repair or
restore that record, then restart the service and confirm that `/v1/health`
responds.

## Sandbox API

Blaze exposes sandbox lifecycle and guest operations under `/v1/sandboxes`.
Clients use this namespace to list, create, inspect, and delete sandboxes and
to execute commands, read files, and write files inside them. Sandbox
destruction uses `DELETE /v1/sandboxes/{id}`.

## Host Integration Boundary

Blaze configures the sandbox-local network path. Routing beyond the host and DNS
Expand All @@ -96,7 +103,7 @@ option in production, configure the required upstream routing or translation
and verify guest connectivity for the host environment.

To disable the capability, set `enable_network = false` or remove the key, then
destroy existing network-enabled sandboxes through the normal instance API.
destroy existing network-enabled sandboxes through the sandbox API.

## Guest Operations

Expand All @@ -116,7 +123,6 @@ The sandbox routes are:
- `POST /v1/sandboxes/{id}/read` — read one file; and
- `POST /v1/sandboxes/{id}/write` — replace one file.

The corresponding `/v1/instances/{id}/...` routes provide the same behavior.
Exec requests use the following shape:

```json
Expand Down Expand Up @@ -153,13 +159,7 @@ Leave `listen.http_addr` disabled in production until
Daemon shutdown also does not yet wait for every active HTTP handler or release
all runtime owners, so an in-flight request may observe a closed connection.

## Reset and Reusable-Instance Management

`POST /v1/instances/{id}/reset` does not report success until Blaze can reset
both runtime and storage. A malformed identifier returns HTTP 400, an unknown
instance returns HTTP 404, an instance that is not running returns HTTP 422,
and a running instance returns HTTP 501 without changing its state or owned
resources.
## Reusable-Instance Management

The four `/v1/pools` management routes also return HTTP 501. Blaze rejects
`storage.pool_size`, `storage.prefork`, and every `[pool]` section except the
Expand Down
17 changes: 9 additions & 8 deletions docs/user-guide/zh/runtime/blaze.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,14 +74,20 @@ Blaze 会在绑定 Unix listener 或可选 TCP listener 之前完成清单校验
ID。Blaze 会保留被拒绝的记录。修复或恢复该记录后，重新启动 service，并确认
`/v1/health` 可以响应。

## 沙箱 API

Blaze 通过 `/v1/sandboxes` 提供沙箱生命周期和客户机操作。客户端使用该
命名空间列出、创建、查看和删除沙箱，以及在沙箱内执行命令、读取文件和写入
文件。销毁沙箱使用 `DELETE /v1/sandboxes/{id}`。

## 主机集成边界

Blaze 负责配置 sandbox 本地的网络路径。主机以外的路由和 DNS 仍由主机运维方
负责。生产环境开启该选项前，需要配置所需的上游路由或地址转换，并在目标主机
环境中验证 guest 连通性。

如需关闭该能力，将 `enable_network` 设置为 `false` 或删除该配置项，再通过
正常的 instance API 销毁已经启用网络的 sandbox。
沙箱 API 销毁已经启用网络的 sandbox。

## Guest 操作

Expand All @@ -99,7 +105,7 @@ Sandbox 路由包括：
- `POST /v1/sandboxes/{id}/read` — 读取一个文件；
- `POST /v1/sandboxes/{id}/write` — 替换一个文件。

对应的 `/v1/instances/{id}/...` 路由提供相同行为。Exec 请求格式如下：
Exec 请求格式如下：

```json
{"cmd":"uname -a","cwd":"/","env":{"LANG":"C"},"timeout":10}
Expand Down Expand Up @@ -130,12 +136,7 @@ read 响应过大时返回 HTTP 502 和
保持 `listen.http_addr` 关闭。Daemon 停止时也不会等待全部 HTTP handler 或
释放所有 runtime owner，因此正在执行的请求可能看到连接关闭。

## 重置与可复用实例管理

在 Blaze 能够同时重置运行环境和存储之前，
`POST /v1/instances/{id}/reset` 不会返回成功。实例编号格式错误时返回
HTTP 400，实例不存在时返回 HTTP 404，实例不处于运行状态时返回 HTTP 422，
运行中的实例返回 HTTP 501，且不会改变其状态或已占用资源。
## 可复用实例管理

四个 `/v1/pools` 管理接口同样返回 HTTP 501。`storage.pool_size` 和
`storage.prefork` 始终会被拒绝；除历史软件包的精确默认值外，任何 `[pool]`
Expand Down
27 changes: 6 additions & 21 deletions src/blaze/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,8 @@ for configuration, selection, retry, and worker shutdown behavior.

## API Endpoints

Blaze exposes sandbox lifecycle and guest operations through `/v1/sandboxes`.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/health` | Health check |
Expand All @@ -146,16 +148,6 @@ for configuration, selection, retry, and worker shutdown behavior.
| POST | `/v1/sandboxes/{id}/exec` | Execute a guest command |
| POST | `/v1/sandboxes/{id}/read` | Read a guest file |
| POST | `/v1/sandboxes/{id}/write` | Replace a guest file |
| GET | `/v1/instances` | Alias for listing sandboxes |
| POST | `/v1/instances` | Alias for creating a sandbox |
| GET | `/v1/instances/{id}` | Alias for sandbox details |
| DELETE | `/v1/instances/{id}` | Alias for destroying a sandbox |
| POST | `/v1/instances/{id}/destroy` | Compatible destroy action |
| POST | `/v1/instances/{id}/exec` | Compatible guest command action |
| POST | `/v1/instances/{id}/read` | Compatible guest file read action |
| POST | `/v1/instances/{id}/write` | Compatible guest file write action |
| POST | `/v1/instances/{id}/checkpoint` | Record checkpoint state |
| POST | `/v1/instances/{id}/reset` | Reserved for running instances; returns `501` until runtime and storage reset are implemented |
| GET | `/v1/pools` | Reserved; returns `501` |
| GET | `/v1/pools/{backend}/{class}` | Reserved; returns `501` |
| POST | `/v1/pools/{backend}/{class}/drain` | Reserved; returns `501` |
Expand All @@ -168,13 +160,6 @@ for configuration, selection, retry, and worker shutdown behavior.
| GET | `/v1/metrics` | Prometheus metrics |
| POST | `/v1/admin/reload` | Hot-reload policies |

For reset requests, a malformed instance identifier returns `400`, an unknown
instance returns `404`, and an instance that is not running returns `422`. A
running instance returns `501` without changing its lifecycle state or its
runtime and storage resources. Clients that require a fresh sandbox must
successfully destroy the old sandbox and create a new one; `501` does not mean
that reset completed.

Upgrade compatibility accepts and ignores only this exact daemon section:

```toml
Expand Down Expand Up @@ -251,10 +236,10 @@ cleanup, and failure boundaries.
The operation journal records the operation and start time, not completion of
each resource step. An interrupted create is cleaned up rather than resumed,
and an existing backend process is not adopted after restart. Failed recovery
does not run in a background retry loop. The checkpoint endpoint retains its
existing metadata transition. Reset remains unavailable until runtime and
storage can be reset together; this recovery flow does not add backend snapshot
or restore operations.
does not run in a background retry loop. Checkpoint capture and restore are not
available in this change. Reset remains unavailable until runtime and storage
can be reset together; this recovery flow does not add backend snapshot,
capture, or restore operations.

### Guest operations

Expand Down
23 changes: 5 additions & 18 deletions src/blaze/README_zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,8 @@ lock 和唯一的同步许可直至完成；后续同步会被推迟而不会不

## API 端点

Blaze 通过 `/v1/sandboxes` 提供沙箱生命周期和客户机操作。

| 方法 | 路径 | 说明 |
|--------|------|-------------|
| GET | `/v1/health` | 健康检查 |
Expand All @@ -137,16 +139,6 @@ lock 和唯一的同步许可直至完成；后续同步会被推迟而不会不
| POST | `/v1/sandboxes/{id}/exec` | 执行 guest 命令 |
| POST | `/v1/sandboxes/{id}/read` | 读取 guest 文件 |
| POST | `/v1/sandboxes/{id}/write` | 替换 guest 文件 |
| GET | `/v1/instances` | 列出 sandbox 的兼容入口 |
| POST | `/v1/instances` | 创建 sandbox 的兼容入口 |
| GET | `/v1/instances/{id}` | 获取 sandbox 详情的兼容入口 |
| DELETE | `/v1/instances/{id}` | 销毁 sandbox 的兼容入口 |
| POST | `/v1/instances/{id}/destroy` | 保留的销毁 action |
| POST | `/v1/instances/{id}/exec` | Guest 命令兼容入口 |
| POST | `/v1/instances/{id}/read` | Guest 文件读取兼容入口 |
| POST | `/v1/instances/{id}/write` | Guest 文件写入兼容入口 |
| POST | `/v1/instances/{id}/checkpoint` | 记录 checkpoint 状态 |
| POST | `/v1/instances/{id}/reset` | 运行中实例的预留接口；运行时和存储重置实现前返回 `501` |
| GET | `/v1/pools` | 预留接口；返回 `501` |
| GET | `/v1/pools/{backend}/{class}` | 预留接口；返回 `501` |
| POST | `/v1/pools/{backend}/{class}/drain` | 预留接口；返回 `501` |
Expand All @@ -159,11 +151,6 @@ lock 和唯一的同步许可直至完成；后续同步会被推迟而不会不
| GET | `/v1/metrics` | Prometheus 指标 |
| POST | `/v1/admin/reload` | 热加载策略 |

重置请求中的实例编号格式错误时返回 `400`，实例不存在时返回 `404`，实例
不处于运行状态时返回 `422`。运行中的实例返回 `501`，且不会改变其生命周期
状态，也不会改变其运行环境和存储资源。需要全新沙箱的客户端必须先成功销毁
旧沙箱，再创建新沙箱；`501` 不表示重置已经完成。

升级兼容仅接受并忽略以下内容完全一致的 daemon `[pool]` 配置段：

```toml
Expand Down Expand Up @@ -224,9 +211,9 @@ daemon 才会逐个处理未结束的 sandbox。后续逐项恢复期间，如

操作记录只保存操作类型和开始时间，不记录每个资源步骤是否已经完成。中断的
创建会被清理而不是从原位置继续，重启后也不会接管先前的后端进程。恢复失败
后目前没有后台循环自动重试。检查点接口保持原有的元数据状态变化。重置接口
在运行环境和存储能够一起重置前不可用；这里的恢复流程没有增加后端快照或
恢复操作。
后目前没有后台循环自动重试。本次变更不提供检查点捕获或恢复。重置接口在
运行环境和存储能够一起重置前不可用；这里的恢复流程没有增加后端快照、捕获
或恢复操作。

### Guest 操作

Expand Down
Loading
Loading