@cloudflare/sandbox 0.0.0-6d1b288 → 0.0.0-6f16c81

package/src/index.ts

@@ -1,79 +1,14 @@
-import { Container, getContainer } from "@cloudflare/containers";
-import { HttpClient } from "./client";
-
-export function getSandbox(ns: DurableObjectNamespace<Sandbox>, id: string) {
-  return getContainer(ns, id);
-}
-
-export class Sandbox<Env = unknown> extends Container<Env> {
-  defaultPort = 3000; // The default port for the container to listen on
-  sleepAfter = "3m"; // Sleep the sandbox if no requests are made in this timeframe
-
-  client: HttpClient = new HttpClient({
-    onCommandComplete: (success, exitCode, stdout, stderr, command, args) => {
-      console.log(
-        `[Container] Command completed: ${command}, Success: ${success}, Exit code: ${exitCode}`
-      );
-    },
-    onCommandStart: (command, args) => {
-      console.log(`[Container] Command started: ${command} ${args.join(" ")}`);
-    },
-    onError: (error, command, args) => {
-      console.error(`[Container] Command error: ${error}`);
-    },
-    onOutput: (stream, data, command) => {
-      console.log(`[Container] [${stream}] ${data}`);
-    },
-    port: this.defaultPort,
-  });
-
-  envVars = {
-    MESSAGE: "I was passed in via the Sandbox class!",
-  };
-
-  override onStart() {
-    console.log("Sandbox successfully started");
-  }
-
-  override onStop() {
-    console.log("Sandbox successfully shut down");
-    if (this.client) {
-      this.client.clearSession();
-    }
-  }
-
-  override onError(error: unknown) {
-    console.log("Sandbox error:", error);
-  }
-
-  async exec(command: string, args: string[], options?: { stream?: boolean }) {
-    if (options?.stream) {
-      return this.client.executeStream(command, args);
-    }
-    return this.client.execute(command, args);
-  }
-
-  async gitCheckout(
-    repoUrl: string,
-    options: { branch?: string; targetDir?: string; stream?: boolean }
-  ) {
-    if (options?.stream) {
-      return this.client.gitCheckoutStream(
-        repoUrl,
-        options.branch,
-        options.targetDir
-      );
-    }
-    return this.client.gitCheckout(repoUrl, options.branch, options.targetDir);
-  }
-
-  async mkdir(
-    path: string,
-    options: { recursive?: boolean; stream?: boolean }
-  ) {
-    if (options?.stream) {
-      return this.client.mkdirStream(path, options.recursive);
-    }
-    return this.client.mkdir(path, options.recursive);
-  }
-}
+// Export types from client
+export type {
+  DeleteFileResponse, ExecuteResponse,
+  GitCheckoutResponse,
+  MkdirResponse, MoveFileResponse,
+  ReadFileResponse, RenameFileResponse, WriteFileResponse
+} from "./client";
+
+// Re-export request handler utilities
+export {
+  proxyToSandbox, type RouteInfo, type SandboxEnv
+} from './request-handler';
+
+export { getSandbox, Sandbox } from "./sandbox";

package/src/request-handler.ts

