@alibaba-group/opensandbox 0.1.4 → 0.1.6

package/README.md

@@ -55,7 +55,10 @@ try {
   await sandbox.close();
 } catch (err) {
   if (err instanceof SandboxException) {
-    console.error(`Sandbox Error: [${err.error.code}] ${err.error.message ?? ""}`);
+    console.error(
+      `Sandbox Error: [${err.error.code}] ${err.error.message ?? ""}`,
+    );
+    console.error(`Request ID: ${err.requestId ?? "N/A"}`);
   } else {
     console.error(err);
   }
@@ -72,7 +75,7 @@ Manage the sandbox lifecycle, including renewal, pausing, and resuming.
 const info = await sandbox.getInfo();
 console.log("State:", info.status.state);
 console.log("Created:", info.createdAt);
-console.log("Expires:", info.expiresAt);
+console.log("Expires:", info.expiresAt); // null when manual cleanup mode is used
 
 await sandbox.pause();
 
@@ -83,6 +86,16 @@ const resumed = await sandbox.resume();
 await resumed.renew(30 * 60);
 ```
 
+Create a non-expiring sandbox by passing `timeoutSeconds: null`:
+
+```ts
+const manual = await Sandbox.create({
+  connectionConfig: config,
+  image: "ubuntu",
+  timeoutSeconds: null,
+});
+```
+
 ### 2. Custom Health Check
 
 Define custom logic to determine whether the sandbox is ready/healthy. This overrides the default ping check used during readiness checks.
@@ -109,7 +122,8 @@ import type { ExecutionHandlers } from "@alibaba-group/opensandbox";
 const handlers: ExecutionHandlers = {
   onStdout: (m) => console.log("STDOUT:", m.text),
   onStderr: (m) => console.error("STDERR:", m.text),
-  onExecutionComplete: (c) => console.log("Finished in", c.executionTimeMs, "ms"),
+  onExecutionComplete: (c) =>
+    console.log("Finished in", c.executionTimeMs, "ms"),
 };
 
 await sandbox.commands.run(
@@ -124,16 +138,19 @@ await sandbox.commands.run(
 Manage files and directories, including read, write, list/search, and delete.
 
 ```ts
-await sandbox.files.createDirectories([{ path: "/tmp/demo", mode: 0o755 }]);
+await sandbox.files.createDirectories([{ path: "/tmp/demo", mode: 755 }]);
 
 await sandbox.files.writeFiles([
-  { path: "/tmp/demo/hello.txt", data: "Hello World", mode: 0o644 },
+  { path: "/tmp/demo/hello.txt", data: "Hello World", mode: 644 },
 ]);
 
 const content = await sandbox.files.readFile("/tmp/demo/hello.txt");
 console.log("Content:", content);
 
-const files = await sandbox.files.search({ path: "/tmp/demo", pattern: "*.txt" });
+const files = await sandbox.files.search({
+  path: "/tmp/demo",
+  pattern: "*.txt",
+});
 console.log(files.map((f) => f.path));
 
 await sandbox.files.deleteDirectories(["/tmp/demo"]);
@@ -148,7 +165,32 @@ const { endpoint } = await sandbox.getEndpoint(44772);
 const url = await sandbox.getEndpointUrl(44772);
 ```
 
-### 6. Sandbox Management (Admin)
+### 6. Volume Mounts
+
+`volumes` supports `host`, `pvc`, and `ossfs` backends. Each volume must specify exactly one backend.
+
+```ts
+const sandbox = await Sandbox.create({
+  connectionConfig: config,
+  image: "ubuntu",
+  volumes: [
+    {
+      name: "oss-data",
+      ossfs: {
+        bucket: "bucket-a",
+        endpoint: "oss-cn-hangzhou.aliyuncs.com",
+        accessKeyId: process.env.OSS_ACCESS_KEY_ID!,
+        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET!,
+        version: "2.0",
+      },
+      mountPath: "/mnt/oss",
+      subPath: "prefix",
+    },
+  ],
+});
+```
+
+### 7. Sandbox Management (Admin)
 
 Use `SandboxManager` for administrative tasks and finding existing sandboxes.
 
@@ -156,7 +198,10 @@ Use `SandboxManager` for administrative tasks and finding existing sandboxes.
 import { SandboxManager } from "@alibaba-group/opensandbox";
 
 const manager = SandboxManager.create({ connectionConfig: config });
-const list = await manager.listSandboxInfos({ states: ["Running"], pageSize: 10 });
+const list = await manager.listSandboxInfos({
+  states: ["Running"],
+  pageSize: 10,
+});
 console.log(list.items.map((s) => s.id));
 await manager.close();
 ```
@@ -168,18 +213,19 @@ await manager.close();
 The `ConnectionConfig` class manages API server connection settings.
 
 Runtime notes:
+
 - In browsers, the SDK uses the global `fetch` implementation.
 - In Node.js, every `Sandbox` and `SandboxManager` clones the base `ConnectionConfig` via `withTransportIfMissing()`, so each instance gets an isolated `undici` keep-alive pool. Call `sandbox.close()` or `manager.close()` when you are done so the SDK can release the associated agent.
 
-| Parameter | Description | Default | Environment Variable |
-| --- | --- | --- | --- |
-| `apiKey` | API key for authentication | Optional | `OPEN_SANDBOX_API_KEY` |
-| `domain` | Sandbox service domain (`host[:port]`) | `localhost:8080` | `OPEN_SANDBOX_DOMAIN` |
-| `protocol` | HTTP protocol (`http`/`https`) | `http` | - |
-| `requestTimeoutSeconds` | Request timeout applied to SDK HTTP calls | `30` | - |
-| `debug` | Enable basic HTTP debug logging | `false` | - |
-| `headers` | Extra headers applied to every request | `{}` | - |
-| `useServerProxy` | Use sandbox server as proxy for execd/endpoint requests (e.g. when client cannot reach the sandbox directly) | `false` | - |
+| Parameter               | Description                                                                                                  | Default          | Environment Variable   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------- | ---------------------- |
+| `apiKey`                | API key for authentication                                                                                   | Optional         | `OPEN_SANDBOX_API_KEY` |
+| `domain`                | Sandbox service domain (`host[:port]`)                                                                       | `localhost:8080` | `OPEN_SANDBOX_DOMAIN`  |
+| `protocol`              | HTTP protocol (`http`/`https`)                                                                               | `http`           | -                      |
+| `requestTimeoutSeconds` | Request timeout applied to SDK HTTP calls                                                                    | `30`             | -                      |
+| `debug`                 | Enable basic HTTP debug logging                                                                              | `false`          | -                      |
+| `headers`               | Extra headers applied to every request                                                                       | `{}`             | -                      |
+| `useServerProxy`        | Use sandbox server as proxy for execd/endpoint requests (e.g. when client cannot reach the sandbox directly) | `false`          | -                      |
 
 ```ts
 import { ConnectionConfig } from "@alibaba-group/opensandbox";
@@ -203,20 +249,23 @@ const config2 = new ConnectionConfig({
 
 `Sandbox.create()` allows configuring the sandbox environment.
 
-| Parameter | Description | Default |
-| --- | --- | --- |
-| `image` | Docker image to use | Required |
-| `timeoutSeconds` | Automatic termination timeout (server-side TTL) | 10 minutes |
-| `entrypoint` | Container entrypoint command | `["tail","-f","/dev/null"]` |
-| `resource` | CPU and memory limits (string map) | `{"cpu":"1","memory":"2Gi"}` |
-| `env` | Environment variables | `{}` |
-| `metadata` | Custom metadata tags | `{}` |
-| `networkPolicy` | Optional outbound network policy (egress) | - |
-| `extensions` | Extra server-defined fields | `{}` |
-| `skipHealthCheck` | Skip readiness checks (`Running` + health check) | `false` |
-| `healthCheck` | Custom readiness check | - |
-| `readyTimeoutSeconds` | Max time to wait for readiness | 30 seconds |
-| `healthCheckPollingInterval` | Poll interval while waiting (milliseconds) | 200 ms |
+| Parameter                    | Description                                      | Default                      |
+| ---------------------------- | ------------------------------------------------ | ---------------------------- |
+| `image`                      | Docker image to use                              | Required                     |
+| `timeoutSeconds`             | Automatic termination timeout (server-side TTL)  | 10 minutes                   |
+| `entrypoint`                 | Container entrypoint command                     | `["tail","-f","/dev/null"]`  |
+| `resource`                   | CPU and memory limits (string map)               | `{"cpu":"1","memory":"2Gi"}` |
+| `env`                        | Environment variables                            | `{}`                         |
+| `metadata`                   | Custom metadata tags                             | `{}`                         |
+| `networkPolicy`              | Optional outbound network policy (egress)        | -                            |
+| `extensions`                 | Extra server-defined fields                      | `{}`                         |
+| `skipHealthCheck`            | Skip readiness checks (`Running` + health check) | `false`                      |
+| `healthCheck`                | Custom readiness check                           | -                            |
+| `readyTimeoutSeconds`        | Max time to wait for readiness                   | 30 seconds                   |
+| `healthCheckPollingInterval` | Poll interval while waiting (milliseconds)       | 200 ms                       |
+
+Note: metadata keys under `opensandbox.io/` are reserved for system-managed
+labels and will be rejected by the server.
 
 ```ts
 const sandbox = await Sandbox.create({
@@ -229,16 +278,35 @@ const sandbox = await Sandbox.create({
 });
 ```
 
-### 3. Resource cleanup
+### 3. Runtime Egress Policy Updates
+
+Runtime egress reads and patches go directly to the sandbox egress sidecar.
+The SDK first resolves the sandbox endpoint on port `18080`, then calls the sidecar `/policy` API.
+
+Patch uses merge semantics:
+- Incoming rules take priority over existing rules with the same `target`.
+- Existing rules for other targets remain unchanged.
+- Within a single patch payload, the first rule for a `target` wins.
+- The current `defaultAction` is preserved.
+
+```ts
+const policy = await sandbox.getEgressPolicy();
+
+await sandbox.patchEgressRules([
+  { action: "allow", target: "www.github.com" },
+  { action: "deny", target: "pypi.org" },
+]);
+```
+
+### 4. Resource cleanup
 
 Both `Sandbox` and `SandboxManager` own a scoped HTTP agent when running on Node.js
 so you can safely reuse the same `ConnectionConfig`. Once you are finished interacting
 with the sandbox or administration APIs, call `sandbox.close()` / `manager.close()` to
-release the underlying agent. 
+release the underlying agent.
 
 ## Browser Notes
 
 - The SDK can run in browsers, but **streaming file uploads are Node-only**.
 - If you pass `ReadableStream` or `AsyncIterable` for `writeFiles`, the browser will fall back to **buffering in memory** before upload.
 - Reason: browsers do not support streaming `multipart/form-data` bodies with custom boundaries (required by the execd upload API).
-

package/dist/{chunk-OYTPXLWE.js → chunk-AFWIGM3C.js}

@@ -14,25 +14,26 @@ var SandboxException = class extends Error {
   name = "SandboxException";
   error;
   cause;
+  requestId;
   constructor(opts = {}) {
     super(opts.message);
     this.cause = opts.cause;
     this.error = opts.error ?? new SandboxError(SandboxError.INTERNAL_UNKNOWN_ERROR);
+    this.requestId = opts.requestId;
   }
 };
 var SandboxApiException = class extends SandboxException {
   name = "SandboxApiException";
   statusCode;
-  requestId;
   rawBody;
   constructor(opts) {
     super({
       message: opts.message,
       cause: opts.cause,
-      error: opts.error ?? new SandboxError(SandboxError.UNEXPECTED_RESPONSE, opts.message)
+      error: opts.error ?? new SandboxError(SandboxError.UNEXPECTED_RESPONSE, opts.message),
+      requestId: opts.requestId
     });
     this.statusCode = opts.statusCode;
-    this.requestId = opts.requestId;
     this.rawBody = opts.rawBody;
   }
 };
@@ -267,6 +268,9 @@ function joinUrl(baseUrl, pathname) {
   return `${base}${path}`;
 }
 function toRunCommandRequest(command, opts) {
+  if (opts?.gid != null && opts.uid == null) {
+    throw new Error("uid is required when gid is provided");
+  }
   const body = {
     command,
     cwd: opts?.workingDirectory,
@@ -275,8 +279,39 @@ function toRunCommandRequest(command, opts) {
   if (opts?.timeoutSeconds != null) {
     body.timeout = Math.round(opts.timeoutSeconds * 1e3);
   }
+  if (opts?.uid != null) {
+    body.uid = opts.uid;
+  }
+  if (opts?.gid != null) {
+    body.gid = opts.gid;
+  }
+  if (opts?.envs != null) {
+    body.envs = opts.envs;
+  }
+  return body;
+}
+function toRunInSessionRequest(command, opts) {
+  const body = {
+    command
+  };
+  if (opts?.workingDirectory != null) {
+    body.cwd = opts.workingDirectory;
+  }
+  if (opts?.timeoutSeconds != null) {
+    body.timeout = Math.round(opts.timeoutSeconds * 1e3);
+  }
   return body;
 }
+function inferForegroundExitCode(execution) {
+  const errorValue = execution.error?.value?.trim();
+  const parsedExitCode = errorValue && /^-?\d+$/.test(errorValue) ? Number(errorValue) : Number.NaN;
+  return execution.error != null ? Number.isFinite(parsedExitCode) ? parsedExitCode : null : execution.complete ? 0 : null;
+}
+function assertNonBlank(value, field) {
+  if (!value.trim()) {
+    throw new Error(`${field} cannot be empty`);
+  }
+}
 function parseOptionalDate(value, field) {
   if (value == null) return void 0;
   if (value instanceof Date) return value;
@@ -296,6 +331,58 @@ var CommandsAdapter = class {
     this.fetch = opts.fetch ?? fetch;
   }
   fetch;
+  buildRunStreamSpec(command, opts) {
+    assertNonBlank(command, "command");
+    return {
+      pathname: "/command",
+      body: toRunCommandRequest(command, opts),
+      fallbackErrorMessage: "Run command failed"
+    };
+  }
+  buildRunInSessionStreamSpec(sessionId, command, opts) {
+    assertNonBlank(sessionId, "sessionId");
+    assertNonBlank(command, "command");
+    return {
+      pathname: `/session/${encodeURIComponent(sessionId)}/run`,
+      body: toRunInSessionRequest(command, opts),
+      fallbackErrorMessage: "Run in session failed"
+    };
+  }
+  async *streamExecution(spec, signal) {
+    const url = joinUrl(this.opts.baseUrl, spec.pathname);
+    const res = await this.fetch(url, {
+      method: "POST",
+      headers: {
+        accept: "text/event-stream",
+        "content-type": "application/json",
+        ...this.opts.headers ?? {}
+      },
+      body: JSON.stringify(spec.body),
+      signal
+    });
+    for await (const ev of parseJsonEventStream(res, {
+      fallbackErrorMessage: spec.fallbackErrorMessage
+    })) {
+      yield ev;
+    }
+  }
+  async consumeExecutionStream(stream, handlers, inferExitCode = false) {
+    const execution = {
+      logs: { stdout: [], stderr: [] },
+      result: []
+    };
+    const dispatcher = new ExecutionEventDispatcher(execution, handlers);
+    for await (const ev of stream) {
+      if (ev.type === "init" && (ev.text ?? "") === "" && execution.id) {
+        ev.text = execution.id;
+      }
+      await dispatcher.dispatch(ev);
+    }
+    if (inferExitCode) {
+      execution.exitCode = inferForegroundExitCode(execution);
+    }
+    return execution;
+  }
   async interrupt(sessionId) {
     const { error, response } = await this.client.DELETE("/command", {
       params: { query: { id: sessionId } }
@@ -339,35 +426,53 @@ var CommandsAdapter = class {
     };
   }
   async *runStream(command, opts, signal) {
-    const url = joinUrl(this.opts.baseUrl, "/command");
-    const body = JSON.stringify(toRunCommandRequest(command, opts));
-    const res = await this.fetch(url, {
-      method: "POST",
-      headers: {
-        "accept": "text/event-stream",
-        "content-type": "application/json",
-        ...this.opts.headers ?? {}
-      },
-      body,
+    for await (const ev of this.streamExecution(
+      this.buildRunStreamSpec(command, opts),
       signal
-    });
-    for await (const ev of parseJsonEventStream(res, { fallbackErrorMessage: "Run command failed" })) {
+    )) {
       yield ev;
     }
   }
   async run(command, opts, handlers, signal) {
-    const execution = {
-      logs: { stdout: [], stderr: [] },
-      result: []
-    };
-    const dispatcher = new ExecutionEventDispatcher(execution, handlers);
-    for await (const ev of this.runStream(command, opts, signal)) {
-      if (ev.type === "init" && (ev.text ?? "") === "" && execution.id) {
-        ev.text = execution.id;
-      }
-      await dispatcher.dispatch(ev);
+    return this.consumeExecutionStream(
+      this.runStream(command, opts, signal),
+      handlers,
+      !opts?.background
+    );
+  }
+  async createSession(options) {
+    const body = options?.workingDirectory != null ? { cwd: options.workingDirectory } : {};
+    const { data, error, response } = await this.client.POST("/session", {
+      body
+    });
+    throwOnOpenApiFetchError({ error, response }, "Create session failed");
+    const ok = data;
+    if (!ok || typeof ok.session_id !== "string") {
+      throw new Error("Create session failed: unexpected response shape");
+    }
+    return ok.session_id;
+  }
+  async *runInSessionStream(sessionId, command, opts, signal) {
+    for await (const ev of this.streamExecution(
+      this.buildRunInSessionStreamSpec(sessionId, command, opts),
+      signal
+    )) {
+      yield ev;
     }
-    return execution;
+  }
+  async runInSession(sessionId, command, options, handlers, signal) {
+    return this.consumeExecutionStream(
+      this.runInSessionStream(sessionId, command, options, signal),
+      handlers,
+      true
+    );
+  }
+  async deleteSession(sessionId) {
+    const { error, response } = await this.client.DELETE(
+      "/session/{sessionId}",
+      { params: { path: { sessionId } } }
+    );
+    throwOnOpenApiFetchError({ error, response }, "Delete session failed");
   }
 };
 
@@ -856,11 +961,15 @@ var SandboxesAdapter = class {
     }
     return d;
   }
+  parseOptionalIsoDate(field, v) {
+    if (v == null) return null;
+    return this.parseIsoDate(field, v);
+  }
   mapSandboxInfo(raw) {
     return {
       ...raw ?? {},
       createdAt: this.parseIsoDate("createdAt", raw?.createdAt),
-      expiresAt: this.parseIsoDate("expiresAt", raw?.expiresAt)
+      expiresAt: this.parseOptionalIsoDate("expiresAt", raw?.expiresAt)
     };
   }
   async createSandbox(req) {
@@ -876,7 +985,7 @@ var SandboxesAdapter = class {
     return {
       ...raw ?? {},
       createdAt: this.parseIsoDate("createdAt", raw?.createdAt),
-      expiresAt: this.parseIsoDate("expiresAt", raw?.expiresAt)
+      expiresAt: this.parseOptionalIsoDate("expiresAt", raw?.expiresAt)
     };
   }
   async getSandbox(sandboxId) {
@@ -970,6 +1079,7 @@ export {
   InvalidArgumentException,
   createExecdClient,
   createLifecycleClient,
+  throwOnOpenApiFetchError,
   ExecutionEventDispatcher,
   CommandsAdapter,
   FilesystemAdapter,
@@ -977,4 +1087,4 @@ export {
   MetricsAdapter,
   SandboxesAdapter
 };
-//# sourceMappingURL=chunk-OYTPXLWE.js.map
+//# sourceMappingURL=chunk-AFWIGM3C.js.map