[Feature] TCP over WebSocket

[Timandes]

Feature Category

• Sandbox
• Actions
• Deployments
• SDK & API
• Envhub
• CLI
• Performance & Optimization
• Documentation & Examples

Problem Statement
WebSocket TCP 端口代理服务

Proposed Solution

Detailed Feature Description

1. 目标

在 ROCK 沙箱代理服务层实现 WebSocket → TCP 端口代理，允许客户端通过 WebSocket 连接访问沙箱容器内监听的 TCP 端口。

2. URL 设计

┌────────────┬────────────────────────────────────────────────────┐
│ 项目 │ 规格 │
├────────────┼────────────────────────────────────────────────────┤
│ 端点路径 │ WS /sandboxes/{sandbox_id}/portforward?port={port} │
│ sandbox_id │ 沙箱实例的唯一标识符 │
│ port │ Query 参数，指定要代理的目标 TCP 端口号 │
└────────────┴────────────────────────────────────────────────────┘

示例：
ws://localhost:8080/sandboxes/abc123/portforward?port=8080

3. 数据传输

┌──────────┬──────────────────────────┐
│ 项目 │ 规格 │
├──────────┼──────────────────────────┤
│ 协议 │ WebSocket │
│ 数据格式 │ 二进制消息 │
│ 转发方式 │ 原样透传，不修改数据内容 │
└──────────┴──────────────────────────┘

4. 端口安全限制

┌──────────┬──────────────────────────────────────────────────────┐
│ 项目 │ 规格 │
├──────────┼──────────────────────────────────────────────────────┤
│ 允许范围 │ 1024-65535 │
│ 排除端口 │ 22 (SSH) │
│ 拒绝行为 │ 返回 HTTP 403 Forbidden（在 WebSocket Upgrade 之前） │
└──────────┴──────────────────────────────────────────────────────┘

5. 连接生命周期

┌────────────────┬────────────────────────────────────────────────────────────┐
│ 场景 │ 行为 │
├────────────────┼────────────────────────────────────────────────────────────┤
│ 连接建立 │ WebSocket 连接成功后，立即建立到目标 TCP 端口的连接 │
│ 一对一映射 │ 每个 WebSocket 连接对应一个独立的 TCP 连接 │
│ 多客户端 │ 多个 WebSocket 客户端连接同一端口，各自创建独立的 TCP 连接 │
│ TCP 断开 │ 关闭 WebSocket 连接 │
│ WebSocket 断开 │ 关闭 TCP 连接 │
└────────────────┴────────────────────────────────────────────────────────────┘

6. 超时配置

┌──────────────┬────────┬─────────────────────────────────────────┐
│ 超时类型 │ 时长 │ 说明 │
├──────────────┼────────┼─────────────────────────────────────────┤
│ TCP 连接超时 │ 10 秒 │ 建立到目标端口的 TCP 连接的最大等待时间 │
│ 空闲超时 │ 300 秒 │ 连接无数据传输后自动关闭 │
└──────────────┴────────┴─────────────────────────────────────────┘

7. 错误处理

┌──────────────────────────────┬───────────────────────────────────────────────────┐
│ 错误场景 │ 处理方式 │
├──────────────────────────────┼───────────────────────────────────────────────────┤
│ 端口不在允许范围 │ HTTP 403 Forbidden（Upgrade 前） │
│ 端口被排除（如 22） │ HTTP 403 Forbidden（Upgrade 前） │
│ TCP 连接超时 │ HTTP 504 Gateway Timeout（Upgrade 前） │
│ TCP 连接被拒绝（端口未监听） │ HTTP 502 Bad Gateway（Upgrade 前） │
│ 沙箱不存在 │ HTTP 404 Not Found（Upgrade 前） │
│ 传输中断 │ 关闭 WebSocket 连接，关闭码 1011 (Internal Error) │
└──────────────────────────────┴───────────────────────────────────────────────────┘

8. 实现位置

┌─────────────────────────────────────────────┬──────────────────────────────────┐
│ 文件 │ 修改内容 │
├─────────────────────────────────────────────┼──────────────────────────────────┤
│ rock/sandbox/service/sandbox_proxy_service.py │ 添加 websocket_to_tcp_proxy() 方法 │
│ rock/admin/entrypoints/sandbox_proxy_api.py │ 添加 WebSocket 路由端点 │
│ rock/common/constants.py │ 添加端口限制相关常量（如需要） │
└─────────────────────────────────────────────┴──────────────────────────────────┘

9. 认证授权

不需要额外的认证/授权机制。