@glodon-aiot/workspace-sandbox 0.2.0-alpha.1 → 0.2.0-alpha.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,68 +1,103 @@
1
1
  # @glodon-aiot/workspace-sandbox
2
2
 
3
- 供端侧宿主调用:在工程目录内读写文件,并在 Microsoft Execution Containers 里执行命令和脚本。
3
+ 供端侧宿主调用:在工程目录内读写文件,并在 Microsoft Execution Containers(MXC)里执行命令和脚本。
4
4
 
5
- 需要 Node.js 24。宿主启动本进程并转发请求。页面协议里没有本地绝对路径。
5
+ 需要 Node.js 24。生产接入使用协议 2:页面通过 WebSocket 直连本进程,宿主只管理进程并转发状态。文件字节和命令输出不经过宿主,页面也拿不到工程绝对路径。
6
6
 
7
- ## 启动
7
+ ## 生产接入
8
8
 
9
- 常驻模式。stdin 每行一个 JSON 请求,stdout 每行一个 JSON 响应,用 `id` 对应。不监听端口。
9
+ 宿主启动时绑定系统分配的回环端口,并把页面来源放进允许列表:
10
10
 
11
11
  ```bash
12
- workspace-sandbox --serve
12
+ workspace-sandbox --listen --root /path/to/project --origin https://app.example
13
13
  ```
14
14
 
15
- 文件操作可以同时进行。`exec` 和 `run_python` 一次只能跑一个,第二个返回 `AbortError`。
15
+ `--origin` 可以重复。沙箱只绑定 `127.0.0.1:0`,只提供 `ws://`,不提供 `wss://`。
16
16
 
17
- 也可以不带 `--serve`,把单个 JSON 写到 stdin,stdout 返回一个 JSON。
17
+ stdout 第一行是以下两种管理事件之一:
18
18
 