@@ -0,0 +1,95 @@
+import { getSandbox, type Sandbox } from "./sandbox";
+
+export interface SandboxEnv {
+  Sandbox: DurableObjectNamespace<Sandbox>;
+}
+
+export interface RouteInfo {
+  port: number;
+  sandboxId: string;
+  path: string;
+}
+
+export async function proxyToSandbox<E extends SandboxEnv>(
+  request: Request,
+  env: E
+): Promise<Response | null> {
+  try {
+    const url = new URL(request.url);
+    const routeInfo = extractSandboxRoute(url);
+
+    if (!routeInfo) {
+      return null; // Not a request to an exposed container port
+    }
+
+    const { sandboxId, port, path } = routeInfo;
+    const sandbox = getSandbox(env.Sandbox, sandboxId);
+
+    // Build proxy request with proper headers
+    let proxyUrl: string;
+
+    // Route based on the target port
+    if (port !== 3000) {
+      // Route directly to user's service on the specified port
+      proxyUrl = `http://localhost:${port}${path}${url.search}`;
+    } else {
+      // Port 3000 is our control plane - route normally
+      proxyUrl = `http://localhost:3000${path}${url.search}`;
+    }
+
+    const proxyRequest = new Request(proxyUrl, {
+      method: request.method,
+      headers: {
+        ...Object.fromEntries(request.headers),
+        'X-Original-URL': request.url,
+        'X-Forwarded-Host': url.hostname,
+        'X-Forwarded-Proto': url.protocol.replace(':', ''),
+        'X-Sandbox-Name': sandboxId, // Pass the friendly name
+      },
+      body: request.body,
+    });
+
+    return sandbox.containerFetch(proxyRequest, port);
+  } catch (error) {
+    console.error('[Sandbox] Proxy routing error:', error);
+    return new Response('Proxy routing error', { status: 500 });
+  }
+}
+
+function extractSandboxRoute(url: URL): RouteInfo | null {
+  // Production: subdomain pattern {port}-{sandboxId}.{domain}
+  const subdomainMatch = url.hostname.match(/^(\d+)-([a-zA-Z0-9-]+)\./);
+  if (subdomainMatch) {
+    return {
+      port: parseInt(subdomainMatch[1]),
+      sandboxId: subdomainMatch[2],
+      path: url.pathname,
+    };
+  }
+
+  // Development: path pattern /preview/{port}/{sandboxId}/*
+  if (isLocalhostPattern(url.hostname)) {
+    const pathMatch = url.pathname.match(/^\/preview\/(\d+)\/([^/]+)(\/.*)?$/);
+    if (pathMatch) {
+      return {
+        port: parseInt(pathMatch[1]),
+        sandboxId: pathMatch[2],
+        path: pathMatch[3] || "/",
+      };
+    }
+  }
+
+  return null;
+}
+
+export function isLocalhostPattern(hostname: string): boolean {
+  const hostPart = hostname.split(":")[0];
+  return (
+    hostPart === "localhost" ||
+    hostPart === "127.0.0.1" ||
+    hostPart === "::1" ||
+    hostPart === "[::1]" ||
+    hostPart === "0.0.0.0"
+  );
+}
+

package/src/sandbox.ts

