@alibaba-group/opensandbox 0.1.0-dev1

package/README.md

@@ -0,0 +1,212 @@
+# Alibaba Sandbox SDK for JavaScript/TypeScript
+
+English | [中文](README_zh.md)
+
+A TypeScript/JavaScript SDK for low-level interaction with OpenSandbox. It provides the ability to create, manage, and interact with secure sandbox environments, including executing shell commands, managing files, and reading resource metrics.
+
+## Installation
+
+### npm
+
+```bash
+npm install @alibaba-group/opensandbox
+```
+
+### pnpm
+
+```bash
+pnpm add @alibaba-group/opensandbox
+```
+
+### yarn
+
+```bash
+yarn add @alibaba-group/opensandbox
+```
+
+## Quick Start
+
+The following example shows how to create a sandbox and execute a shell command.
+
+> **Note**: Before running this example, ensure the OpenSandbox service is running. See the root [README.md](../../../README.md) for startup instructions.
+
+```ts
+import { ConnectionConfig, Sandbox, SandboxException } from "@alibaba-group/opensandbox";
+
+const config = new ConnectionConfig({
+  domain: "api.opensandbox.io",
+  apiKey: "your-api-key",
+  // protocol: "https",
+  // requestTimeoutSeconds: 60,
+});
+
+try {
+  const sandbox = await Sandbox.create({
+    connectionConfig: config,
+    image: "ubuntu",
+    timeoutSeconds: 10 * 60,
+  });
+
+  const execution = await sandbox.commands.run("echo 'Hello Sandbox!'");
+  console.log(execution.logs.stdout[0]?.text);
+
+  // Optional but recommended: terminate the remote instance when you are done.
+  await sandbox.kill();
+} catch (err) {
+  if (err instanceof SandboxException) {
+    console.error(`Sandbox Error: [${err.error.code}] ${err.error.message ?? ""}`);
+  } else {
+    console.error(err);
+  }
+}
+```
+
+## Usage Examples
+
+### 1. Lifecycle Management
+
+Manage the sandbox lifecycle, including renewal, pausing, and resuming.
+
+```ts
+const info = await sandbox.getInfo();
+console.log("State:", info.status.state);
+console.log("Created:", info.createdAt);
+console.log("Expires:", info.expiresAt);
+
+await sandbox.pause();
+
+// Resume returns a fresh, connected Sandbox instance.
+const resumed = await sandbox.resume();
+
+// Renew: expiresAt = now + timeoutSeconds
+await resumed.renew(30 * 60);
+```
+
+### 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.
+
+```ts
+const sandbox = await Sandbox.create({
+  connectionConfig: config,
+  image: "nginx:latest",
+  healthCheck: async (sbx) => {
+    // Example: consider the sandbox healthy when port 80 endpoint becomes available
+    const ep = await sbx.getEndpoint(80);
+    return !!ep.endpoint;
+  },
+});
+```
+
+### 3. Command Execution & Streaming
+
+Execute commands and handle output streams in real-time.
+
+```ts
+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"),
+};
+
+await sandbox.commands.run(
+  'for i in 1 2 3; do echo "Count $i"; sleep 0.2; done',
+  undefined,
+  handlers,
+);
+```
+
+### 4. Comprehensive File Operations
+
+Manage files and directories, including read, write, list/search, and delete.
+
+```ts
+await sandbox.files.createDirectories([{ path: "/tmp/demo", mode: 0o755 }]);
+
+await sandbox.files.writeFiles([
+  { path: "/tmp/demo/hello.txt", data: "Hello World", mode: 0o644 },
+]);
+
+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" });
+console.log(files.map((f) => f.path));
+
+await sandbox.files.deleteDirectories(["/tmp/demo"]);
+```
+
+### 5. Endpoints
+
+`getEndpoint()` returns an endpoint **without a scheme** (for example `"localhost:44772"`). Use `getEndpointUrl()` if you want a ready-to-use absolute URL (for example `"http://localhost:44772"`).
+
+```ts
+const { endpoint } = await sandbox.getEndpoint(44772);
+const url = await sandbox.getEndpointUrl(44772);
+```
+
+### 6. Sandbox Management (Admin)
+
+Use `SandboxManager` for administrative tasks and finding existing sandboxes.
+
+```ts
+import { SandboxManager } from "@alibaba-group/opensandbox";
+
+const manager = SandboxManager.create({ connectionConfig: config });
+const list = await manager.listSandboxInfos({ states: ["Running"], pageSize: 10 });
+console.log(list.items.map((s) => s.id));
+```
+
+## Configuration
+
+### 1. Connection Configuration
+
+The `ConnectionConfig` class manages API server connection settings.
+
+| 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 | `{}` | - |
+
+```ts
+import { ConnectionConfig } from "@alibaba-group/opensandbox";
+
+// 1. Basic configuration
+const config = new ConnectionConfig({
+  domain: "api.opensandbox.io",
+  apiKey: "your-key",
+  requestTimeoutSeconds: 60,
+});
+
+// 2. Advanced: custom headers
+const config2 = new ConnectionConfig({
+  domain: "api.opensandbox.io",
+  apiKey: "your-key",
+  headers: { "X-Custom-Header": "value" },
+});
+```
+
+### 2. Sandbox Creation Configuration
+
+`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 | `{}` |
+| `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 |
+