19
- ```bash
20
- workspace-sandbox --manifest
21
- workspace-sandbox --check
19
+ ```json
20
+ { "protocol": 2, "op": "ready", "url": "ws://127.0.0.1:53124", "token": "<64 位十六进制>", "pid": 1234 }
22
21
  ```
23
22
 
24
- `--manifest` 打印包名、版本、协议号、平台和 Node 版本。`--check` 在临时目录里跑 shell、Python、Node 和断网检查,失败时退出码为 1。
23
+ ```json
24
+ { "protocol": 2, "op": "fatal", "reason": "invalid-config", "message": "沙箱启动参数不正确。" }
25
+ ```
25
26
 
26
- ## root
27
+ `fatal.message` 不包含工程路径或令牌。`ready` 之后 stdout 只写 `status` 和 `bye`;宿主必须持续读取 stdout 和 stderr,避免管道堵塞。令牌不能写入宿主日志。
27
28
 
28
- `root` 由宿主写成自己选定的工程目录绝对路径。请求里的其他路径都相对这个目录。
29
+ 宿主把 `sandbox: { state, url, token, protocol }` 交给页面。页面建立连接后的第一帧必须是:
29
30
 
30
- 本进程信任 `root`。能往 stdin 写 JSON 的一方,可以在该目录里列出、读取、写入和删除。文件操作在本进程内完成,不进入隔离容器。
31
+ ```json
32
+ { "protocol": 2, "op": "auth", "token": "..." }
33
+ ```
31
34
 
32
- ## 请求
35
+ 认证成功后,文件和命令请求直接在页面与沙箱之间传输。WebSocket 不接受 `shutdown`、更换 `root` 或更换来源。
33
36
 
34
- `protocol` 可省略;写出时必须是 `1`。`op` 省略时按 `run_python` 处理。
37
+ ### 宿主只做什么
35
38
 
36
- 路径用 `/`,相对工程根。空字符串和 `.` 表示工程根。不能含 `..`、盘符、反斜杠或绝对路径。`input`、`output`、`uploads`、`tmp` 这些目录名不可用。
39
+ 1. 启动 `--listen --root --origin`,并把进程放进独立进程组或 Windows Job。
40
+ 2. 读取 `ready`,把地址、令牌和协议号交给页面。
41
+ 3. 可选地向 stdin 写 `{"op":"status"}`。
42
+ 4. 关闭工程时向 stdin 写 `{"op":"shutdown"}`;3 秒未退出则结束整个进程组。
43
+ 5. 监听异常退出并通知页面。文件操作和命令输出不在宿主中转。
37
44
 
38
- 成功时为 `{ "protocol": 1, "ok": true, ... }`。失败时为 `{ "protocol": 1, "ok": false, "name", "message" }`。`--serve` 下若请求带了字符串 `id`,响应里会原样带回。
45
+ 换工程或重启沙箱时必须使用新的端口和令牌。运行中的调用不会自动重放。
39
46
 
40
- | op | 请求字段 | 成功时多出的字段 |
41
- | --- | --- | --- |
42
- | `list` | `path` | `entries`:`{ name, kind: "file" \| "directory", size?, lastModified? }[]` |
43
- | `stat` | `path` | `entry`:同样的字段 |
44
- | `read` | `path` | `contentBase64`。单文件不超过 50 MB |
45
- | `write` | `path`、`contentBase64`、`createDirectories` | 无 |
46
- | `mkdir` | `path` | 无 |
47
- | `remove` | `path`、`recursive` | 无。非空目录要 `recursive: true` |
48
- | `move` | `from`、`to` | 无 |
49
- | `exec` | `cwd`、`command` 或 `argv`、`timeoutMs`、`python` | `exitCode`、`timedOut`、`stdout`、`stderr`、`cwd?` |
50
- | `run_python` | `script`、`args`、`timeoutMs`、`python` | `exitCode`、`timedOut`、`stdout`、`stderr`、`warnings` |
47
+ ### 页面要求
51
48
 
52
- `lastModified` 是 Unix 毫秒,`size` 是字节。`timeoutMs` 默认 20 秒,最大 120 秒。命令输出超过 16000 个字符会截断。
49
+ 帧格式是普通 WebSocket,不依赖 WebView、Qt 或某一种浏览器内核。页面只要能创建 WebSocket,就可以连接沙箱。
53
50
 
54
- `exec` 的 `command` 和 `argv` 二选一。`argv` 第一项只能是 `python3`、`node` 或 `sh`,第二项是工程内的脚本路径。Windows 上 `exec` 暂不可用。
51
+ - 页面能够连接 `ws://127.0.0.1:*`。页面策略限制连接地址时,把该地址加入允许列表。
52
+ - 握手带上的 Origin 与启动参数中的某个 `--origin` 完全一致。宿主把自己的页面来源传给沙箱。
53
+ - 某些嵌入环境会拦截公网页面对回环地址的访问。宿主只放行自己的页面访问 `127.0.0.1`,匹配来源的预检会返回 `Access-Control-Allow-Private-Network: true`。
54
+ - `file://` 页面的 Origin 通常是 `null`,只有调试时才使用 `--allow-null-origin`。
55
+ - SDK 只加载在可信页面中;同一页面里的脚本能够读取内存中的令牌。
55
56
 
56
- `run_python` 的 `script` 必须是工程内的 `.py` 相对路径。`python` 由宿主写成解释器的绝对路径。macOS 和 Linux 上可以省略,此时使用系统里的 `python3`。
57
+ ## 协议 2 数据面
57
58
 
58
- ```json
59
- { "id": "1", "protocol": 1, "op": "read", "root": "/path/to/project", "path": "notes/readme.txt" }
60
- ```
59
+ 文本帧是 UTF-8 JSON,最大 256 KB;文件内容使用二进制帧,单片载荷最大 1 MB。所有业务请求带客户端生成的字符串 `id`。
61
60
 
