@cloudflare/sandbox 0.0.0-cbb7fcd → 0.0.0-cecde0a

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @cloudflare/sandbox
 
+## 0.0.9
+
+### Patch Changes
+
+- [#20](https://github.com/cloudflare/sandbox-sdk/pull/20) [`f106fda`](https://github.com/cloudflare/sandbox-sdk/commit/f106fdac98e7ef35677326290d45cbf3af88982c) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - add preview URLs and dynamic port forwarding
+
+## 0.0.8
+
+### Patch Changes
+
+- [`60af265`](https://github.com/cloudflare/sandbox-sdk/commit/60af265d834e83fd30a921a3e1be232f13fe24da) Thanks [@threepointone](https://github.com/threepointone)! - update dependencies
+
+## 0.0.7
+
+### Patch Changes
+
+- [`d1c7c99`](https://github.com/cloudflare/sandbox-sdk/commit/d1c7c99df6555eff71bcd59852e4b8eed2ad8cb6) Thanks [@threepointone](https://github.com/threepointone)! - fix file operations
+
+## 0.0.6
+
+### Patch Changes
+
+- [#9](https://github.com/cloudflare/sandbox-sdk/pull/9) [`24f5470`](https://github.com/cloudflare/sandbox-sdk/commit/24f547048d5a26137de4656cea13d83ad2cc0b43) Thanks [@ItsWendell](https://github.com/ItsWendell)! - fix baseUrl for stub and stub forwarding
+
 ## 0.0.5
 
 ### Patch Changes

package/Dockerfile

@@ -1,16 +1,80 @@
-# syntax=docker/dockerfile:1
+# Sandbox base image with development tools, Python, Node.js, and Bun
+FROM ubuntu:22.04
 
-FROM oven/bun:latest
-# Set destination for COPY
+# Prevent interactive prompts during package installation
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install essential system packages and development tools
+RUN apt-get update && apt-get install -y \
+    # Basic utilities
+    curl \
+    wget \
+    git \
+    unzip \
+    zip \
+    # Process management
+    procps \
+    htop \
+    # Build tools
+    build-essential \
+    pkg-config \
+    # Network tools
+    net-tools \
+    iputils-ping \
+    dnsutils \
+    # Text processing
+    jq \
+    vim \
+    nano \
+    # Python dependencies
+    python3.11 \
+    python3.11-dev \
+    python3-pip \
+    # Other useful tools
+    sudo \
+    ca-certificates \
+    gnupg \
+    lsb-release \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set Python 3.11 as default python3
+RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1
+
+# Install Node.js 22 LTS
+# Using the official NodeSource repository setup script
+RUN apt-get update && apt-get install -y ca-certificates curl gnupg \
+    && mkdir -p /etc/apt/keyrings \
+    && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
+    && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list \
+    && apt-get update \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Bun using the official installation script
+RUN curl -fsSL https://bun.sh/install | bash \
+    && mv /root/.bun/bin/bun /usr/local/bin/bun \
+    && mv /root/.bun/bin/bunx /usr/local/bin/bunx \
+    && rm -rf /root/.bun
+
+# Install global npm packages as root
+RUN npm install -g yarn pnpm
+
+# Set up working directory
 WORKDIR /app
 
-# Install git
-RUN apt-get update && apt-get install -y git
+# Verify installations
+RUN python3 --version && \
+    node --version && \
+    npm --version && \
+    bun --version && \
+    yarn --version && \
+    pnpm --version
 
-COPY container_src/* ./
-# RUN bun install
+# Copy container source files
+COPY container_src/ ./
 
+# Expose the application port
 EXPOSE 3000
-# Run
-CMD ["bun", "index.ts"]
 
+# Run the application
+CMD ["bun", "index.ts"]

package/README.md

@@ -47,19 +47,319 @@ import { getSandbox } from "@cloudflare/sandbox";
 export default {
   async fetch(request: Request, env: Env) {
     const sandbox = getSandbox(env.Sandbox, "my-sandbox");
-    return sandbox.exec("ls", ["-la"]);
+    const result = await sandbox.exec("ls -la");
+    return Response.json(result);
   },
 };
 ```
 
-### Methods:
-
-- `exec(command: string, args: string[], options?: { stream?: boolean })`: Execute a command in the sandbox.
-- `gitCheckout(repoUrl: string, options: { branch?: string; targetDir?: string; stream?: boolean })`: Checkout a git repository in the sandbox.
-- `mkdir(path: string, options: { recursive?: boolean; stream?: boolean })`: Create a directory in the sandbox.
-- `writeFile(path: string, content: string, options: { encoding?: string; stream?: boolean })`: Write content to a file in the sandbox.
-- `readFile(path: string, options: { encoding?: string; stream?: boolean })`: Read content from a file in the sandbox.
-- `deleteFile(path: string, options?: { stream?: boolean })`: Delete a file from the sandbox.
-- `renameFile(oldPath: string, newPath: string, options?: { stream?: boolean })`: Rename a file in the sandbox.
-- `moveFile(sourcePath: string, destinationPath: string, options?: { stream?: boolean })`: Move a file from one location to another in the sandbox.
-- `ping()`: Ping the sandbox.
+### Core Methods
+
+#### Command Execution
+- `exec(command: string, options?: ExecOptions)`: Execute a command and return the complete result.
+- `execStream(command: string, options?: StreamOptions)`: Execute a command with real-time streaming (returns ReadableStream).
+
+#### Process Management
+- `startProcess(command: string, options?: ProcessOptions)`: Start a background process.
+- `listProcesses()`: List all running processes.
+- `getProcess(id: string)`: Get details of a specific process.
+- `killProcess(id: string, signal?: string)`: Kill a specific process.
+- `killAllProcesses()`: Kill all running processes.
+- `streamProcessLogs(processId: string, options?: { signal?: AbortSignal })`: Stream logs from a running process (returns ReadableStream).
+
+#### File Operations
+- `gitCheckout(repoUrl: string, options: { branch?: string; targetDir?: string })`: Checkout a git repository.
+- `mkdir(path: string, options?: { recursive?: boolean })`: Create a directory.
+- `writeFile(path: string, content: string, options?: { encoding?: string })`: Write content to a file.
+- `readFile(path: string, options?: { encoding?: string })`: Read content from a file.
+- `deleteFile(path: string)`: Delete a file.
+- `renameFile(oldPath: string, newPath: string)`: Rename a file.
+- `moveFile(sourcePath: string, destinationPath: string)`: Move a file.
+
+#### Port Management
+- `exposePort(port: number, options: { name?: string; hostname: string })`: Expose a port for external access.
+- `unexposePort(port: number)`: Unexpose a previously exposed port.
+- `getExposedPorts(hostname: string)`: List all exposed ports with their preview URLs.
+
+### Beautiful AsyncIterable Streaming APIs ✨
+
+The SDK provides streaming methods that return `ReadableStream` for RPC compatibility, along with a `parseSSEStream` utility to convert them to typed AsyncIterables:
+
+#### Stream Command Output
+```typescript
+import { parseSSEStream, type ExecEvent } from '@cloudflare/sandbox';
+
+// Get the stream and convert to AsyncIterable
+const stream = await sandbox.execStream('npm run build');
+for await (const event of parseSSEStream<ExecEvent>(stream)) {
+  switch (event.type) {
+    case 'start':
+      console.log(`Build started: ${event.command}`);
+      break;
+    case 'stdout':
+      console.log(`[OUT] ${event.data}`);
+      break;
+    case 'stderr':
+      console.error(`[ERR] ${event.data}`);
+      break;
+    case 'complete':
+      console.log(`Build finished with exit code: ${event.exitCode}`);
+      break;
+    case 'error':
+      console.error(`Build error: ${event.error}`);
+      break;
+  }
+}
+```
+
+#### Stream Process Logs
+```typescript
+import { parseSSEStream, type LogEvent } from '@cloudflare/sandbox';
+
+// Monitor background process logs
+const webServer = await sandbox.startProcess('node server.js');
+
+const logStream = await sandbox.streamProcessLogs(webServer.id);
+for await (const log of parseSSEStream<LogEvent>(logStream)) {
+  if (log.type === 'stdout') {
+    console.log(`Server: ${log.data}`);
+  } else if (log.type === 'stderr' && log.data.includes('ERROR')) {
+    // React to errors
+    await handleError(log);
+  } else if (log.type === 'exit') {
+    console.log(`Server exited with code: ${log.exitCode}`);
+    break;
+  }
+}
+```
+
+#### Why parseSSEStream?
+
+The streaming methods return `ReadableStream<Uint8Array>` to ensure compatibility across Durable Object RPC boundaries. The `parseSSEStream` utility converts these streams into typed AsyncIterables, giving you the best of both worlds:
+
+- **RPC Compatibility**: ReadableStream can be serialized across process boundaries
+- **Beautiful APIs**: AsyncIterable provides clean `for await` syntax with typed events
+- **Type Safety**: Full TypeScript support with `ExecEvent` and `LogEvent` types
+
+#### Advanced Examples
+
+##### CI/CD Build System
+```typescript
+import { parseSSEStream, type ExecEvent } from '@cloudflare/sandbox';
+
+export async function runBuild(env: Env, buildId: string) {
+  const sandbox = getSandbox(env.Sandbox, buildId);
+  const buildLog: string[] = [];
+
+  try {
+    const stream = await sandbox.execStream('npm run build');
+    for await (const event of parseSSEStream<ExecEvent>(stream)) {
+      buildLog.push(`[${event.type}] ${event.data || ''}`);
+
+      if (event.type === 'complete') {
+        await env.BUILDS.put(buildId, {
+          status: event.exitCode === 0 ? 'success' : 'failed',
+          exitCode: event.exitCode,
+          logs: buildLog.join('\n'),
+          duration: Date.now() - new Date(event.timestamp).getTime()
+        });
+      }
+    }
+  } catch (error) {
+    await env.BUILDS.put(buildId, {
+      status: 'error',
+      error: error.message,
+      logs: buildLog.join('\n')
+    });
+  }
+}
+```
+
+##### System Monitoring
+```typescript
+import { parseSSEStream, type LogEvent } from '@cloudflare/sandbox';
+
+export default {
+  async scheduled(controller: ScheduledController, env: Env) {
+    const sandbox = getSandbox(env.Sandbox, 'monitor');
+
+    // Monitor system logs
+    const monitor = await sandbox.startProcess('journalctl -f');
+
+    const logStream = await sandbox.streamProcessLogs(monitor.id);
+    for await (const log of parseSSEStream<LogEvent>(logStream)) {
+      if (log.type === 'stdout') {
+        // Check for critical errors
+        if (log.data.includes('CRITICAL')) {
+          await env.ALERTS.send({
+            severity: 'critical',
+            message: log.data,
+            timestamp: log.timestamp
+          });
+        }
+
+        // Store logs
+        await env.LOGS.put(`${log.timestamp}-${monitor.id}`, log.data);
+      }
+    }
+  }
+}
+```
+
+##### Streaming to Frontend via SSE
+```typescript
+// Worker endpoint that streams to frontend
+app.get('/api/build/:id/stream', async (req, env) => {
+  const sandbox = getSandbox(env.Sandbox, req.params.id);
+  const encoder = new TextEncoder();
+
+  return new Response(
+    new ReadableStream({
+      async start(controller) {
+        try {
+          for await (const event of sandbox.execStream('npm run build')) {
+            // Forward events to frontend as SSE
+            const sseEvent = `data: ${JSON.stringify(event)}\n\n`;
+            controller.enqueue(encoder.encode(sseEvent));
+          }
+        } catch (error) {
+          const errorEvent = `data: ${JSON.stringify({
+            type: 'error',
+            error: error.message
+          })}\n\n`;
+          controller.enqueue(encoder.encode(errorEvent));
+        } finally {
+          controller.close();
+        }
+      }
+    }),
+    {
+      headers: {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache'
+      }
+    }
+  );
+});
+```
+
+### Streaming Utilities
+
+The SDK exports additional utilities for working with SSE streams:
+
+#### `parseSSEStream`
+Converts a `ReadableStream<Uint8Array>` (from SSE endpoints) into a typed `AsyncIterable<T>`. This is the primary utility for consuming streams from the SDK.
+
+```typescript
+import { parseSSEStream, type ExecEvent } from '@cloudflare/sandbox';
+
+const stream = await sandbox.execStream('npm build');
+for await (const event of parseSSEStream<ExecEvent>(stream)) {
+  console.log(event);
+}
+```
+
+#### `responseToAsyncIterable`
+Converts a `Response` object with SSE content directly to `AsyncIterable<T>`. Useful when fetching from external SSE endpoints.
+
+```typescript
+import { responseToAsyncIterable, type LogEvent } from '@cloudflare/sandbox';
+
+// Fetch from an external SSE endpoint
+const response = await fetch('https://api.example.com/logs/stream', {
+  headers: { 'Accept': 'text/event-stream' }
+});
+
+// Convert Response to typed AsyncIterable
+for await (const event of responseToAsyncIterable<LogEvent>(response)) {
+  console.log(`[${event.type}] ${event.data}`);
+}
+```
+
+#### `asyncIterableToSSEStream`
+Converts an `AsyncIterable<T>` into an SSE-formatted `ReadableStream<Uint8Array>`. Perfect for Worker endpoints that need to transform or filter events before sending to clients.
+
+```typescript
+import { getSandbox, parseSSEStream, asyncIterableToSSEStream, type LogEvent } from '@cloudflare/sandbox';
+
+export async function handleFilteredLogs(request: Request, env: Env) {
+  const sandbox = getSandbox(env.SANDBOX);
+  
+  // Custom async generator that filters logs
+  async function* filterLogs() {
+    const stream = await sandbox.streamProcessLogs('web-server');
+    
+    for await (const log of parseSSEStream<LogEvent>(stream)) {
+      // Only forward error logs to the client
+      if (log.type === 'stderr' || log.data.includes('ERROR')) {
+        yield log;
+      }
+    }
+  }
+
+  // Convert filtered AsyncIterable back to SSE stream for the response
+  const sseStream = asyncIterableToSSEStream(filterLogs());
+  
+  return new Response(sseStream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+    }
+  });
+}
+```
+
+**Advanced Example - Merging Multiple Streams:**
+```typescript
+async function* mergeBuilds(env: Env) {
+  const sandbox1 = getSandbox(env.SANDBOX1);
+  const sandbox2 = getSandbox(env.SANDBOX2);
+  
+  // Start builds in parallel
+  const [stream1, stream2] = await Promise.all([
+    sandbox1.execStream('npm run build:frontend'),
+    sandbox2.execStream('npm run build:backend')
+  ]);
+  
+  // Parse and merge events
+  const frontend = parseSSEStream<ExecEvent>(stream1);
+  const backend = parseSSEStream<ExecEvent>(stream2);
+  
+  // Merge with source identification
+  for await (const event of frontend) {
+    yield { ...event, source: 'frontend' };
+  }
+  for await (const event of backend) {
+    yield { ...event, source: 'backend' };
+  }
+}
+
+// Convert merged stream to SSE for client
+const mergedSSE = asyncIterableToSSEStream(mergeBuilds(env));
+```
+
+### Cancellation Support
+
+Both streaming methods support cancellation via AbortSignal:
+
+```typescript
+const controller = new AbortController();
+
+// Cancel after 30 seconds
+setTimeout(() => controller.abort(), 30000);
+
+try {
+  for await (const event of sandbox.execStream('long-running-task', {
+    signal: controller.signal
+  })) {
+    // Process events
+    if (shouldCancel(event)) {
+      controller.abort();
+    }
+  }
+} catch (error) {
+  if (error.message.includes('aborted')) {
+    console.log('Operation cancelled');
+  }
+}
+```