package/dist/adapters/commandsAdapter.d.ts

@@ -0,0 +1,22 @@
+import type { ExecdClient } from "../openapi/execdClient.js";
+import type { CommandExecution, RunCommandOpts, ServerStreamEvent } from "../models/execd.js";
+import type { ExecdCommands } from "../services/execdCommands.js";
+import type { ExecutionHandlers } from "../models/execution.js";
+export interface CommandsAdapterOptions {
+    /**
+     * Must match the baseUrl used by the ExecdClient.
+     */
+    baseUrl: string;
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+}
+export declare class CommandsAdapter implements ExecdCommands {
+    private readonly client;
+    private readonly opts;
+    private readonly fetch;
+    constructor(client: ExecdClient, opts: CommandsAdapterOptions);
+    interrupt(sessionId: string): Promise<void>;
+    runStream(command: string, opts?: RunCommandOpts, signal?: AbortSignal): AsyncIterable<ServerStreamEvent>;
+    run(command: string, opts?: RunCommandOpts, handlers?: ExecutionHandlers, signal?: AbortSignal): Promise<CommandExecution>;
+}
+//# sourceMappingURL=commandsAdapter.d.ts.map

package/dist/adapters/commandsAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandsAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/commandsAdapter.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAI7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC9F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAoBhE,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,qBAAa,eAAgB,YAAW,aAAa;IAIjD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAGlB,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,sBAAsB;IAKzC,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1C,SAAS,CACd,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,cAAc,EACrB,MAAM,CAAC,EAAE,WAAW,GACnB,aAAa,CAAC,iBAAiB,CAAC;IAoB7B,GAAG,CACP,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,cAAc,EACrB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,gBAAgB,CAAC;CAgB7B"}

package/dist/adapters/commandsAdapter.js

@@ -0,0 +1,76 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import { throwOnOpenApiFetchError } from "./openapiError.js";
+import { parseJsonEventStream } from "./sse.js";
+import { ExecutionEventDispatcher } from "../models/executionEventDispatcher.js";
+function joinUrl(baseUrl, pathname) {
+    const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+    const path = pathname.startsWith("/") ? pathname : `/${pathname}`;
+    return `${base}${path}`;
+}
+function toRunCommandRequest(command, opts) {
+    return {
+        command,
+        cwd: opts?.workingDirectory,
+        background: !!opts?.background,
+    };
+}
+export class CommandsAdapter {
+    client;
+    opts;
+    fetch;
+    constructor(client, opts) {
+        this.client = client;
+        this.opts = opts;
+        this.fetch = opts.fetch ?? fetch;
+    }
+    async interrupt(sessionId) {
+        const { error, response } = await this.client.DELETE("/command", {
+            params: { query: { id: sessionId } },
+        });
+        throwOnOpenApiFetchError({ error, response }, "Interrupt command failed");
+    }
+    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,
+            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)) {
+            // Keep legacy behavior: if server sends "init" with empty id, preserve previous id.
+            if (ev.type === "init" && (ev.text ?? "") === "" && execution.id) {
+                ev.text = execution.id;
+            }
+            await dispatcher.dispatch(ev);
+        }
+        return execution;
+    }
+}