62
- ```json
63
- { "id": "2", "protocol": 1, "op": "exec", "root": "/path/to/project", "cwd": ".", "command": "python3 scripts/hello.py" }
61
+ | 操作 | 行为 |
62
+ | --- | --- |
63
+ | `list` / `stat` | 读取目录和文件元数据;目录最多返回 2000 项 |
64
+ | `read` | 按 `offset` / `maxBytes` 读取窗口,最大 50 MB |
65
+ | `write` | 先发大小和路径,再按偏移发送二进制片;同目录临时文件写完后原子替换 |
66
+ | `mkdir` / `remove` / `move` | 修改工程内文件和目录 |
67
+ | `exec` / `run_python` | 流式返回 `stdout` / `stderr`,最后发送 `exit` |
68
+ | `cancel` | 取消同一 `id` 的请求;命令会结束整个子进程树 |
69
+
70
+ 路径使用 `/`,只允许工程根内的相对路径。空字符串和 `.` 表示工程根;`..`、盘符、反斜杠和绝对路径会返回 `SecurityError`。请求中不能传入或替换 `root`。
71
+
72
+ 文件操作最多并发 8 个,其中写入最多 1 个。一个工程同时只运行一个 `exec` 或 `run_python`,第二个返回 `AbortError`。写入和待发送数据都使用 4 MB 背压窗口,不会无限堆积到内存。
73
+
74
+ 命令输出按累计 32 KB 或 50 ms 合并发送。SDK 观察结果仍限制为每个流最后 16000 字符;超出部分写到 `tmp/sandbox-exec/<id>.log`,日志最多 8 MB。每次新命令开始前会清理超过 24 小时的日志。
75
+
76
+ 文件覆盖使用临时文件和原子替换。宿主或其他程序正在修改/占用目标时,操作返回 `NoModificationAllowedError`,原文件保持不变。
77
+
78
+ ## 运行环境
79
+
80
+ 本进程:
81
+
82
+ - Node.js 24 或更新版本。
83
+ - 能在 `127.0.0.1` 上绑定系统分配的临时端口。只监听这个地址,不提供 `wss://`。
84
+ - 命令隔离依赖当前系统的容器能力:macOS 用 Seatbelt,Windows 用 ProcessContainer,Linux 用 Bubblewrap。Windows 上 `exec` 暂不可用。
85
+
86
+ ## 诊断
87
+
88
+ ```bash
89
+ workspace-sandbox --manifest
90
+ workspace-sandbox --check
64
91
  ```
65
92
 
93
+ `--manifest` 打印包名、版本、协议号、平台和 Node 版本。`--check` 在临时目录里跑 shell、Python、Node 和断网检查,失败时退出码为 1。
94
+
95
+ ## root
96
+
97
+ `root` 由宿主通过 `--root` 固定,WebSocket 请求不能携带或更换它。其他路径都相对这个目录。
98
+
99
+ 本进程信任宿主给出的 `root`。通过认证的数据面可以在该目录里列出、读取、写入和删除。文件操作在本进程内完成,不进入隔离容器。
100
+
66
101
  ## 命令隔离
67
102
 
68
103
  `exec` 和 `run_python` 在 Microsoft Execution Containers 里执行:macOS 用 Seatbelt,Windows 用 ProcessContainer,Linux 用 Bubblewrap。工程目录可读写。工程外的符号链接和出站网络会被拒绝。子进程不继承宿主的环境变量。返回的 `stdout`、`stderr` 和 `cwd` 里,工程真实路径换成相对路径,用户主目录换成 `~`。
@@ -1,29 +1,42 @@
1
1
  #!/usr/bin/env node
2
2
  import { manifest, selfCheck } from '../src/check.mjs';
3
- import { handleRequest, PROTOCOL } from '../src/request.mjs';
4
- import { runServe } from '../src/serve.mjs';
5
-
6
- function readStdin() {
7
- return new Promise((resolve, reject) => {
8
- let body = '';
9
- process.stdin.setEncoding('utf8');
10
- process.stdin.on('data', (chunk) => {
11
- body += chunk;
12
- });
13
- process.stdin.on('end', () => resolve(body));
14
- process.stdin.on('error', reject);
15
- });
16
- }
3
+ import { fatalLine, runListen } from '../src/listen.mjs';
17
4
 
18
5
  function optionValue(name) {
19
6
  const index = process.argv.indexOf(name);
20
7
  return index > 0 ? process.argv[index + 1] : undefined;
21
8
  }
22
9
 
10
+ function optionValues(name) {
11
+ const values = [];
12
+ for (let index = 0; index < process.argv.length; index += 1) {
13
+ if (process.argv[index] === name && process.argv[index + 1]) values.push(process.argv[index + 1]);
14
+ }
15
+ return values;
16
+ }
17
+
23
18
  let response;