@@ -0,0 +1,252 @@
+import { Container, getContainer } from "@cloudflare/containers";
+import { HttpClient } from "./client";
+import { isLocalhostPattern } from "./request-handler";
+
+export function getSandbox(ns: DurableObjectNamespace<Sandbox>, id: string) {
+  const stub = getContainer(ns, id);
+
+  // Store the name on first access
+  stub.setSandboxName?.(id);
+
+  return stub;
+}
+
+export class Sandbox<Env = unknown> extends Container<Env> {
+  sleepAfter = "3m"; // Sleep the sandbox if no requests are made in this timeframe
+  client: HttpClient;
+  private workerHostname: string | null = null;
+  private sandboxName: string | null = null;
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    this.client = new HttpClient({
+      onCommandComplete: (success, exitCode, _stdout, _stderr, command, _args) => {
+        console.log(
+          `[Container] Command completed: ${command}, Success: ${success}, Exit code: ${exitCode}`
+        );
+      },
+      onCommandStart: (command, args) => {
+        console.log(
+          `[Container] Command started: ${command} ${args.join(" ")}`
+        );
+      },
+      onError: (error, _command, _args) => {
+        console.error(`[Container] Command error: ${error}`);
+      },
+      onOutput: (stream, data, _command) => {
+        console.log(`[Container] [${stream}] ${data}`);
+      },
+      port: 3000, // Control plane port
+      stub: this,
+    });
+
+    // Load the sandbox name from storage on initialization
+    this.ctx.blockConcurrencyWhile(async () => {
+      this.sandboxName = await this.ctx.storage.get<string>('sandboxName') || null;
+    });
+  }
+
+  // RPC method to set the sandbox name
+  async setSandboxName(name: string): Promise<void> {
+    if (!this.sandboxName) {
+      this.sandboxName = name;
+      await this.ctx.storage.put('sandboxName', name);
+      console.log(`[Sandbox] Stored sandbox name via RPC: ${name}`);
+    }
+  }
+
+  override onStart() {
+    console.log("Sandbox successfully started");
+  }
+
+  override onStop() {
+    console.log("Sandbox successfully shut down");
+    if (this.client) {
+      this.client.clearSession();
+    }
+  }
+
+  override onError(error: unknown) {
+    console.log("Sandbox error:", error);
+  }
+
+  // Override fetch to capture the hostname and route to appropriate ports
+  override async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+
+    // Capture the hostname from the first request
+    if (!this.workerHostname) {
+      this.workerHostname = url.hostname;
+      console.log(`[Sandbox] Captured hostname: ${this.workerHostname}`);
+    }
+
+    // Capture and store the sandbox name from the header if present
+    if (!this.sandboxName && request.headers.has('X-Sandbox-Name')) {
+      const name = request.headers.get('X-Sandbox-Name')!;
+      this.sandboxName = name;
+      await this.ctx.storage.put('sandboxName', name);
+      console.log(`[Sandbox] Stored sandbox name: ${this.sandboxName}`);
+    }
+
+    // Determine which port to route to
+    const port = this.determinePort(url);
+
+    // Route to the appropriate port
+    return await this.containerFetch(request, port);
+  }
+
+  private determinePort(url: URL): number {
+    // Extract port from proxy requests (e.g., /proxy/8080/*)
+    const proxyMatch = url.pathname.match(/^\/proxy\/(\d+)/);
+    if (proxyMatch) {
+      return parseInt(proxyMatch[1]);
+    }
+
+    // All other requests go to control plane on port 3000
+    // This includes /api/* endpoints and any other control requests
+    return 3000;
+  }
+
+  async exec(command: string, args: string[], options?: { stream?: boolean; background?: boolean }) {
+    if (options?.stream) {
+      return this.client.executeStream(command, args, undefined, options?.background);
+    }
+    return this.client.execute(command, args, undefined, options?.background);
+  }
+
+  async gitCheckout(
+    repoUrl: string,
+    options: { branch?: string; targetDir?: string; stream?: boolean }
+  ) {
+    if (options?.stream) {
+      return this.client.gitCheckoutStream(
+        repoUrl,
+        options.branch,
+        options.targetDir
+      );
+    }
+    return this.client.gitCheckout(repoUrl, options.branch, options.targetDir);
+  }
+
+  async mkdir(
+    path: string,
+    options: { recursive?: boolean; stream?: boolean } = {}
+  ) {
+    if (options?.stream) {
+      return this.client.mkdirStream(path, options.recursive);
+    }
+    return this.client.mkdir(path, options.recursive);
+  }
+
+  async writeFile(
+    path: string,
+    content: string,
+    options: { encoding?: string; stream?: boolean } = {}
+  ) {
+    if (options?.stream) {
+      return this.client.writeFileStream(path, content, options.encoding);
+    }
+    return this.client.writeFile(path, content, options.encoding);
+  }
+
+  async deleteFile(path: string, options: { stream?: boolean } = {}) {
+    if (options?.stream) {
+      return this.client.deleteFileStream(path);
+    }
+    return this.client.deleteFile(path);
+  }
+
+  async renameFile(
+    oldPath: string,
+    newPath: string,
+    options: { stream?: boolean } = {}
+  ) {
+    if (options?.stream) {
+      return this.client.renameFileStream(oldPath, newPath);
+    }
+    return this.client.renameFile(oldPath, newPath);
+  }
+
+  async moveFile(
+    sourcePath: string,
+    destinationPath: string,
+    options: { stream?: boolean } = {}
+  ) {
+    if (options?.stream) {
+      return this.client.moveFileStream(sourcePath, destinationPath);
+    }
+    return this.client.moveFile(sourcePath, destinationPath);
+  }
+
+  async readFile(
+    path: string,
+    options: { encoding?: string; stream?: boolean } = {}
+  ) {
+    if (options?.stream) {
+      return this.client.readFileStream(path, options.encoding);
+    }
+    return this.client.readFile(path, options.encoding);
+  }
+
+  async exposePort(port: number, options?: { name?: string }) {
+    await this.client.exposePort(port, options?.name);
+
+    // We need the sandbox name to construct preview URLs
+    if (!this.sandboxName) {
+      throw new Error('Sandbox name not available. Ensure sandbox is accessed through getSandbox()');
+    }
+
+    const hostname = this.getHostname();
+    const url = this.constructPreviewUrl(port, this.sandboxName, hostname);
+
+    return {
+      url,
+      port,
+      name: options?.name,
+    };
+  }
+
+  async unexposePort(port: number) {
+    await this.client.unexposePort(port);
+  }
+
+  async getExposedPorts() {
+    const response = await this.client.getExposedPorts();
+
+    // We need the sandbox name to construct preview URLs
+    if (!this.sandboxName) {
+      throw new Error('Sandbox name not available. Ensure sandbox is accessed through getSandbox()');
+    }
+
+    const hostname = this.getHostname();
+
+    return response.ports.map(port => ({
+      url: this.constructPreviewUrl(port.port, this.sandboxName!, hostname),
+      port: port.port,
+      name: port.name,
+      exposedAt: port.exposedAt,
+    }));
+  }
+
+  private getHostname(): string {
+    // Use the captured hostname or fall back to localhost for development
+    return this.workerHostname || "localhost:8787";
+  }
+
+  private constructPreviewUrl(port: number, sandboxId: string, hostname: string): string {
+    // Check if this is a localhost pattern
+    const isLocalhost = isLocalhostPattern(hostname);
+
+    if (isLocalhost) {
+      // For local development, we need to use a different approach
+      // Since subdomains don't work with localhost, we'll use the base URL
+      // with a note that the user needs to handle routing differently
+      return `http://${hostname}/preview/${port}/${sandboxId}`;
+    }
+
+    // For all other domains (workers.dev, custom domains, etc.)
+    // Use subdomain-based routing pattern
+    const protocol = hostname.includes(":") ? "http" : "https";
+    return `${protocol}://${port}-${sandboxId}.${hostname}`;
+  }
+}

