@cloudflare/sandbox 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @cloudflare/sandbox
 
+## 0.2.2
+
+### Patch Changes
+
+- [#51](https://github.com/cloudflare/sandbox-sdk/pull/51) [`4aceb32`](https://github.com/cloudflare/sandbox-sdk/commit/4aceb3215c836f59afcb88b2b325016b3f623f46) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Handle intermittent interpreter failures and decouple jupyter startup
+
+## 0.2.1
+
+### Patch Changes
+
+- [#49](https://github.com/cloudflare/sandbox-sdk/pull/49) [`d81d2a5`](https://github.com/cloudflare/sandbox-sdk/commit/d81d2a563c9af8947d5444019ed4d6156db563e3) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Implement code interpreter API
+
 ## 0.2.0
 
 ### Minor Changes

package/Dockerfile

@@ -31,6 +31,7 @@ RUN apt-get update && apt-get install -y \
     python3.11 \
     python3.11-dev \
     python3-pip \
+    python3.11-venv \
     # Other useful tools
     sudo \
     ca-certificates \
@@ -41,12 +42,12 @@ RUN apt-get update && apt-get install -y \
 # 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
+# Install Node.js 20 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 \
+    && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.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/*
@@ -55,6 +56,21 @@ RUN apt-get update && apt-get install -y ca-certificates curl gnupg \
 COPY --from=bun-source /usr/local/bin/bun /usr/local/bin/bun
 COPY --from=bun-source /usr/local/bin/bunx /usr/local/bin/bunx
 
+# Install Jupyter and kernels
+RUN pip3 install --no-cache-dir \
+    jupyter \
+    jupyterlab \
+    ipykernel \
+    notebook \
+    matplotlib \
+    numpy \
+    pandas \
+    seaborn \
+    && python3 -m ipykernel install --user --name python3
+
+# Install JavaScript kernel (ijavascript) - using E2B's fork
+RUN npm install -g --unsafe-perm git+https://github.com/e2b-dev/ijavascript.git \
+    && ijsinstall --install=global
 
 # Set up container server directory
 WORKDIR /container-server
@@ -63,16 +79,24 @@ WORKDIR /container-server
 RUN python3 --version && \
     node --version && \
     npm --version && \
-    bun --version
+    bun --version && \
+    jupyter --version && \
+    jupyter kernelspec list
 
 # Copy container source files to server directory
+COPY container_src/package.json ./
+RUN bun install
+
 COPY container_src/ ./
 
 # Create clean workspace directory for users
 RUN mkdir -p /workspace
 
-# Expose the application port
-EXPOSE 3000
+# Expose the application port (3000 for control, 8888 for Jupyter)
+EXPOSE 3000 8888
+
+# Make startup script executable
+RUN chmod +x startup.sh
 
-# Run the application from container server directory
-CMD ["bun", "index.ts"]
+# Use startup script
+CMD ["./startup.sh"]

package/README.md

@@ -17,6 +17,10 @@
   - [Basic Setup](#basic-setup)
 - [📚 API Reference](#api-reference)
   - [Core Methods](#core-methods)
+- [🧪 Code Interpreter](#code-interpreter)
+  - [Code Execution](#code-execution)
+  - [Rich Outputs](#rich-outputs)
+  - [Output Formats](#output-formats)
 - [🌐 Port Forwarding](#port-forwarding)
   - [Utility Methods](#utility-methods)
 - [💡 Examples](#examples)
@@ -24,6 +28,7 @@
   - [Build and Test Code](#build-and-test-code)
   - [Interactive Development Environment](#interactive-development-environment)
   - [Expose Services with Preview URLs](#expose-services-with-preview-urls)
+  - [Data Analysis with Code Interpreter](#data-analysis-with-code-interpreter)
 - [🏗️ Architecture](#architecture)
 - [🛠️ Advanced Usage](#advanced-usage)
   - [AsyncIterable Streaming Support](#asynciterable-streaming-support)
@@ -50,6 +55,9 @@ The Cloudflare Sandbox SDK enables you to run isolated code environments directl
 - **🔄 Git Integration**: Clone repositories directly into sandboxes
 - **🚀 Streaming Support**: Real-time output streaming for long-running commands
 - **🎮 Session Management**: Maintain state across multiple operations
+- **🧪 Code Interpreter**: Execute Python and JavaScript with rich outputs (charts, tables, formatted data)
+- **📊 Multi-Language Support**: Persistent execution contexts for Python and JavaScript/TypeScript
+- **🎨 Rich MIME Types**: Automatic processing of images, HTML, charts, and structured data
 
 <h2 id="quick-start">🚀 Quick Start</h2>
 
@@ -64,7 +72,7 @@ npm install @cloudflare/sandbox
 1. **Create a Dockerfile** (temporary requirement, will be removed in future releases):
 
 ```dockerfile
-FROM docker.io/cloudflare/sandbox:0.2.0
+FROM docker.io/cloudflare/sandbox:0.2.2
 
 # Expose the ports you want to expose
 EXPOSE 3000
@@ -246,6 +254,123 @@ console.log(result.stdout); // "production"
 - `unexposePort(port)` - Remove port exposure
 - `getExposedPorts()` - List all exposed ports with their URLs
 
+<h2 id="code-interpreter">🧪 Code Interpreter</h2>
+
+The Sandbox SDK includes powerful code interpreter capabilities, allowing you to execute Python and JavaScript code with rich outputs including charts, tables, and formatted data.
+
+### Code Execution
+
+#### `createCodeContext(options?)`
+
+Creates a new code execution context with persistent state.
+
+```typescript
+// Create a Python context
+const pythonCtx = await sandbox.createCodeContext({ language: 'python' });
+
+// Create a JavaScript context
+const jsCtx = await sandbox.createCodeContext({ language: 'javascript' });
+```
+
+**Options:**
+- `language`: Programming language (`'python'` | `'javascript'` | `'typescript'`)
+- `cwd`: Working directory (default: `/workspace`)
+- `envVars`: Environment variables for the context
+
+#### `runCode(code, options?)`
+
+Executes code with optional streaming callbacks.
+
+```typescript
+// Simple execution
+const execution = await sandbox.runCode('print("Hello World")', { 
+  context: pythonCtx 
+});
+
+// With streaming callbacks
+await sandbox.runCode(`
+for i in range(5):
+    print(f"Step {i}")
+    time.sleep(1)
+`, { 
+  context: pythonCtx,
+  onStdout: (output) => console.log('Real-time:', output.text),
+  onResult: (result) => console.log('Result:', result)
+});
+```
+
+**Options:**
+- `context`: Context to run the code in
+- `language`: Language if no context provided
+- `onStdout`: Callback for stdout output
+- `onStderr`: Callback for stderr output
+- `onResult`: Callback for execution results
+- `onError`: Callback for errors
+
+#### `runCodeStream(code, options?)`
+
+Returns a streaming response for real-time processing.
+
+```typescript
+const stream = await sandbox.runCodeStream('import time; [print(i) for i in range(10)]');
+// Process the stream as needed
+```
+
+### Rich Outputs
+
+The code interpreter automatically detects and processes various output types:
+
+```typescript
+// Data visualization
+const execution = await sandbox.runCode(`
+import matplotlib.pyplot as plt
+import numpy as np
+
+x = np.linspace(0, 10, 100)
+y = np.sin(x)
+plt.plot(x, y)
+plt.title('Sine Wave')
+plt.show()
+`, { 
+  context: pythonCtx,
+  onResult: (result) => {
+    if (result.png) {
+      // Base64 encoded PNG image
+      console.log('Chart generated!');
+    }
+  }
+});
+
+// HTML tables with pandas
+const tableExecution = await sandbox.runCode(`
+import pandas as pd
+df = pd.DataFrame({
+    'name': ['Alice', 'Bob', 'Charlie'],
+    'score': [92, 88, 95]
+})
+df
+`, { context: pythonCtx });
+
+// Access HTML table in execution.results[0].html
+```
+
+### Output Formats
+
+Results can include multiple formats:
+- `text`: Plain text representation
+- `html`: HTML (often pandas DataFrames)
+- `png`/`jpeg`: Base64 encoded images
+- `svg`: Vector graphics
+- `json`: Structured data
+- `chart`: Parsed chart information
+
+Check available formats with `result.formats()`.
+
+#### Additional Code Interpreter Methods
+
+- `listCodeContexts()` - List all active code contexts
+- `deleteCodeContext(contextId)` - Delete a specific context
+
 <h2 id="port-forwarding">🌐 Port Forwarding</h2>
 
 The SDK automatically handles preview URL routing for exposed ports. Just add one line to your worker:
@@ -404,14 +529,100 @@ console.log(`Service available at: ${preview.url}`);
 // See the example in examples/basic/src/index.ts for the routing implementation.
 ```
 
+### Data Analysis with Code Interpreter
+
+```typescript
+const sandbox = getSandbox(env.Sandbox, "analysis");
+
+// Create a Python context for data analysis
+const pythonCtx = await sandbox.createCodeContext({ language: 'python' });
+
+// Load and analyze data
+const analysis = await sandbox.runCode(`
+import pandas as pd
+import matplotlib.pyplot as plt
+
+# Create sample data
+data = {
+    'Month': ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
+    'Sales': [10000, 12000, 15000, 14000, 18000],
+    'Profit': [2000, 2500, 3200, 2800, 4000]
+}
+df = pd.DataFrame(data)
+
+# Display summary statistics
+print("Sales Summary:")
+print(df.describe())
+
+# Create visualization
+plt.figure(figsize=(10, 6))
+plt.subplot(1, 2, 1)
+plt.bar(df['Month'], df['Sales'])
+plt.title('Monthly Sales')
+plt.xlabel('Month')
+plt.ylabel('Sales ($)')
+
+plt.subplot(1, 2, 2)
+plt.plot(df['Month'], df['Profit'], marker='o', color='green')
+plt.title('Monthly Profit')
+plt.xlabel('Month')
+plt.ylabel('Profit ($)')
+
+plt.tight_layout()
+plt.show()
+
+# Return the data as JSON
+df.to_dict('records')
+`, { 
+  context: pythonCtx,
+  onResult: (result) => {
+    if (result.png) {
+      // Handle the chart image
+      console.log('Chart generated:', result.png.substring(0, 50) + '...');
+    }
+    if (result.json) {
+      // Handle the structured data
+      console.log('Data:', result.json);
+    }
+  }
+});
+
+// Multi-language workflow: Process in Python, analyze in JavaScript
+await sandbox.runCode(`
+# Save processed data
+df.to_json('/tmp/sales_data.json', orient='records')
+`, { context: pythonCtx });
+
+const jsCtx = await sandbox.createCodeContext({ language: 'javascript' });
+const jsAnalysis = await sandbox.runCode(`
+const fs = require('fs');
+const data = JSON.parse(fs.readFileSync('/tmp/sales_data.json', 'utf8'));
+
+// Calculate growth rate
+const growth = data.map((curr, idx) => {
+  if (idx === 0) return { ...curr, growth: 0 };
+  const prev = data[idx - 1];
+  return {
+    ...curr,
+    growth: ((curr.Sales - prev.Sales) / prev.Sales * 100).toFixed(2) + '%'
+  };
+});
+
+console.log('Growth Analysis:', growth);
+growth;
+`, { context: jsCtx });
+```
+
 <h2 id="architecture">🏗️ Architecture</h2>
 
 The SDK leverages Cloudflare's infrastructure:
 
 - **Durable Objects**: Manages sandbox lifecycle and state
-- **Containers**: Provides isolated execution environments
+- **Containers**: Provides isolated execution environments with Jupyter kernels
 - **Workers**: Handles HTTP routing and API interface
 - **Edge Network**: Enables global distribution and low latency
+- **Jupyter Integration**: Python (IPython) and JavaScript (TSLab) kernels for code execution
+- **MIME Processing**: Automatic detection and handling of rich output formats
 
 <h2 id="advanced-usage">🛠️ Advanced Usage</h2>
 
@@ -521,6 +732,9 @@ sandbox.client.onCommandComplete = (success, code) =>
 - Maximum container runtime is limited by Durable Object constraints
 - WebSocket support for preview URLs coming soon
 - Some system calls may be restricted in the container environment
+- Code interpreter has no internet access (sandbox restriction)
+- Some Python/JavaScript packages may not be pre-installed
+- Resource limits apply to code execution (CPU, memory)
 
 <h2 id="contributing">🤝 Contributing</h2>
 
@@ -534,11 +748,21 @@ cd sandbox-sdk
 # Install dependencies
 npm install
 
+# Install Bun (if not already installed)
+# Visit https://bun.sh for installation instructions
+curl -fsSL https://bun.sh/install | bash
+
+# Install container dependencies (required for TypeScript checking)
+cd packages/sandbox/container_src && bun install && cd -
+
 # Run tests
 npm test
 
 # Build the project
 npm run build
+
+# Run type checking and linting
+npm run check
 ```
 
 <h2 id="license">📄 License</h2>

package/container_src/bun.lock

@@ -0,0 +1,122 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "sandbox-server",
+      "dependencies": {
+        "@jupyterlab/services": "^7.0.0",
+        "uuid": "^9.0.1",
+        "ws": "^8.16.0",
+      },
+      "devDependencies": {
+        "@types/uuid": "^9.0.7",
+        "@types/ws": "^8.5.10",
+      },
+    },
+  },
+  "packages": {
+    "@jupyter/ydoc": ["@jupyter/ydoc@3.1.0", "", { "dependencies": { "@jupyterlab/nbformat": "^3.0.0 || ^4.0.0-alpha.21 || ^4.0.0", "@lumino/coreutils": "^1.11.0 || ^2.0.0", "@lumino/disposable": "^1.10.0 || ^2.0.0", "@lumino/signaling": "^1.10.0 || ^2.0.0", "y-protocols": "^1.0.5", "yjs": "^13.5.40" } }, "sha512-+hLNUBZr8Zz8NiuaoYKINDURDJHbjFGxg8EcSU52y+rBe412TsoFxfPSng4eP7w3cZFrVlm7D+8K0nAMHxj0ZQ=="],
+
+    "@jupyterlab/coreutils": ["@jupyterlab/coreutils@6.4.5", "", { "dependencies": { "@lumino/coreutils": "^2.2.1", "@lumino/disposable": "^2.1.4", "@lumino/signaling": "^2.1.4", "minimist": "~1.2.0", "path-browserify": "^1.0.0", "url-parse": "~1.5.4" } }, "sha512-fNEefnqTNP/3alrmGYDb0Mu1heS5Cu39FIDiDDoZuuWv4bsdE2xf7VaStuwjljsQm7VZwi5aeholi1+ciBkZKg=="],
+
+    "@jupyterlab/nbformat": ["@jupyterlab/nbformat@4.4.5", "", { "dependencies": { "@lumino/coreutils": "^2.2.1" } }, "sha512-VOlm1klsb1LUNp47AL8iDZPP71pXu9a+WqukJFuuWVxg//+iR6wdqTYcunE9Lx/7SZDqMsXGD+doBZC36Lzenw=="],
+
+    "@jupyterlab/services": ["@jupyterlab/services@7.4.5", "", { "dependencies": { "@jupyter/ydoc": "^3.0.4", "@jupyterlab/coreutils": "^6.4.5", "@jupyterlab/nbformat": "^4.4.5", "@jupyterlab/settingregistry": "^4.4.5", "@jupyterlab/statedb": "^4.4.5", "@lumino/coreutils": "^2.2.1", "@lumino/disposable": "^2.1.4", "@lumino/polling": "^2.1.4", "@lumino/properties": "^2.0.3", "@lumino/signaling": "^2.1.4", "ws": "^8.11.0" } }, "sha512-JEr8+4VS2MqFyYHh4AnpK/g5V0qRBpmnfXmU0p9YFjcIgGR365D8JF0880IJ0e8+jaW88gSAvZFB8x3o9xRoAQ=="],
+
+    "@jupyterlab/settingregistry": ["@jupyterlab/settingregistry@4.4.5", "", { "dependencies": { "@jupyterlab/nbformat": "^4.4.5", "@jupyterlab/statedb": "^4.4.5", "@lumino/commands": "^2.3.2", "@lumino/coreutils": "^2.2.1", "@lumino/disposable": "^2.1.4", "@lumino/signaling": "^2.1.4", "@rjsf/utils": "^5.13.4", "ajv": "^8.12.0", "json5": "^2.2.3" }, "peerDependencies": { "react": ">=16" } }, "sha512-6hEBq3qI99VZwO97W0AM0mP1is57bWC8Vk2xudic1a90wA9G6ovUBzayqSMm/6QhTuIbCY+vruznwhhsLrVMeg=="],
+
+    "@jupyterlab/statedb": ["@jupyterlab/statedb@4.4.5", "", { "dependencies": { "@lumino/commands": "^2.3.2", "@lumino/coreutils": "^2.2.1", "@lumino/disposable": "^2.1.4", "@lumino/properties": "^2.0.3", "@lumino/signaling": "^2.1.4" } }, "sha512-UpqhOujKwoWoxtNBL2Qk0nrw+ORLJ3ckwiJg2eA0CI+n5kO3IBYAnPzak0tSS0mQNspayXr3KAm4GQ80op5yuA=="],
+
+    "@lumino/algorithm": ["@lumino/algorithm@2.0.3", "", {}, "sha512-DIcF7cIrGEC1Wh8DNjdwaL7IdcNs4Jj1VjO/90oHefeQPszKgc6DSfCxvbQiRanKR6tl/JL7tq4ZRPZES2oVAA=="],
+
+    "@lumino/commands": ["@lumino/commands@2.3.2", "", { "dependencies": { "@lumino/algorithm": "^2.0.3", "@lumino/coreutils": "^2.2.1", "@lumino/disposable": "^2.1.4", "@lumino/domutils": "^2.0.3", "@lumino/keyboard": "^2.0.3", "@lumino/signaling": "^2.1.4", "@lumino/virtualdom": "^2.0.3" } }, "sha512-aAFEiUpp2hrkQU82Z85w1L80g0iDzsQRncLBa+pqVR/k0k1lz6H9F6xZ1ff+lBumZKKtsxBxNomvd0hfxLLqGw=="],
+
+    "@lumino/coreutils": ["@lumino/coreutils@2.2.1", "", { "dependencies": { "@lumino/algorithm": "^2.0.3" } }, "sha512-yij4TnxDIum7xfFUsVvZB0oLv4shs2mNbn3juwtEIsruvVBPmurNzKX0Y8z2QetbP2AZ6MSFtBzEKsihf0H0VA=="],
+
+    "@lumino/disposable": ["@lumino/disposable@2.1.4", "", { "dependencies": { "@lumino/signaling": "^2.1.4" } }, "sha512-qTJiDbglPE2QnG4x4gtBcRbcfKQibxyyinNGKcNDrcK2TGTbbhK5PpMQ8d70l2V2Xw2pb/LfksBAg5pxkJ/G4A=="],
+
+    "@lumino/domutils": ["@lumino/domutils@2.0.3", "", {}, "sha512-bXAbZg3mf2ZDNdBBpCGDike3U+osRGHePTh8H2Ud2KwaN4g/5IryFJm/TiO4K5IYs91bWF2Zqhf3FsdbZKHlGw=="],
+
+    "@lumino/keyboard": ["@lumino/keyboard@2.0.3", "", {}, "sha512-bU2OxAR8a9eNBdV0YFjU6/lVVpbOw1gM7yHOuDGDdNu4J0UpKapFoR9gopNGSaHTmTwDtx9RHdFfIAgHwjZ+VQ=="],
+
+    "@lumino/polling": ["@lumino/polling@2.1.4", "", { "dependencies": { "@lumino/coreutils": "^2.2.1", "@lumino/disposable": "^2.1.4", "@lumino/signaling": "^2.1.4" } }, "sha512-gSkxlIJ/4/esY2G7bsRrY9A4KimDMHTo0shaD+MCbhd09fZMCWJoDMcA447/dykB1rM5NXgugNLjpdGGL/e8cw=="],
+
+    "@lumino/properties": ["@lumino/properties@2.0.3", "", {}, "sha512-zkXIU5uYz/ScHCHGl5Bt4gMYsfPxZEduZd80zqDslBWvTIMro3NnzLe66NMnecbdr5N3hDJagYyA8//Qy3XjiA=="],
+
+    "@lumino/signaling": ["@lumino/signaling@2.1.4", "", { "dependencies": { "@lumino/algorithm": "^2.0.3", "@lumino/coreutils": "^2.2.1" } }, "sha512-nC5Z6d9om369Jkh1Vp3b7C89hV4cjr1fQDVcxhemyKXwc9r6VW7FpKixC+jElcAknP5KLj1FAa8Np+K06mMkEA=="],
+
+    "@lumino/virtualdom": ["@lumino/virtualdom@2.0.3", "", { "dependencies": { "@lumino/algorithm": "^2.0.3" } }, "sha512-q2C8eBxPvvOOQjN3KuxZ+vJi082JH/GF7KwMdaWsy5g+7wjKdnXPuLQFTBLOrVqIzmbxBDlLeFr93CEhdQXcyQ=="],
+
+    "@rjsf/utils": ["@rjsf/utils@5.24.12", "", { "dependencies": { "json-schema-merge-allof": "^0.8.1", "jsonpointer": "^5.0.1", "lodash": "^4.17.21", "lodash-es": "^4.17.21", "react-is": "^18.2.0" }, "peerDependencies": { "react": "^16.14.0 || >=17" } }, "sha512-fDwQB0XkjZjpdFUz5UAnuZj8nnbxDbX5tp+jTOjjJKw2TMQ9gFFYCQ12lSpdhezA2YgEGZfxyYTGW0DKDL5Drg=="],
+
+    "@types/node": ["@types/node@24.1.0", "", { "dependencies": { "undici-types": "~7.8.0" } }, "sha512-ut5FthK5moxFKH2T1CUOC6ctR67rQRvvHdFLCD2Ql6KXmMuCrjsSsRI9UsLCm9M18BMwClv4pn327UvB7eeO1w=="],
+
+    "@types/uuid": ["@types/uuid@9.0.8", "", {}, "sha512-jg+97EGIcY9AGHJJRaaPVgetKDsrTgbRjQ5Msgjh/DQKEFl0DtyRr/VCOyD1T2R1MNeWPK/u7JoGhlDZnKBAfA=="],
+
+    "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
+
+    "ajv": ["ajv@8.17.1", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g=="],
+
+    "compute-gcd": ["compute-gcd@1.2.1", "", { "dependencies": { "validate.io-array": "^1.0.3", "validate.io-function": "^1.0.2", "validate.io-integer-array": "^1.0.0" } }, "sha512-TwMbxBNz0l71+8Sc4czv13h4kEqnchV9igQZBi6QUaz09dnz13juGnnaWWJTRsP3brxOoxeB4SA2WELLw1hCtg=="],
+
+    "compute-lcm": ["compute-lcm@1.1.2", "", { "dependencies": { "compute-gcd": "^1.2.1", "validate.io-array": "^1.0.3", "validate.io-function": "^1.0.2", "validate.io-integer-array": "^1.0.0" } }, "sha512-OFNPdQAXnQhDSKioX8/XYT6sdUlXwpeMjfd6ApxMJfyZ4GxmLR1xvMERctlYhlHwIiz6CSpBc2+qYKjHGZw4TQ=="],
+
+    "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
+
+    "fast-uri": ["fast-uri@3.0.6", "", {}, "sha512-Atfo14OibSv5wAp4VWNsFYE1AchQRTv9cBGWET4pZWHzYshFSS9NQI6I57rdKn9croWVMbYFbLhJ+yJvmZIIHw=="],
+
+    "isomorphic.js": ["isomorphic.js@0.2.5", "", {}, "sha512-PIeMbHqMt4DnUP3MA/Flc0HElYjMXArsw1qwJZcm9sqR8mq3l8NYizFMty0pWwE/tzIGH3EKK5+jes5mAr85yw=="],
+
+    "json-schema-compare": ["json-schema-compare@0.2.2", "", { "dependencies": { "lodash": "^4.17.4" } }, "sha512-c4WYmDKyJXhs7WWvAWm3uIYnfyWFoIp+JEoX34rctVvEkMYCPGhXtvmFFXiffBbxfZsvQ0RNnV5H7GvDF5HCqQ=="],
+
+    "json-schema-merge-allof": ["json-schema-merge-allof@0.8.1", "", { "dependencies": { "compute-lcm": "^1.1.2", "json-schema-compare": "^0.2.2", "lodash": "^4.17.20" } }, "sha512-CTUKmIlPJbsWfzRRnOXz+0MjIqvnleIXwFTzz+t9T86HnYX/Rozria6ZVGLktAU9e+NygNljveP+yxqtQp/Q4w=="],
+
+    "json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
+
+    "json5": ["json5@2.2.3", "", { "bin": { "json5": "lib/cli.js" } }, "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg=="],
+
+    "jsonpointer": ["jsonpointer@5.0.1", "", {}, "sha512-p/nXbhSEcu3pZRdkW1OfJhpsVtW1gd4Wa1fnQc9YLiTfAjn0312eMKimbdIQzuZl9aa9xUGaRlP9T/CJE/ditQ=="],
+
+    "lib0": ["lib0@0.2.114", "", { "dependencies": { "isomorphic.js": "^0.2.4" }, "bin": { "0gentesthtml": "bin/gentesthtml.js", "0serve": "bin/0serve.js", "0ecdsa-generate-keypair": "bin/0ecdsa-generate-keypair.js" } }, "sha512-gcxmNFzA4hv8UYi8j43uPlQ7CGcyMJ2KQb5kZASw6SnAKAf10hK12i2fjrS3Cl/ugZa5Ui6WwIu1/6MIXiHttQ=="],
+
+    "lodash": ["lodash@4.17.21", "", {}, "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg=="],
+
+    "lodash-es": ["lodash-es@4.17.21", "", {}, "sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw=="],
+
+    "minimist": ["minimist@1.2.8", "", {}, "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA=="],
+
+    "path-browserify": ["path-browserify@1.0.1", "", {}, "sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g=="],
+
+    "querystringify": ["querystringify@2.2.0", "", {}, "sha512-FIqgj2EUvTa7R50u0rGsyTftzjYmv/a3hO345bZNrqabNqjtgiDMgmo4mkUjd+nzU5oF3dClKqFIPUKybUyqoQ=="],
+
+    "react": ["react@19.1.1", "", {}, "sha512-w8nqGImo45dmMIfljjMwOGtbmC/mk4CMYhWIicdSflH91J9TyCyczcPFXJzrZ/ZXcgGRFeP6BU0BEJTw6tZdfQ=="],
+
+    "react-is": ["react-is@18.3.1", "", {}, "sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg=="],
+
+    "require-from-string": ["require-from-string@2.0.2", "", {}, "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw=="],
+
+    "requires-port": ["requires-port@1.0.0", "", {}, "sha512-KigOCHcocU3XODJxsu8i/j8T9tzT4adHiecwORRQ0ZZFcp7ahwXuRU1m+yuO90C5ZUyGeGfocHDI14M3L3yDAQ=="],
+
+    "undici-types": ["undici-types@7.8.0", "", {}, "sha512-9UJ2xGDvQ43tYyVMpuHlsgApydB8ZKfVYTsLDhXkFL/6gfkp+U8xTGdh8pMJv1SpZna0zxG1DwsKZsreLbXBxw=="],
+
+    "url-parse": ["url-parse@1.5.10", "", { "dependencies": { "querystringify": "^2.1.1", "requires-port": "^1.0.0" } }, "sha512-WypcfiRhfeUP9vvF0j6rw0J3hrWrw6iZv3+22h6iRMJ/8z1Tj6XfLP4DsUix5MhMPnXpiHDoKyoZ/bdCkwBCiQ=="],
+
+    "uuid": ["uuid@9.0.1", "", { "bin": { "uuid": "dist/bin/uuid" } }, "sha512-b+1eJOlsR9K8HJpow9Ok3fiWOWSIcIzXodvv0rQjVoOVNpWMpxf1wZNpt4y9h10odCNrqnYp1OBzRktckBe3sA=="],
+
+    "validate.io-array": ["validate.io-array@1.0.6", "", {}, "sha512-DeOy7CnPEziggrOO5CZhVKJw6S3Yi7e9e65R1Nl/RTN1vTQKnzjfvks0/8kQ40FP/dsjRAOd4hxmJ7uLa6vxkg=="],
+
+    "validate.io-function": ["validate.io-function@1.0.2", "", {}, "sha512-LlFybRJEriSuBnUhQyG5bwglhh50EpTL2ul23MPIuR1odjO7XaMLFV8vHGwp7AZciFxtYOeiSCT5st+XSPONiQ=="],
+
+    "validate.io-integer": ["validate.io-integer@1.0.5", "", { "dependencies": { "validate.io-number": "^1.0.3" } }, "sha512-22izsYSLojN/P6bppBqhgUDjCkr5RY2jd+N2a3DCAUey8ydvrZ/OkGvFPR7qfOpwR2LC5p4Ngzxz36g5Vgr/hQ=="],
+
+    "validate.io-integer-array": ["validate.io-integer-array@1.0.0", "", { "dependencies": { "validate.io-array": "^1.0.3", "validate.io-integer": "^1.0.4" } }, "sha512-mTrMk/1ytQHtCY0oNO3dztafHYyGU88KL+jRxWuzfOmQb+4qqnWmI+gykvGp8usKZOM0H7keJHEbRaFiYA0VrA=="],
+
+    "validate.io-number": ["validate.io-number@1.0.3", "", {}, "sha512-kRAyotcbNaSYoDnXvb4MHg/0a1egJdLwS6oJ38TJY7aw9n93Fl/3blIXdyYvPOp55CNxywooG/3BcrwNrBpcSg=="],
+
+    "ws": ["ws@8.18.3", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-PEIGCY5tSlUt50cqyMXfCzX+oOPqN0vuGqWzbcJ2xvnkzkq46oOpz7dQaTDBdfICb4N14+GARUDw2XV2N4tvzg=="],
+
+    "y-protocols": ["y-protocols@1.0.6", "", { "dependencies": { "lib0": "^0.2.85" }, "peerDependencies": { "yjs": "^13.0.0" } }, "sha512-vHRF2L6iT3rwj1jub/K5tYcTT/mEYDUppgNPXwp8fmLpui9f7Yeq3OEtTLVF012j39QnV+KEQpNqoN7CWU7Y9Q=="],
+
+    "yjs": ["yjs@13.6.27", "", { "dependencies": { "lib0": "^0.2.99" } }, "sha512-OIDwaflOaq4wC6YlPBy2L6ceKeKuF7DeTxx+jPzv1FHn9tCZ0ZwSRnUBxD05E3yed46fv/FWJbvR+Ud7x0L7zw=="],
+  }
+}

package/container_src/circuit-breaker.ts

@@ -0,0 +1,121 @@
+/**
+ * Circuit Breaker implementation to prevent cascading failures
+ */
+export class CircuitBreaker {
+  private failures = 0;
+  private lastFailure: number = 0;
+  private successCount = 0;
+  private state: "closed" | "open" | "half-open" = "closed";
+
+  // Configuration
+  private readonly threshold: number;
+  private readonly timeout: number;
+  private readonly halfOpenSuccessThreshold: number;
+  private readonly name: string;
+
+  constructor(options: {
+    name: string;
+    threshold?: number;
+    timeout?: number;
+    halfOpenSuccessThreshold?: number;
+  }) {
+    this.name = options.name;
+    this.threshold = options.threshold || 5;
+    this.timeout = options.timeout || 30000; // 30 seconds
+    this.halfOpenSuccessThreshold = options.halfOpenSuccessThreshold || 3;
+  }
+
+  /**
+   * Execute an operation with circuit breaker protection
+   */
+  async execute<T>(operation: () => Promise<T>): Promise<T> {
+    // Check circuit state
+    if (this.state === "open") {
+      if (Date.now() - this.lastFailure > this.timeout) {
+        console.log(
+          `[CircuitBreaker ${this.name}] Transitioning from open to half-open`
+        );
+        this.state = "half-open";
+        this.successCount = 0;
+      } else {
+        throw new Error(
+          `Circuit breaker is open for ${this.name}. Retry after ${
+            this.timeout - (Date.now() - this.lastFailure)
+          }ms`
+        );
+      }
+    }
+
+    try {
+      const result = await operation();
+
+      // Record success
+      if (this.state === "half-open") {
+        this.successCount++;
+        if (this.successCount >= this.halfOpenSuccessThreshold) {
+          console.log(
+            `[CircuitBreaker ${this.name}] Transitioning from half-open to closed`
+          );
+          this.state = "closed";
+          this.failures = 0;
+        }
+      } else if (this.state === "closed") {
+        // Reset failure count on success
+        this.failures = 0;
+      }
+
+      return result;
+    } catch (error) {
+      this.recordFailure();
+      throw error;
+    }
+  }
+
+  /**
+   * Record a failure and update circuit state
+   */
+  private recordFailure() {
+    this.failures++;
+    this.lastFailure = Date.now();
+
+    if (this.state === "half-open") {
+      console.log(
+        `[CircuitBreaker ${this.name}] Failure in half-open state, transitioning to open`
+      );
+      this.state = "open";
+    } else if (this.failures >= this.threshold) {
+      console.log(
+        `[CircuitBreaker ${this.name}] Threshold reached (${this.failures}/${this.threshold}), transitioning to open`
+      );
+      this.state = "open";
+    }
+  }
+
+  /**
+   * Get current circuit breaker state
+   */
+  getState(): {
+    state: string;
+    failures: number;
+    lastFailure: number;
+    isOpen: boolean;
+  } {
+    return {
+      state: this.state,
+      failures: this.failures,
+      lastFailure: this.lastFailure,
+      isOpen: this.state === "open",
+    };
+  }
+
+  /**
+   * Reset the circuit breaker
+   */
+  reset() {
+    this.state = "closed";
+    this.failures = 0;
+    this.successCount = 0;
+    this.lastFailure = 0;
+    console.log(`[CircuitBreaker ${this.name}] Reset to closed state`);
+  }
+}