24
- if (process.argv.includes('--serve')) {
25
- await runServe();
26
- process.exit(0);
19
+ if (process.argv.includes('--listen')) {
20
+ process.on('uncaughtException', () => {
21
+ process.stdout.write(`${JSON.stringify({ protocol: 2, op: 'bye', reason: 'fatal' })}\n`);
22
+ process.exit(1);
23
+ });
24
+ const root = optionValue('--root');
25
+ const origins = optionValues('--origin');
26
+ if (!root || origins.length === 0) {
27
+ process.stdout.write(`${JSON.stringify(fatalLine('invalid-config'))}\n`);
28
+ process.exit(1);
29
+ }
30
+ try {
31
+ const code = await runListen({
32
+ root,
33
+ origins,
34
+ allowNullOrigin: process.argv.includes('--allow-null-origin'),
35
+ });
36
+ process.exit(code || 0);
37
+ } catch {
38
+ process.exit(1);
39
+ }
27
40
  } else if (process.argv.includes('--manifest')) {
28
41
  response = manifest();
29
42
  } else if (process.argv.includes('--check')) {
@@ -37,14 +50,7 @@ if (process.argv.includes('--serve')) {
37
50
  }
38
51
  response = report;
39
52
  } else {
40
- let request;
41
- try {
42
- request = JSON.parse((await readStdin()) || '{}');
43
- } catch {
44
- request = undefined;
45
- }
46
- response = request
47
- ? await handleRequest(request)
48
- : { protocol: PROTOCOL, ok: false, name: 'TypeError', message: '请求不是合法的 JSON。' };
53
+ process.stdout.write(`${JSON.stringify(fatalLine('invalid-config'))}\n`);
54
+ process.exit(1);
49
55
  }
50
- process.stdout.write(JSON.stringify(response));
56
+ process.stdout.write(`${JSON.stringify(response)}\n`);
package/package.json CHANGED
@@ -1,12 +1,10 @@
1
1
  {
2
2
  "name": "@glodon-aiot/workspace-sandbox",
3
- "version": "0.2.0-alpha.1",
3
+ "version": "0.2.0-alpha.3",
4
4
  "description": "供端侧宿主调用:在工程目录内读写文件,并在 Microsoft Execution Containers 里执行命令和脚本。",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
- "bin": {
8
- "workspace-sandbox": "./bin/workspace-sandbox.mjs"
9
- },
7
+ "bin": "./bin/workspace-sandbox.mjs",
10
8
  "files": [
11
9
  "bin",
12
10
  "src"
@@ -19,7 +17,8 @@
19
17
  "bundle": "node scripts/bundle.mjs"
20
18
  },
21
19
  "dependencies": {
22
- "@microsoft/mxc-sdk": "1.0.1"
20
+ "@microsoft/mxc-sdk": "1.0.1",
21
+ "ws": "8.18.3"
23
22
  },
24
23
  "publishConfig": {
25
24
  "access": "public",
package/src/check.mjs CHANGED
@@ -1,7 +1,8 @@
1
1
  import { mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs';
2
2
  import { tmpdir } from 'node:os';
3
3
  import { join } from 'node:path';
4
- import { PROTOCOL, handleRequest } from './request.mjs';
4
+ import { runExec } from './exec.mjs';
5
+ import { LISTEN_PROTOCOL } from './listen.mjs';
5
6
  import { removeView } from './view.mjs';
6
7
 
7
8
  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
@@ -10,7 +11,7 @@ export function manifest() {
10
11
  return {
11
12
  name: pkg.name,
12
13
  version: pkg.version,
13
- protocol: PROTOCOL,
14
+ protocol: LISTEN_PROTOCOL,
14
15
  platform: `${process.platform}-${process.arch}`,
15
16
  node: process.versions.node,
16
17
  };
@@ -34,21 +35,25 @@ export async function selfCheck({ python } = {}) {
34
35
  try {
35
36
  const checks = [];
36
37
  for (const probe of PROBES) {
37
- const response = await handleRequest({
38
- protocol: PROTOCOL,
39
- op: 'exec',
40
- root,
41
- cwd: '.',
42
- command: probe.command,
43
- timeoutMs: 20_000,
44
- ...(python ? { python } : {}),
45
- });
46
- const passed = response.ok && response.exitCode === 0 && probe.expect.test(response.stdout);
47
- checks.push({
48
- name: probe.name,
49
- ok: passed,
50
- ...(passed ? {} : { detail: response.ok ? `${response.stdout}${response.stderr}`.trim() : response.message }),
51
- });
38
+ try {
39
+ const response = await runExec({
40
+ op: 'exec',
41
+ root,
42
+ rootReal: root,
43
+ cwd: '.',
44
+ command: probe.command,
45
+ timeoutMs: 20_000,
46
+ ...(python ? { python } : {}),
47
+ });
48
+ const passed = response.exitCode === 0 && probe.expect.test(response.stdout);
49
+ checks.push({
50
+ name: probe.name,
51
+ ok: passed,
52
+ ...(passed ? {} : { detail: `${response.stdout}${response.stderr}`.trim() }),
53
+ });
54
+ } catch (error) {
55
+ checks.push({ name: probe.name, ok: false, detail: error?.message || '检查失败。' });
56
+ }
52
57
  }
53
58
  return { ...manifest(), ok: checks.every((check) => check.ok), checks };
54
59
  } finally {
package/src/exec.mjs CHANGED
@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, statSync, sym
3
3
  import { tmpdir } from 'node:os';
4
4
  import { dirname, join } from 'node:path';
5
5
  import { sandboxEnvironment } from './environment.mjs';
6
- import { contained, selectContainment } from './mxc.mjs';
6
+ import { contained, selectContainment, spawnContained } from './mxc.mjs';
7
7
  import { defaultPython, installFailureResponse, preparePython } from './python.mjs';
8
8
  import {
9
9
  isSyntheticCwd,
@@ -19,6 +19,9 @@ import {
19
19
  import { ensureView, outputMappings, toRealCommand, toVirtualCwd, toVirtualText } from './view.mjs';
20
20
 
21
21
  const PROGRAMS = new Set(['python3', 'node', 'sh']);
22
+ const OUTPUT_CHUNK = 32 * 1024;
23
+ const OUTPUT_DELAY_MS = 50;
24
+ const STDERR_HOLDBACK = 4096;
22
25
 
23
26
  function shellPath() {
24
27
  return existsSync('/bin/bash') ? '/bin/bash' : '/bin/sh';
@@ -70,6 +73,99 @@ function runnerScript({ cwdPath, fallbackPath, commandFile, marker }) {
70
73
  ].join('\n');
71
74
  }
72
75
 
76
+ async function emitCoalesced(stream, onChunk) {
77
+ if (!stream) return '';
78
+ let pending = '';
79
+ let full = '';
80
+ let last = Date.now();
81
+ let timer;
82
+ let chain = Promise.resolve();
83
+ const flush = () => {
84
+ if (!pending) return;
85
+ last = Date.now();
86
+ const text = pending;
87
+ pending = '';
88
+ chain = chain.then(async () => {
89
+ for (let index = 0; index < text.length; index += OUTPUT_CHUNK) {
90
+ const piece = text.slice(index, index + OUTPUT_CHUNK);
91
+ full += piece;
92
+ await onChunk(piece);
93
+ }
94
+ });
95
+ };
96
+ const arm = () => {
97
+ if (timer || !pending) return;
98
+ timer = setTimeout(() => {
99
+ timer = undefined;
100
+ flush();
101
+ arm();
102
+ }, OUTPUT_DELAY_MS);
103
+ };
104
+ try {
105
+ for await (const chunk of stream) {
106
+ pending += Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
107
+ if (pending.length >= OUTPUT_CHUNK || Date.now() - last >= OUTPUT_DELAY_MS) {
108
+ if (timer) clearTimeout(timer);
109
+ timer = undefined;
110
+ flush();
111
+ } else arm();
112
+ }
113
+ } finally {
114
+ if (timer) clearTimeout(timer);
115
+ }
116
+ flush();
117
+ await chain;
118
+ return full;
119
+ }
120
+
121
+ async function streamExec({ containment, command, launch, request, mappings, marker, note }) {
122
+ const child = await spawnContained(containment, command, launch);
123
+ const abort = () => {
124
+ try {
125
+ child.kill();
126
+ } catch {
127
+ /* 进程已经结束。 */
128
+ }
129
+ };
130
+ if (request.signal?.aborted) abort();
131
+ else request.signal?.addEventListener('abort', abort, { once: true });
132
+ try {
133
+ child.standardInput?.end();
134
+ if (note) await request.onOutput('stderr', note);
135
+ const stdoutStream = child.standardOutput;
136
+ const stderrStream = child.standardError;
137
+ let held = '';
138
+ const [stdoutRaw, stderrRaw] = await Promise.all([
139
+ emitCoalesced(stdoutStream, (text) => request.onOutput('stdout', toVirtualText(text, mappings))),
140
+ emitCoalesced(stderrStream, async (text) => {
141
+ held += text;
142
+ if (held.length <= STDERR_HOLDBACK) return;
143
+ const emit = held.slice(0, held.length - STDERR_HOLDBACK);
144
+ held = held.slice(-STDERR_HOLDBACK);
145
+ await request.onOutput('stderr', toVirtualText(emit, mappings));
146
+ }),
147
+ ]);
148
+ const waited = await child.wait();
149
+ const { stderr: tail, pwd } = splitMarker(held, marker);
150
+ if (tail) await request.onOutput('stderr', toVirtualText(tail, mappings));
151
+ const { stderr } = splitMarker(stderrRaw, marker);
152
+ const cwd = pwd === undefined ? undefined : toVirtualCwd(pwd, { view: launch.workingDirectory, rootReal: request.rootReal });
153
+ return {
154
+ exitCode: waited.exitCode ?? 1,
155
+ timedOut: Boolean(waited.timedOut),
156
+ stdout: toVirtualText(stdoutRaw, mappings),
157
+ stderr: toVirtualText(`${note}${stderr}`, mappings),
158
+ ...(cwd ? { cwd } : {}),
159
+ };
160
+ } catch (error) {
161
+ abort();
162
+ if (request.signal?.aborted) throw sandboxError('AbortError', '已取消。');
163
+ throw error;
164
+ } finally {
165
+ request.signal?.removeEventListener('abort', abort);
166
+ }
167
+ }
168
+
73
169
  function splitMarker(stderr, marker) {
74
170
  const index = stderr.lastIndexOf(marker);
75
171
  if (index < 0) return { stderr, pwd: undefined };
@@ -111,7 +207,7 @@ export async function runExec(request) {
111
207
  marker,
112
208
  })
113
209
  );
114
- const result = await contained(containment, [shellPath(), runner].map(quoteArg).join(' '), {
210
+ const launch = {
115
211
  filesystem: {
116
212
  readonlyPaths: [view, dirname(dirname(process.execPath)), ...(python?.readonlyPaths ?? [])],
117
213
  readwritePaths: [request.rootReal, tmp],
@@ -123,8 +219,13 @@ export async function runExec(request) {
123
219
  }),
124
220
  timeoutMs: request.timeoutMs,
125
221
  workingDirectory: view,
126
- });
222
+ };
223
+ const command = [shellPath(), runner].map(quoteArg).join(' ');
127
224
  const mappings = outputMappings({ view, rootReal: request.rootReal, rootGiven: request.root });
225
+ if (typeof request.onOutput === 'function') {
226
+ return await streamExec({ containment, command, launch, request, mappings, marker, note: python?.note ?? '' });
227
+ }
228
+ const result = await contained(containment, command, launch);
128
229
  const { stderr, pwd } = splitMarker(result.stderr || '', marker);
129
230
  const cwd = pwd === undefined ? undefined : toVirtualCwd(pwd, { view, rootReal: request.rootReal });
130
231
  return {
package/src/files.mjs CHANGED
@@ -1,5 +1,4 @@
1
- import { randomBytes } from 'node:crypto';
2
- import { lstat, mkdir, readdir, readFile, realpath, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
1
+ import { lstat, mkdir, open, opendir, readdir, realpath, rename, rm, stat, unlink } from 'node:fs/promises';
3
2
  import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
4
3
  import { isSyntheticCwd, sandboxError, SYNTHETIC_DIR_MESSAGE } from './policy.mjs';
5
4
 
@@ -8,12 +7,8 @@ export const MAX_FILE_BYTES = 50 * 1024 * 1024;
8
7
 
9
8
  const DOM_ERROR = /^[A-Z][A-Za-z]+Error$/;
10
9
 
11
- export function assertWithinQuota(byteLength, limit = MAX_FILE_BYTES) {
12
- if (byteLength > limit) throw sandboxError('QuotaExceededError', '文件超过 50 MB。');
13
- }
14
-
15
10
  /** 页面传来的相对路径。空路径是工程根。拒绝绝对路径、盘符、反斜杠和 `..`。 */
16
- export function splitWorkspacePath(path) {
11
+ export function splitWorkspacePath(path, options = {}) {
17
12
  let rel = String(path ?? '').trim();
18
13
  if (rel === '.') rel = '';
19
14
  while (rel.startsWith('./')) rel = rel.slice(2);
@@ -25,7 +20,8 @@ export function splitWorkspacePath(path) {
25
20
  throw sandboxError('SecurityError', '路径必须是工程内的相对路径。');
26
21
  }
27
22
  if (parts.length > 0 && isSyntheticCwd(parts[0])) {
28
- throw sandboxError('NotAllowedError', SYNTHETIC_DIR_MESSAGE);
23
+ const execLog = options.allowExecLog === true && parts[0] === 'tmp' && parts[1] === 'sandbox-exec' && parts.length >= 3;
24
+ if (!execLog) throw sandboxError('NotAllowedError', SYNTHETIC_DIR_MESSAGE);
29
25
  }
30
26
  return parts;
31
27
  }
@@ -50,8 +46,8 @@ function asFileError(error) {
50
46
  * 逐段 realpath。已经存在的前缀必须落在工程根里,符号链接指向根外则拒绝。
51
47
  * 还不存在的部分接在最近的真实祖先后面,供写入和建目录使用。
52
48
  */
53
- export async function resolveWorkspacePath(rootReal, path) {
54
- const parts = splitWorkspacePath(path);
49
+ export async function resolveWorkspacePath(rootReal, path, options) {
50
+ const parts = splitWorkspacePath(path, options);
55
51
  let ancestor = rootReal;
56
52
  const missing = [];
57
53
  for (let index = 0; index < parts.length; index += 1) {
@@ -140,61 +136,6 @@ async function listOp(request) {
140
136
  return { entries };
141
137
  }
142
138
 
143
- async function readOp(request, maxBytes) {
144
- const real = await resolveWorkspacePath(request.rootReal, request.path);
145
- let info;
146
- try {
147
- info = await stat(real);
148
- } catch (error) {
149
- if (error?.code === 'ENOENT') throw sandboxError('NotFoundError', '目标不存在。');
150
- throw error;
151
- }
152
- if (info.isDirectory()) throw sandboxError('TypeMismatchError', '不是文件。');
153
- assertWithinQuota(info.size, maxBytes);
154
- const bytes = await readFile(real);
155
- return { contentBase64: Buffer.from(bytes).toString('base64') };
156
- }
157
-
158
- async function ensureParent(real, createDirectories) {
159
- const parent = dirname(real);
160
- let info;
161
- try {
162
- info = await stat(parent);
163
- } catch (error) {
164
- if (error?.code !== 'ENOENT') throw error;
165
- }
166
- if (info?.isDirectory()) return parent;
167
- if (info || !createDirectories) throw sandboxError('NotFoundError', '父目录不存在。');
168
- await mkdir(parent, { recursive: true });
169
- return parent;
170
- }
171
-
172
- async function writeOp(request, maxBytes) {
173
- if (request.contentBase64 !== undefined && typeof request.contentBase64 !== 'string') {
174
- throw sandboxError('TypeError', 'contentBase64 必须是字符串。');
175
- }
176
- const real = await resolveWorkspacePath(request.rootReal, request.path);
177
- let existing;
178
- try {
179
- existing = await stat(real);
180
- } catch (error) {
181
- if (error?.code !== 'ENOENT') throw error;
182
- }
183
- if (existing?.isDirectory()) throw sandboxError('TypeMismatchError', '不能把目录当文件写。');
184
- const parent = await ensureParent(real, request.createDirectories === true);
185
- const bytes = Buffer.from(request.contentBase64 ?? '', 'base64');
186
- assertWithinQuota(bytes.length, maxBytes);
187
- const temporary = join(parent, `.${basename(real)}.${randomBytes(6).toString('hex')}.tmp`);
188
- try {
189
- await writeFile(temporary, bytes);
190
- await rename(temporary, real);
191
- } catch (error) {
192
- await unlink(temporary).catch(() => undefined);
193
- throw error;
194
- }
195
- return {};
196
- }
197
-
198
139
  async function mkdirOp(request) {
199
140
  const real = await resolveWorkspacePath(request.rootReal, request.path);
200
141
  try {
@@ -264,11 +205,103 @@ async function moveOp(request) {
264
205
  return {};
265
206
  }
266
207
 
208
+ const LOG_PATH = { allowExecLog: true };
209
+ const READ_RETRY_MS = [0, 20, 50, 100];
210
+
211
+ function sleep(ms) {
212
+ return new Promise((resolve) => setTimeout(resolve, ms));
213
+ }
214
+
215
+ export function isSharingConflict(error) {
216
+ return error?.code === 'EBUSY' || error?.code === 'ETXTBSY' || error?.code === 'EAGAIN';
217
+ }
218
+
219
+ /** 按偏移读取窗口,不把整个文件读进一个缓冲区。文件在读取期间变化时最多再试 3 次。 */
220
+ export async function readFileWindow(rootReal, path, offset, maxBytes) {
221
+ if (!Number.isInteger(offset) || offset < 0) throw sandboxError('TypeError', 'offset 必须是非负整数。');
222
+ if (!Number.isInteger(maxBytes) || maxBytes < 0) throw sandboxError('TypeError', 'maxBytes 必须是非负整数。');
223
+ if (maxBytes > MAX_FILE_BYTES) throw sandboxError('QuotaExceededError', '文件超过 50 MB。');
224
+ const real = await resolveWorkspacePath(rootReal, path, LOG_PATH);
225
+ for (let attempt = 0; attempt < READ_RETRY_MS.length; attempt += 1) {
226
+ if (READ_RETRY_MS[attempt] > 0) await sleep(READ_RETRY_MS[attempt]);
227
+ let before;
228
+ try {
229
+ before = await stat(real);
230
+ } catch (error) {
231
+ if (error?.code === 'ENOENT') throw sandboxError('NotFoundError', '目标不存在。');
232
+ if (isSharingConflict(error)) throw sandboxError('NoModificationAllowedError', '文件正在被其他程序修改。');
233
+ throw error;
234
+ }
235
+ if (before.isDirectory()) throw sandboxError('TypeMismatchError', '不是文件。');
236
+ const length = Math.min(maxBytes, Math.max(0, before.size - offset));
237
+ const handle = await open(real, 'r');
238
+ let bytes;
239
+ try {
240
+ bytes = Buffer.alloc(length);
241
+ if (length > 0) await handle.read(bytes, 0, length, offset);
242
+ } finally {
243
+ await handle.close();
244
+ }
245
+ const after = await stat(real);
246
+ if (before.size === after.size && before.mtimeMs === after.mtimeMs) {
247
+ return { bytes, size: after.size, offset, returned: bytes.length };
248
+ }
249
+ }
250
+ throw sandboxError('NoModificationAllowedError', '文件正在被其他程序修改。');
251
+ }
252
+
253
+ /** 目录流最多取 limit 项。超出时不再 stat 其余条目。 */
254
+ export async function listLimited(rootReal, path, limit = 2000) {
255
+ const real = await resolveWorkspacePath(rootReal, path);
256
+ let info;
257
+ try {
258
+ info = await stat(real);
259
+ } catch (error) {
260
+ if (error?.code === 'ENOENT') throw sandboxError('NotFoundError', '目标不存在。');
261
+ throw error;
262
+ }
263
+ if (!info.isDirectory()) throw sandboxError('TypeMismatchError', '不是目录。');
264
+ const dir = await opendir(real);
265
+ const names = [];
266
+ let truncated = false;
267
+ try {
268
+ for await (const child of dir) {
269
+ if (names.length === limit) {
270
+ truncated = true;
271
+ break;
272
+ }
273
+ names.push(child.name);
274
+ }
275
+ } finally {
276
+ await dir.close().catch(() => undefined);
277
+ }
278
+ names.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
279
+ const entries = [];
280
+ for (const name of names) {
281
+ const childPath = join(real, name);
282
+ let realChild;
283
+ try {
284
+ realChild = await realpath(childPath);
285
+ } catch {
286
+ entries.push({ name, kind: 'file' });
287
+ continue;
288
+ }
289
+ if (escapesRoot(rootReal, realChild)) continue;
290
+ let childInfo;
291
+ try {
292
+ childInfo = await stat(realChild);
293
+ } catch {
294
+ entries.push({ name, kind: 'file' });
295
+ continue;
296
+ }
297
+ entries.push(entryFor(name, childInfo));
298
+ }
299
+ return truncated ? { entries, truncated: true } : { entries };
300
+ }
301
+
267
302
  const OPERATIONS = {
268
303
  stat: statOp,
269
304
  list: listOp,
270
- read: readOp,
271
- write: writeOp,
272
305
  mkdir: mkdirOp,
273
306
  remove: removeOp,
274
307
  move: moveOp,
@@ -276,13 +309,12 @@ const OPERATIONS = {
276
309
 
277
310
  /**
278
311
  * 工程目录内的文件操作。不进入 MXC,由调用方保证 rootReal 是真实工程根。
279
- * limits 只给测试收紧配额,协议请求里没有这个字段。
280
312
  */
281
- export async function runFileOp(request, limits = {}) {
313
+ export async function runFileOp(request) {
282
314
  const operation = OPERATIONS[request.op];
283
315
  if (!operation) throw sandboxError('NotSupportedError', `不支持的操作 ${String(request.op)}。`);
284
316
  try {
285
- return await operation(request, limits.maxBytes ?? MAX_FILE_BYTES);
317
+ return await operation(request);
286
318
  } catch (error) {
287
319
  throw asFileError(error);
288
320
  }