package/tests/test2.ts

@@ -7,6 +7,8 @@ import {
   quickExecuteStream,
   quickMoveFile,
   quickMoveFileStream,
+  quickReadFile,
+  quickReadFileStream,
   quickRenameFile,
   quickRenameFileStream,
   quickWriteFile,
@@ -683,6 +685,223 @@ async function testHttpClient() {
     );
   }
 
+  // Test 25: File reading
+  console.log("Test 25: File reading");
+  try {
+    // First create a file to read
+    const readContent = "This is a test file for reading\nLine 2\nLine 3";
+    await quickWriteFile("file-to-read.txt", readContent);
+    console.log("✅ Test file created for reading");
+
+    // Read the file
+    const result = await quickReadFile("file-to-read.txt");
+    console.log("✅ File read successfully:", result.success);
+    console.log("   Path:", result.path);
+    console.log("   Content length:", result.content.length, "characters");
+    console.log("   Exit code:", result.exitCode);
+
+    // Verify the content
+    console.log("✅ File content verified:", result.content === readContent);
+    console.log("   Content:", result.content);
+    console.log("✅ File reading test completed\n");
+  } catch (error) {
+    console.error("❌ Test 25 failed:", error);
+  }
+
+  // Test 26: File reading with custom encoding
+  console.log("Test 26: File reading with custom encoding");
+  try {
+    // Create a file with special characters
+    const specialContent = "Hello 世界! 🌍 Test with emojis and unicode";
+    await quickWriteFile("special-chars.txt", specialContent, "utf-8");
+    console.log("✅ Special characters file created");
+
+    // Read with explicit UTF-8 encoding
+    const result = await quickReadFile("special-chars.txt", "utf-8");
+    console.log(
+      "✅ Special characters file read successfully:",
+      result.success
+    );
+    console.log(
+      "✅ Special characters verified:",
+      result.content === specialContent
+    );
+    console.log("   Content:", result.content);
+    console.log("✅ Custom encoding test completed\n");
+  } catch (error) {
+    console.error("❌ Test 26 failed:", error);
+  }
+
+  // Test 27: File reading in nested directories
+  console.log("Test 27: File reading in nested directories");
+  try {
+    // Create a file in a nested directory
+    const nestedContent = "This file is in a nested directory for reading";
+    await quickWriteFile("nested/read/test-nested-read.txt", nestedContent);
+    console.log("✅ Nested file created for reading");
+
+    // Read the nested file
+    const result = await quickReadFile("nested/read/test-nested-read.txt");
+    console.log("✅ Nested file read successfully:", result.success);
+    console.log(
+      "✅ Nested file content verified:",
+      result.content === nestedContent
+    );
+    console.log("   Content:", result.content);
+    console.log("✅ Nested directory reading test completed\n");
+  } catch (error) {
+    console.error("❌ Test 27 failed:", error);
+  }
+
+  // Test 28: Streaming file reading
+  console.log("Test 28: Streaming file reading");
+  try {
+    const client = createClient();
+    await client.createSession();
+
+    // Create a file to read via streaming
+    const streamReadContent =
+      "This file will be read via streaming\nLine 2\nLine 3";
+    await client.writeFile("stream-read-file.txt", streamReadContent);
+    console.log("✅ Test file created for streaming reading");
+
+    let readContent = "";
+    let readCompleted = false;
+
+    // Set up event handlers for streaming
+    client.setOnStreamEvent((event) => {
+      if (event.type === "command_complete" && event.content) {
+        readContent = event.content;
+        readCompleted = true;
+      }
+    });
+
+    console.log("   Starting streaming file reading...");
+    await client.readFileStream("stream-read-file.txt");
+    console.log("✅ Streaming file reading completed");
+
+    // Verify the content was read correctly
+    console.log(
+      "✅ Streaming read content verified:",
+      readContent === streamReadContent
+    );
+    console.log("   Content length:", readContent.length, "characters");
+
+    client.clearSession();
+    console.log("✅ Streaming file reading test completed\n");
+  } catch (error) {
+    console.error("❌ Test 28 failed:", error);
+  }
+
+  // Test 29: Quick streaming file reading
+  console.log("Test 29: Quick streaming file reading");
+  try {
+    // Create a file for quick streaming read
+    const quickReadContent = "Quick streaming read test content";
+    await quickWriteFile("quick-read-stream.txt", quickReadContent);
+    console.log("✅ Test file created for quick streaming reading");
+
+    let quickReadContentReceived = "";
+    let quickReadCompleted = false;
+
+    console.log("   Starting quick streaming file reading...");
+    await quickReadFileStream("quick-read-stream.txt", "utf-8", {
+      onStreamEvent: (event) => {
+        if (event.type === "command_complete" && event.content) {
+          quickReadContentReceived = event.content;
+          quickReadCompleted = true;
+        }
+      },
+    });
+    console.log("✅ Quick streaming file reading completed");
+
+    // Verify the content
+    console.log(
+      "✅ Quick streaming read verified:",
+      quickReadContentReceived === quickReadContent
+    );
+    console.log("   Content:", quickReadContentReceived);
+    console.log("✅ Quick streaming file reading test completed\n");
+  } catch (error) {
+    console.error("❌ Test 29 failed:", error);
+  }
+
+  // Test 30: File reading with session management
+  console.log("Test 30: File reading with session management");
+  try {
+    const client = createClient();
+    const sessionId = await client.createSession();
+
+    // Create a file in session
+    const sessionReadContent =
+      "This file was created and read with session management";
+    await client.writeFile(
+      "session-read-file.txt",
+      sessionReadContent,
+      "utf-8",
+      sessionId
+    );
+    console.log("✅ Session file created for reading");
+
+    // Read the file in the same session
+    const result = await client.readFile(
+      "session-read-file.txt",
+      "utf-8",
+      sessionId
+    );
+    console.log("✅ Session file read successfully:", result.success);
+    console.log(
+      "✅ Session file content verified:",
+      result.content === sessionReadContent
+    );
+    console.log("   Session ID:", sessionId);
+    console.log("   Content:", result.content);
+
+    client.clearSession();
+    console.log("✅ Session file reading test completed\n");
+  } catch (error) {
+    console.error("❌ Test 30 failed:", error);
+  }
+
+  // Test 31: Error handling for file reading
+  console.log("Test 31: Error handling for file reading");
+  try {
+    // Try to read a non-existent file
+    await quickReadFile("non-existent-read-file.txt");
+    console.log("❌ Should have failed for non-existent file");
+  } catch (error) {
+    console.log("✅ Error handling works for non-existent files");
+    console.log(
+      "   Error:",
+      error instanceof Error ? error.message : "Unknown error"
+    );
+  }
+
+  try {
+    // Try to read from a dangerous path
+    await quickReadFile("/etc/passwd");
+    console.log("❌ Should have failed for dangerous path");
+  } catch (error) {
+    console.log("✅ Error handling works for dangerous paths");
+    console.log(
+      "   Error:",
+      error instanceof Error ? error.message : "Unknown error"
+    );
+  }
+
+  try {
+    // Try to read with empty path
+    await quickReadFile("");
+    console.log("❌ Should have failed for empty path");
+  } catch (error) {
+    console.log("✅ Error handling works for empty paths");
+    console.log(
+      "   Error:",
+      error instanceof Error ? error.message : "Unknown error",
+      "\n"
+    );
+  }
+
   console.log("🎉 All tests completed!");
 }