@computesdk/cloudflare 1.6.3 → 1.6.5

package/README.md

@@ -1,17 +1,6 @@
 # @computesdk/cloudflare
 
-Cloudflare provider for ComputeSDK - execute code in secure sandboxes on Cloudflare's edge network using Durable Objects.
-
-## Features
-
-- **🔒 Secure Isolation**: Each sandbox runs in its own container with full process isolation
-- **⚡ Edge-Native**: Runs on Cloudflare's global network for low latency worldwide  
-- **📁 Full Filesystem Support**: Read, write, and manage files within the sandbox
-- **🔧 Command Execution**: Run any command or process inside the container
-- **🌐 Port Forwarding**: Expose services running in your sandbox via public URLs
-- **🔄 Git Integration**: Clone repositories directly into sandboxes
-- **🧪 Code Interpreter**: Execute Python and JavaScript with rich outputs
-- **🎮 Session Management**: Maintain state across multiple operations
+Cloudflare provider for ComputeSDK — execute code in secure, isolated sandboxes on Cloudflare's edge network.
 
 ## Installation
 
@@ -19,101 +8,44 @@ Cloudflare provider for ComputeSDK - execute code in secure sandboxes on Cloudfl
 npm install @computesdk/cloudflare
 ```
 
-## Prerequisites
+## Setup
 
-This provider requires a Cloudflare Workers environment with Durable Objects configured. You'll need:
+Run the setup command to deploy a gateway Worker to your Cloudflare account:
 
-Note: Cloudflare API key should include the following permissions:
-- Workers Scripts:Edit
-- Workers KV Storage:Edit
-- Account Settings:Read
-- Workers Scripts:Read
-- Workers KV Storage:Read
-- Workers Tail:Read
+```bash
+npx @computesdk/cloudflare
+```
 
-1. **Cloudflare Workers account** with Durable Objects enabled
-2. **wrangler.toml configuration** with Sandbox Durable Object binding
-3. **Dockerfile** setup (temporary requirement)
+This requires two environment variables:
 
-### Setup Instructions
+- `CLOUDFLARE_API_TOKEN` — a Cloudflare API token with the following permissions:
+  - Workers Scripts: Read & Edit
+  - Workers KV Storage: Read & Edit
+  - Account Settings: Read
+  - Workers Tail: Read
+- `CLOUDFLARE_ACCOUNT_ID` — your Cloudflare account ID
 
-1. **Create a Dockerfile** (temporary requirement):
-```dockerfile
-FROM docker.io/cloudflare/sandbox:0.3.0
+You can set these in a `.env` file or export them in your shell. Get your API token at [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens).
 
-# Expose the ports you want to expose
-EXPOSE 3000
-```
+The setup command will deploy the gateway Worker and output two values:
 
-2. **Configure wrangler.toml**:
-```toml
-[durable_objects]
-bindings = [
-  { name = "Sandbox", class_name = "Sandbox" }
-]
-
-[[migrations]]
-tag = "v1"
-new_sqlite_classes = ["Sandbox"]
-
-[[containers]]
-class_name = "Sandbox"
-image = "./Dockerfile"
-max_instances = 1
 ```
-
-3. **Export the Sandbox class in your Worker**:
-```typescript
-import { getSandbox } from "@cloudflare/sandbox";
-
-// Export the Sandbox class in your Worker
-export { Sandbox } from "@cloudflare/sandbox";
-
-export default {
-  async fetch(request: Request, env: Env) {
-    // Your worker code here
-  },
-};
+CLOUDFLARE_SANDBOX_URL=https://computesdk-sandbox.<subdomain>.workers.dev
+CLOUDFLARE_SANDBOX_SECRET=<generated-secret>
 ```
 
-## Quick Start
+Add these to your `.env` file. These are the only env vars needed at runtime.
 
-### Gateway Mode (Recommended)
-
-Use the gateway for zero-config auto-detection:
-
-```typescript
-import { compute } from 'computesdk';
-
-// Auto-detects from environment (when running in Cloudflare Workers)
-const sandbox = await compute.sandbox.create();
-
-// Execute Python code
-const result = await sandbox.runCode(`
-import sys
-print(f"Python version: {sys.version}")
-print("Hello from Cloudflare!")
-`);
-
-console.log(result.stdout);
-await sandbox.destroy();
-```
+> **Note:** Docker must be installed for the setup command to build the sandbox container image.
 
-### Direct Mode
-
-For direct SDK usage without the gateway:
+## Quick Start
 
 ```typescript
 import { cloudflare } from '@computesdk/cloudflare';
 