package/dist/adapters/filesystemAdapter.d.ts

@@ -0,0 +1,52 @@
+import type { ExecdClient } from "../openapi/execdClient.js";
+import type { SandboxFiles } from "../services/filesystem.js";
+import type { ContentReplaceEntry, FileInfo, MoveEntry, SearchEntry, SearchFilesResponse, SetPermissionEntry, WriteEntry } from "../models/filesystem.js";
+export interface FilesystemAdapterOptions {
+    /**
+     * Must match the baseUrl used by the ExecdClient, used for binary endpoints
+     * like download/upload where we bypass JSON parsing.
+     */
+    baseUrl: string;
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+}
+/**
+ * Filesystem adapter that exposes user-facing file APIs (`sandbox.files`).
+ *
+ * This adapter owns all request/response conversions:
+ * - Maps friendly method shapes to API payloads
+ * - Parses timestamps into `Date`
+ * - Implements streaming upload/download helpers
+ */
+export declare class FilesystemAdapter implements SandboxFiles {
+    private readonly client;
+    private readonly opts;
+    private readonly fetch;
+    private static readonly Api;
+    constructor(client: ExecdClient, opts: FilesystemAdapterOptions);
+    private parseIsoDate;
+    private static readonly _ApiFileInfo;
+    private mapApiFileInfo;
+    getFileInfo(paths: string[]): Promise<Record<string, FileInfo>>;
+    deleteFiles(paths: string[]): Promise<void>;
+    createDirectories(entries: Pick<WriteEntry, "path" | "mode" | "owner" | "group">[]): Promise<void>;
+    deleteDirectories(paths: string[]): Promise<void>;
+    setPermissions(entries: SetPermissionEntry[]): Promise<void>;
+    moveFiles(entries: MoveEntry[]): Promise<void>;
+    replaceContents(entries: ContentReplaceEntry[]): Promise<void>;
+    search(entry: SearchEntry): Promise<SearchFilesResponse>;
+    private uploadFile;
+    readBytes(path: string, opts?: {
+        range?: string;
+    }): Promise<Uint8Array>;
+    readBytesStream(path: string, opts?: {
+        range?: string;
+    }): AsyncIterable<Uint8Array>;
+    private downloadStream;
+    readFile(path: string, opts?: {
+        encoding?: string;
+        range?: string;
+    }): Promise<string>;
+    writeFiles(entries: WriteEntry[]): Promise<void>;
+}
+//# sourceMappingURL=filesystemAdapter.d.ts.map

package/dist/adapters/filesystemAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystemAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/filesystemAdapter.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,KAAK,EACV,mBAAmB,EACnB,QAAQ,EAGR,SAAS,EAIT,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,EACX,MAAM,yBAAyB,CAAC;AAqGjC,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAcD;;;;;;;GAOG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IAoBlD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IApBvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAczB;gBAGiB,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,wBAAwB;IAKjD,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CACsC;IAE1E,OAAO,CAAC,cAAc;IAoBhB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAwB/D,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3C,iBAAiB,CACrB,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,EAAE,GAC/D,OAAO,CAAC,IAAI,CAAC;IAYV,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjD,cAAc,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5D,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAa9C,eAAe,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAa9D,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC;YAiBhD,UAAU;IAmGlB,SAAS,CACb,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACxB,OAAO,CAAC,UAAU,CAAC;IA6BtB,eAAe,CACb,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACxB,aAAa,CAAC,UAAU,CAAC;YAIb,cAAc;IAuCvB,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3C,OAAO,CAAC,MAAM,CAAC;IAMZ,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAWvD"}