feat(specs): sandbox snapshot specs (opensandbox-group#721)

Author: ninan-nn

sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/converter/SandboxModelConverter.kt

@@ -298,7 +298,10 @@ internal object SandboxModelConverter {
             entrypoint = this.entrypoint,
             expiresAt = this.expiresAt,
             createdAt = this.createdAt,
-            image = this.image.toImageSpec(),
+            image =
+                requireNotNull(this.image) {
+                    "Sandbox image is missing from API response. Snapshot-based sandbox responses are not supported by this SDK yet."
+                }.toImageSpec(),
             platform = this.platform?.toDomainPlatformSpec(),
             status = this.status.toSandboxStatus(),
             metadata = metadata,

specs/README.md

@@ -10,22 +10,27 @@ This directory contains OpenAPI specification documents for the OpenSandbox proj
 
 **Sandbox Lifecycle Management API**
 
-Defines the complete lifecycle interfaces for creating, managing, and destroying sandbox environments directly from container images.
+Defines the complete lifecycle interfaces for creating, managing, and destroying sandbox environments from container images or snapshots.
 
 **Core Features:**
 - **Sandbox Management**: Create, list, query, and delete sandbox instances with metadata filters and pagination
 - **State Control**: Pause and resume sandbox execution
 - **Lifecycle States**: Supports transitions across Pending → Running → Pausing → Paused → Stopping → Terminated, and error handling with `Failed`
-- **Resource & Runtime Configuration**: Specify CPU/memory/GPU resource limits, required `entrypoint`, environment variables, and opaque `extensions`
+- **Resource & Runtime Configuration**: Specify CPU/memory/GPU resource limits, image startup `entrypoint`, environment variables, and opaque `extensions`
 - **Image Support**: Create sandboxes from public or private registries, including registry auth
 - **Timeout Management**: Mandatory `timeout` on creation with explicit renewal via API
 - **Endpoint Access**: Retrieve public access endpoints for services running inside sandboxes
+- **Snapshot Management**: Create snapshots from sandboxes, list snapshots, and delete snapshots
 
 **Main Endpoints (base path `/v1`):**
-- `POST /sandboxes` - Create a sandbox from an image with timeout and resource limits
+- `POST /sandboxes` - Create a sandbox from an image or snapshot with timeout and resource limits
 - `GET /sandboxes` - List sandboxes with state/metadata filters and pagination
-- `GET /sandboxes/{sandboxId}` - Get full sandbox details (including image and entrypoint)
+- `GET /sandboxes/{sandboxId}` - Get full sandbox details (including startup source and entrypoint)
 - `DELETE /sandboxes/{sandboxId}` - Delete a sandbox
+- `POST /sandboxes/{sandboxId}/snapshots` - Create a snapshot from a sandbox
+- `GET /snapshots` - List snapshots with optional sandbox filtering and pagination
+- `GET /snapshots/{snapshotId}` - Get snapshot state and metadata
+- `DELETE /snapshots/{snapshotId}` - Delete a snapshot
 - `POST /sandboxes/{sandboxId}/pause` - Pause a sandbox (asynchronous)
 - `POST /sandboxes/{sandboxId}/resume` - Resume a paused sandbox
 - `POST /sandboxes/{sandboxId}/renew-expiration` - Renew sandbox expiration (TTL)

specs/README_zh.md

@@ -10,22 +10,27 @@
 
 **沙箱生命周期管理 API**
 
-定义了沙箱环境的创建、管理和销毁的完整生命周期接口，并可直接从容器镜像启动。
+定义了沙箱环境的创建、管理和销毁的完整生命周期接口，可从容器镜像创建或从快照恢复。
 
 **核心功能：**
 - **沙箱管理**：创建、列表、查询、删除沙箱实例，支持元数据过滤与分页
 - **状态控制**：暂停 (Pause)、恢复 (Resume) 沙箱执行
 - **生命周期**：支持 Pending → Running → Pausing → Paused → Stopping → Terminated，并包含错误态 `Failed`
-- **资源与运行时配置**：指定 CPU/内存/GPU 资源限制、必填 `entrypoint`、环境变量，以及自定义 `extensions`
+- **资源与运行时配置**：指定 CPU/内存/GPU 资源限制、镜像启动 `entrypoint`、环境变量，以及自定义 `extensions`
 - **镜像支持**：从公共或私有镜像仓库创建沙箱，支持私有仓库认证
 - **超时管理**：创建时必填 `timeout`，并可通过 API 续期
 - **端点访问**：获取沙箱内服务的公共访问端点
+- **快照管理**：从沙箱创建快照、列出快照、删除快照
 
 **主要端点（基础路径 `/v1`）：**
-- `POST /sandboxes` - 从镜像创建沙箱，设置超时与资源限制
+- `POST /sandboxes` - 从镜像或快照创建沙箱，设置超时与资源限制
 - `GET /sandboxes` - 列出沙箱，支持状态/元数据过滤与分页
-- `GET /sandboxes/{sandboxId}` - 获取完整沙箱详情（包含镜像与 entrypoint）
+- `GET /sandboxes/{sandboxId}` - 获取完整沙箱详情（包含启动来源与 entrypoint）
 - `DELETE /sandboxes/{sandboxId}` - 删除沙箱
+- `POST /sandboxes/{sandboxId}/snapshots` - 从沙箱创建快照
+- `GET /snapshots` - 列出快照，支持按沙箱过滤与分页
+- `GET /snapshots/{snapshotId}` - 获取快照状态与元数据
+- `DELETE /snapshots/{snapshotId}` - 删除快照
 - `POST /sandboxes/{sandboxId}/pause` - 异步暂停沙箱
 - `POST /sandboxes/{sandboxId}/resume` - 恢复已暂停的沙箱
 - `POST /sandboxes/{sandboxId}/renew-expiration` - 续期沙箱 TTL