-// Initialize with your Durable Object binding
 const compute = cloudflare({
-  sandboxBinding: env.Sandbox, // Your Durable Object binding
-  runtime: 'python',
-  timeout: 300000,
-  envVars: {
-    MY_VAR: 'hello world'
-  }
+  sandboxUrl: process.env.CLOUDFLARE_SANDBOX_URL,
+  sandboxSecret: process.env.CLOUDFLARE_SANDBOX_SECRET,
 });
 
 const sandbox = await compute.sandbox.create();
@@ -125,164 +57,130 @@ print(f"Python version: {sys.version}")
 print("Hello from Cloudflare!")
 `);
 
-console.log(result.stdout);
-
-// Execute shell commands
-const cmdResult = await sandbox.runCommand('ls', ['-la']);
-console.log(cmdResult.stdout);
-
-// File operations
-await sandbox.filesystem.writeFile('/tmp/hello.txt', 'Hello Cloudflare!');
-const content = await sandbox.filesystem.readFile('/tmp/hello.txt');
-console.log(content); // "Hello Cloudflare!"
-
-// Expose a web service
-await sandbox.runCode(`
-import http.server
-import socketserver
-PORT = 3000
-Handler = http.server.SimpleHTTPRequestHandler
-with socketserver.TCPServer(("", PORT), Handler) as httpd:
-    print(f"Server running on port {PORT}")
-    httpd.serve_forever()
-`);
-
-// Get the public URL
-const url = await sandbox.getUrl({ port: 3000 });
-console.log(`Service available at: ${url}`);
-
+console.log(result.output);
 await sandbox.destroy();
 ```
 
-## Advanced Usage
+## Usage
 
-### Runtime Detection
+### Run Code
 
 The provider automatically detects the runtime based on code content:
 
 ```typescript
-// Automatically detected as Python
+// Detected as Python
 await sandbox.runCode('print("Hello Python")');
 
-// Automatically detected as Node.js
+// Detected as Node.js
 await sandbox.runCode('console.log("Hello Node.js")');
 
 // Explicitly specify runtime
 await sandbox.runCode('print("Hello")', 'python');
 ```
 
-### Environment Variables
+### Run Commands
 
 ```typescript
-import { cloudflare } from '@computesdk/cloudflare';
-
-const compute = cloudflare({
-  sandboxBinding: env.Sandbox,
-  envVars: {
-    API_KEY: 'your-api-key',
-    DATABASE_URL: 'postgresql://localhost:5432/mydb',
-    NODE_ENV: 'production'
-  }
-});
+const result = await sandbox.runCommand('ls -la /app');
+console.log(result.stdout);
 ```
 
-### Port Forwarding
+### File System
 
 ```typescript
-// Start a web server
-await sandbox.runCode(`
-const express = require('express');
-const app = express();
-app.get('/', (req, res) => res.json({ message: 'Hello from Cloudflare!' }));
-app.listen(8080);
-`);
-
-// Get public URL
-const url = await sandbox.getUrl({ port: 8080, protocol: 'https' });
-console.log(`API available at: ${url}`);
-```
+// Write and read files
+await sandbox.filesystem.writeFile('/app/config.json', JSON.stringify({ key: 'value' }));
+const content = await sandbox.filesystem.readFile('/app/config.json');
 
-### File System Operations
-
-```typescript
 // Create directories
-await sandbox.filesystem.mkdir('/app');
-
-// Write files
-await sandbox.filesystem.writeFile('/app/package.json', JSON.stringify({
-  name: 'my-app',
-  version: '1.0.0'
-}, null, 2));
-
-// Read files
-const packageJson = await sandbox.filesystem.readFile('/app/package.json');
-const config = JSON.parse(packageJson);
+await sandbox.filesystem.mkdir('/app/data');
 
 // List directory contents
 const files = await sandbox.filesystem.readdir('/app');
-files.forEach(file => {
-  console.log(`${file.name} (${file.isDirectory ? 'dir' : 'file'})`);
-});
 
-// Check if file exists
-if (await sandbox.filesystem.exists('/app/package.json')) {
-  console.log('Package.json found!');
-}
+// Check existence
+const exists = await sandbox.filesystem.exists('/app/config.json');
 
-// Remove files/directories
-await sandbox.filesystem.remove('/app/temp');
+// Remove files
+await sandbox.filesystem.remove('/app/temp.txt');
 ```
 
-### Git Operations
+### Port Forwarding
 
 ```typescript
-// Clone a repository
+// Start a web server in the sandbox
 await sandbox.runCode(`
