@sandboxxjs/core 0.5.0 → 2.0.0

package/src/create-client.ts

@@ -0,0 +1,187 @@
+/**
+ * createSandboxClient — the runtime implementation of SandboxClient.
+ *
+ * Platform-agnostic: uses standard WebSocket API (available in Node 22+, browsers).
+ * Platform differences are injected via SandboxProvider, which supplies
+ * Executor, FileSystem, and ProcessManager components.
+ */
+
+import type { SandboxClient, SandboxClientOptions } from "./client";
+import type {
+  ClientMessage,
+  ErrorMessage,
+  FsResultMessage,
+  ResultMessage,
+  ServiceMessage,
+} from "./protocol";
+import type { SandboxProvider } from "./provider";
+
+export function createSandboxClient(provider: SandboxProvider): SandboxClient {
+  const executor = provider.createExecutor();
+  const fs = provider.createFileSystem();
+  const pm = provider.createProcessManager();
+
+  let ws: WebSocket | null = null;
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  let isConnected = false;
+
+  async function connect(options: SandboxClientOptions): Promise<void> {
+    const { wsUrl, sandboxId, token, heartbeatInterval = 30_000 } = options;
+
+    return new Promise((resolve, reject) => {
+      ws = new WebSocket(wsUrl);
+
+      ws.onopen = () => {
+        // Step 3: Register
+        const registerMsg: ClientMessage = { type: "register", sandboxId, token };
+        ws!.send(JSON.stringify(registerMsg));
+      };
+
+      ws.onmessage = (event) => {
+        const data = typeof event.data === "string" ? event.data : "";
+        let msg: ServiceMessage;
+        try {
+          msg = JSON.parse(data);
+        } catch {
+          return;
+        }
+
+        if (msg.type === "registered") {
+          // Step 4: Ready
+          isConnected = true;
+          heartbeatTimer = setInterval(() => {
+            if (ws?.readyState === WebSocket.OPEN) {
+              const hb: ClientMessage = { type: "heartbeat" };
+              ws.send(JSON.stringify(hb));
+            }
+          }, heartbeatInterval);
+          resolve();
+          return;
+        }
+
+        // Step 5: Command — handle and respond
+        handleCommand(msg);
+      };
+
+      ws.onerror = () => {
+        if (!isConnected) reject(new Error("WebSocket connection failed"));
+      };
+
+      ws.onclose = () => {
+        cleanup();
+      };
+    });
+  }
+
+  async function handleCommand(msg: ServiceMessage): Promise<void> {
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+
+    try {
+      switch (msg.type) {
+        // Executor
+        case "exec": {
+          const result = await executor.exec(msg.command, {
+            cwd: msg.cwd,
+            timeout: msg.timeout,
+          });
+          const reply: ResultMessage = {
+            type: "result",
+            id: msg.id,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            exitCode: result.exitCode,
+          };
+          ws.send(JSON.stringify(reply));
+          break;
+        }
+
+        // FileSystem
+        case "fs.read": {
+          const content = await fs.readFile(msg.path);
+          sendFsResult(msg.id, { content });
+          break;
+        }
+
+        case "fs.write": {
+          await fs.writeFile(msg.path, msg.content);
+          sendFsResult(msg.id, { written: true });
+          break;
+        }
+
+        case "fs.list": {
+          const files = await fs.listFiles(msg.path);
+          sendFsResult(msg.id, files);
+          break;
+        }
+
+        case "fs.mkdir": {
+          await fs.mkdir(msg.path, { recursive: msg.recursive });
+          sendFsResult(msg.id, { created: true });
+          break;
+        }
+
+        case "fs.delete": {
+          await fs.deleteFile(msg.path);
+          sendFsResult(msg.id, { deleted: true });
+          break;
+        }
+
+        // ProcessManager
+        case "process.start": {
+          const proc = await pm.start(msg.command, { cwd: msg.cwd });
+          sendFsResult(msg.id, proc);
+          break;
+        }
+
+        case "process.kill": {
+          await pm.kill(msg.processId);
+          sendFsResult(msg.id, { killed: true });
+          break;
+        }
+
+        case "process.list": {
+          const procs = await pm.list();
+          sendFsResult(msg.id, procs);
+          break;
+        }
+      }
+    } catch (err) {
+      const errorMsg: ErrorMessage = {
+        type: "error",
+        id: (msg as { id?: string }).id || "unknown",
+        message: err instanceof Error ? err.message : "Command failed",
+      };
+      ws.send(JSON.stringify(errorMsg));
+    }
+  }
+
+  function sendFsResult(id: string, data: unknown): void {
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+    const reply: FsResultMessage = { type: "fs.result", id, data };
+    ws.send(JSON.stringify(reply));
+  }
+
+  function cleanup(): void {
+    isConnected = false;
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    ws = null;
+  }
+
+  async function disconnect(): Promise<void> {
+    if (ws) {
+      ws.close();
+      cleanup();
+    }
+  }
+
+  return {
+    connect,
+    disconnect,
+    get connected() {
+      return isConnected;
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @sandboxxjs/core — Sandbox abstraction framework.
+ *
+ * Unified lifecycle for any sandbox environment:
+ *
+ *   Allocate → Prepare → Register → Ready → Command
+ *
+ *   1. Allocator provisions resources, returns SandboxContainer (status: pending)
+ *   2. Sandbox environment starts, sandbox-client prepares
+ *   3. sandbox-client connects to Registry via WebSocket, registers
+ *   4. Registry marks sandbox as ready
+ *   5. Router dispatches commands through Registry to sandbox-client
+ *
+ * Platform differences are injected via SandboxProvider:
+ *   - @sandboxxjs/node-provider: child_process + node:fs
+ *   - @sandboxxjs/web-provider: @webcontainer/api
+ *   - Future: Docker, SSH, WASM, etc.
+ */
+
+// Allocator — Step 1: Allocate
+export type {
+  AllocateRequest,
+  SandboxAllocator,
+  SandboxContainer,
+  SandboxContainerType,
+  SandboxStatus,
+} from "./allocator";
+
+// Client — Step 2-3: Prepare + Register
+export type { SandboxClient, SandboxClientOptions } from "./client";
+export { createSandboxClient } from "./create-client";
+// Provider — Platform capability injection
+export type {
+  SandboxExecutor,
+  SandboxFileSystem,
+  SandboxProcessManager,
+  SandboxProvider,
+} from "./provider";
+// Registry — Step 3-4: Register + Ready
+export type { SandboxConnection, SandboxRegistry } from "./registry";
+// Router — Step 5: Command (RPC dispatch)
+export type { SandboxRouter } from "./router";
+
+// Sandbox — Step 5: Command (consumer-facing)
+export type { ExecOptions, ExecResult, FileInfo, ProcessInfo, Sandbox } from "./sandbox";

package/src/protocol.ts

@@ -0,0 +1,133 @@
+/**
+ * Sandbox protocol — WebSocket message types between sandbox-client and service.
+ *
+ * This protocol covers lifecycle steps 3-5:
+ *   Register: client sends RegisterMessage, service responds RegisteredMessage
+ *   Ready:    heartbeat keeps connection alive
+ *   Command:  service sends commands, client returns results
+ *
+ * All sandbox-clients (cloud, web, future types) speak this same protocol.
+ *
+ * Lifecycle: Allocate → Prepare → Register → Ready → Command
+ *                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ */
+
+// ==================== Client → Service ====================
+
+export interface RegisterMessage {
+  type: "register";
+  sandboxId: string;
+  token: string;
+}
+
+export interface ResultMessage {
+  type: "result";
+  id: string;
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface FsResultMessage {
+  type: "fs.result";
+  id: string;
+  data: unknown;
+}
+
+export interface ErrorMessage {
+  type: "error";
+  id: string;
+  message: string;
+}
+
+export interface HeartbeatMessage {
+  type: "heartbeat";
+}
+
+// ==================== Service → Client ====================
+
+export interface ExecMessage {
+  type: "exec";
+  id: string;
+  command: string;
+  cwd?: string;
+  timeout?: number;
+}
+
+export interface FsReadMessage {
+  type: "fs.read";
+  id: string;
+  path: string;
+}
+
+export interface FsWriteMessage {
+  type: "fs.write";
+  id: string;
+  path: string;
+  content: string;
+}
+
+export interface FsListMessage {
+  type: "fs.list";
+  id: string;
+  path: string;
+}
+
+export interface FsMkdirMessage {
+  type: "fs.mkdir";
+  id: string;
+  path: string;
+  recursive?: boolean;
+}
+
+export interface FsDeleteMessage {
+  type: "fs.delete";
+  id: string;
+  path: string;
+}
+
+export interface ProcessStartMessage {
+  type: "process.start";
+  id: string;
+  command: string;
+  cwd?: string;
+}
+
+export interface ProcessKillMessage {
+  type: "process.kill";
+  id: string;
+  processId: string;
+}
+
+export interface ProcessListMessage {
+  type: "process.list";
+  id: string;
+}
+
+export interface RegisteredMessage {
+  type: "registered";
+  sandboxId: string;
+}
+
+// ==================== Union types ====================
+
+/** Messages sent from sandbox-client to service */
+export type ClientMessage =
+  | RegisterMessage
+  | ResultMessage
+  | FsResultMessage
+  | ErrorMessage
+  | HeartbeatMessage;
+
+/** Messages sent from service to sandbox-client */
+export type ServiceMessage =
+  | ExecMessage
+  | FsReadMessage
+  | FsWriteMessage
+  | FsListMessage
+  | FsMkdirMessage
+  | FsDeleteMessage
+  | ProcessStartMessage
+  | ProcessKillMessage
+  | ProcessListMessage
+  | RegisteredMessage;

package/src/provider.ts

@@ -0,0 +1,54 @@
+/**
+ * SandboxProvider — platform capability injection.
+ *
+ * Provider is a component factory that supplies platform-specific
+ * implementations of Executor, FileSystem, and ProcessManager.
+ *
+ * The core layer (createSandboxClient) only depends on this interface.
+ * Platform differences are isolated in provider implementations:
+ *   - node-provider: child_process + node:fs
+ *   - web-provider: @webcontainer/api
+ *   - Future: Docker, SSH, etc.
+ */
+
+import type { ExecOptions, ExecResult, FileInfo, ProcessInfo } from "./sandbox";
+
+/**
+ * Command execution component.
+ */
+export interface SandboxExecutor {
+  exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+}
+
+/**
+ * File system component.
+ */
+export interface SandboxFileSystem {
+  readFile(path: string): Promise<string>;
+  writeFile(path: string, content: string): Promise<void>;
+  listFiles(path: string): Promise<FileInfo[]>;
+  mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
+  deleteFile(path: string): Promise<void>;
+}
+
+/**
+ * Process management component.
+ */
+export interface SandboxProcessManager {
+  start(command: string, options?: { cwd?: string }): Promise<ProcessInfo>;
+  kill(processId: string): Promise<void>;
+  list(): Promise<ProcessInfo[]>;
+}
+
+/**
+ * SandboxProvider — the component factory.
+ *
+ * Each platform implements this interface to provide its components.
+ * createSandboxClient(provider) obtains components and dispatches
+ * incoming messages to the appropriate component.
+ */
+export interface SandboxProvider {
+  createExecutor(): SandboxExecutor;
+  createFileSystem(): SandboxFileSystem;
+  createProcessManager(): SandboxProcessManager;
+}

package/src/registry.ts

@@ -0,0 +1,29 @@
+/**
+ * SandboxRegistry — accepts sandbox-client connections and manages lifecycle.
+ *
+ * Step 3-4 of the lifecycle: Register → Ready.
+ *
+ * When a sandbox-client connects via WebSocket and sends a register message,
+ * the registry:
+ *   1. Validates the token
+ *   2. Binds the WebSocket connection to the sandboxId
+ *   3. Updates the sandbox status from "pending" to "ready"
+ *   4. Provides the command routing channel
+ *
+ * The registry also handles disconnection, heartbeat, and reconnection.
+ *
+ * Lifecycle: Allocate → Prepare → Register → Ready → Command
+ *                                 ^^^^^^^^^^^^^^^^^
+ */
+
+export interface SandboxConnection {
+  sandboxId: string;
+  connectedAt: number;
+}
+
+export interface SandboxRegistry {
+  /** Check if a sandbox-client is connected and ready */
+  has(sandboxId: string): boolean;
+  /** List all active connections */
+  connections(): SandboxConnection[];
+}

package/src/router.ts

@@ -0,0 +1,25 @@
+/**
+ * SandboxRouter — routes RPC methods to sandbox operations.
+ *
+ * Step 5 of the lifecycle: Command.
+ *
+ * The router is the external-facing RPC interface.
+ * It combines the allocator (lifecycle) and registry (connections)
+ * to provide a unified dispatch: method + params → result.
+ *
+ * Internally, it resolves the sandboxId from params, finds the
+ * connected sandbox-client through the registry, and forwards
+ * the command over WebSocket.
+ *
+ * Lifecycle: Allocate → Prepare → Register → Ready → Command
+ *                                                     ^^^^^^^
+ */
+
+import type { Sandbox } from "./sandbox";
+
+export interface SandboxRouter {
+  /** Get a Sandbox handle by id — routes through registry to connected client */
+  getSandbox(sandboxId: string): Sandbox;
+  /** Dispatch an RPC method with params */
+  dispatch(method: string, params: Record<string, unknown>): Promise<unknown>;
+}

package/src/sandbox.ts

@@ -0,0 +1,52 @@
+/**
+ * Sandbox — the unified interface for sandbox operations.
+ *
+ * Step 5 of the lifecycle: Command.
+ *
+ * Consumers get a Sandbox instance and operate on it.
+ * They never need to know if it's a cloud container, a browser WebContainer,
+ * or any other sandbox type. All commands are routed through the registry
+ * to the connected sandbox-client.
+ *
+ * Lifecycle: Allocate → Prepare → Register → Ready → Command
+ *                                                     ^^^^^^^
+ */
+
+export interface ExecOptions {
+  cwd?: string;
+  timeout?: number;
+}
+
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  success: boolean;
+}
+
+export interface ProcessInfo {
+  id: string;
+  pid?: number;
+  command: string;
+  status: string;
+}
+
+export interface FileInfo {
+  name: string;
+  type: "file" | "directory" | "symlink";
+  size?: number;
+}
+
+export interface Sandbox {
+  exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+  startProcess(command: string, options?: { cwd?: string }): Promise<ProcessInfo>;
+  killProcess(processId: string): Promise<void>;
+  listProcesses(): Promise<ProcessInfo[]>;
+  readFile(path: string): Promise<string>;
+  writeFile(path: string, content: string): Promise<void>;
+  listFiles(path: string): Promise<FileInfo[]>;
+  mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
+  deleteFile(path: string): Promise<void>;
+  exposePort(port: number, hostname: string): Promise<{ url: string }>;
+  destroy(): Promise<void>;
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/README.md

@@ -1,60 +0,0 @@
-# @@sandboxxjs/sandbox/core
-
-Core implementation for SandboX - secure code execution engine.
-
-## Features
-
-- Multiple isolators (Local, Cloudflare, E2B, Firecracker)
-- Multiple runtimes (Node.js, Python, Bash, Docker)
-- File system operations
-- Resource limits
-- Event-driven architecture
-
-## Installation
-
-```bash
-npm install @@sandboxxjs/sandbox/core
-```
-
-## Usage
-
-```typescript
-import { Sandbox, LocalIsolator } from "@@sandboxxjs/sandbox/core";
-
-const isolator = new LocalIsolator("node");
-const sandbox = new Sandbox({
-  runtime: "node",
-  isolator: "local",
-});
-
-const result = await sandbox.execute({
-  code: 'console.log("Hello")',
-});
-
-console.log(result.stdout); // "Hello"
-```
-
-## API
-
-### Sandbox
-
-```typescript
-class Sandbox {
-  execute(options: ExecuteOptions): Promise<ExecuteResult>;
-  writeFile(path: string, data: string): Promise<void>;
-  readFile(path: string): Promise<string>;
-  destroy(): Promise<void>;
-  on(event: string, handler: Function): void;
-  fs: FileSystem;
-}
-```
-
-### Isolators
-
-- `LocalIsolator` - Process isolation via execa
-- `CloudflareContainerIsolator` - Docker via Bun binary
-- `E2BIsolator` - E2B microVM (not yet implemented)
-
-## License
-
-MIT