-import subprocess
-result = subprocess.run([
-  'git', 'clone', 'https://github.com/user/repo.git', '/app'
-], capture_output=True, text=True)
-print(result.stdout)
+import http.server, socketserver
+PORT = 3000
+with socketserver.TCPServer(("", PORT), http.server.SimpleHTTPRequestHandler) as httpd:
+    httpd.serve_forever()
 `);
 
-// Or using the built-in git functionality (if available)
-const result = await sandbox.runCommand('git', [
-  'clone', 
-  'https://github.com/user/repo.git', 
-  '/app'
-]);
+// Get the public URL
+const url = await sandbox.getUrl({ port: 3000 });
+console.log(`Service available at: ${url}`);
+```
+
+### Environment Variables
+
+Pass environment variables to the sandbox at initialization:
+
+```typescript
+const compute = cloudflare({
+  sandboxUrl: process.env.CLOUDFLARE_SANDBOX_URL,
+  sandboxSecret: process.env.CLOUDFLARE_SANDBOX_SECRET,
+  envVars: {
+    API_KEY: 'your-api-key',
+    DATABASE_URL: 'postgresql://localhost:5432/mydb',
+  },
+});
+```
+
+Or per-sandbox at creation time:
+
+```typescript
+const sandbox = await compute.sandbox.create({
+  envs: { NODE_ENV: 'production' },
+});
 ```
 
-## Configuration Options
+## Configuration
 
 ```typescript
 interface CloudflareConfig {
-  /** Cloudflare Sandbox binding from Workers environment (required) */
-  sandboxBinding: any;
-  
-  /** Default runtime environment */
-  runtime?: 'python' | 'node';
-  
-  /** Execution timeout in milliseconds (default: 300000) */
+  /** URL of the deployed gateway Worker */
+  sandboxUrl?: string;
+  /** Shared secret for authenticating with the gateway Worker */
+  sandboxSecret?: string;
+  /** Durable Object binding (direct mode only — see below) */
+  sandboxBinding?: any;
+  /** Default runtime: 'python' | 'node' | 'bun' | 'deno' */
+  runtime?: Runtime;
+  /** Execution timeout in milliseconds */
   timeout?: number;
-  
   /** Environment variables to pass to sandbox */
   envVars?: Record<string, string>;
-  
-  /** Base URL for preview URLs (defaults to worker domain) */
-  baseUrl?: string;
 }
 ```
 
-## Error Handling
+## Direct Mode
+
+If your code already runs inside a Cloudflare Worker, you can skip the gateway and use the Durable Object binding directly:
 
 ```typescript
 import { cloudflare } from '@computesdk/cloudflare';
 
+const compute = cloudflare({
+  sandboxBinding: env.Sandbox,
+});
+```
+
+This requires configuring the Sandbox Durable Object binding in your `wrangler.toml`. See the [Cloudflare Sandbox docs](https://developers.cloudflare.com/sandbox/get-started/) for setup instructions.
+
+## Error Handling
+
+```typescript
 try {
-  const compute = cloudflare({ sandboxBinding: env.Sandbox });
-  const sandbox = await compute.sandbox.create();
-  
   const result = await sandbox.runCode('invalid python syntax');
 } catch (error) {
   if (error.message.includes('Syntax error')) {
@@ -295,24 +193,10 @@ try {
 
 ## Limitations
 
-- Requires Cloudflare Workers environment with Durable Objects
-- Container setup currently requires Docker configuration
 - Resource limits apply based on your Cloudflare plan
 - Some system calls may be restricted in the container environment
-
-## Examples
-
-Check out the [examples directory](../../examples) for complete working examples:
-
-- **Basic Usage**: Simple code execution
-- **Web Server**: Express.js app with public URLs
-- **Data Processing**: Python data analysis with file I/O
-- **CI/CD**: Automated testing and building
+- Listing all sandboxes is not supported — use `getById` to reconnect to a specific sandbox
 
 ## License
 
-MIT
-
-## Contributing
-
-See the [main repository](https://github.com/computesdk/computesdk) for contribution guidelines.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@computesdk/cloudflare",
-  "version": "1.6.3",
+  "version": "1.6.5",
   "description": "Cloudflare provider for ComputeSDK - edge code execution using Cloudflare Workers and Durable Objects",
   "author": "Garrison",
   "license": "MIT",
@@ -23,8 +23,8 @@
   ],
   "dependencies": {
     "@cloudflare/sandbox": "^0.7.18",
-    "@computesdk/provider": "1.0.33",
-    "computesdk": "2.5.3"
+    "@computesdk/provider": "1.2.0",
+    "computesdk": "2.5.4"
   },
   "keywords": [
     "computesdk",
@@ -60,7 +60,7 @@
     "typescript": "^5.0.0",
     "vitest": "^1.0.0",
     "wrangler": "^3.0.0",
-    "@computesdk/test-utils": "1.6.0"
+    "@computesdk/test-utils": "1.6.1"
   },
   "scripts": {
     "build": "tsup",