@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/cloudflare-deploy/references/containers/api.md

@@ -0,0 +1,187 @@
+## Container Class API
+
+```typescript
+import { Container } from "@cloudflare/containers";
+
+export class MyContainer extends Container {
+  defaultPort = 8080;
+  requiredPorts = [8080];
+  sleepAfter = "30m";
+  enableInternet = true;
+  pingEndpoint = "/health";
+  envVars = {};
+  entrypoint = [];
+
+  onStart() { /* container started */ }
+  onStop() { /* container stopping */ }
+  onError(error: Error) { /* container error */ }
+  onActivityExpired(): boolean { /* timeout, return true to stay alive */ }
+  async alarm() { /* scheduled task */ }
+}
+```
+
+## Routing
+
+**getByName(id)** - Named instance for session affinity, per-user state
+**getRandom()** - Random instance for load balancing stateless services
+
+```typescript
+const container = env.MY_CONTAINER.getByName("user-123");
+const container = env.MY_CONTAINER.getRandom();
+```
+
+## Startup Methods
+
+### start() - Basic start (8s timeout)
+
+```typescript
+await container.start();
+await container.start({ envVars: { KEY: "value" } });
+```
+
+Returns when **process starts**, NOT when ports ready. Use for fire-and-forget.
+
+### startAndWaitForPorts() - Recommended (20s timeout)
+
+```typescript
+await container.startAndWaitForPorts();  // Uses requiredPorts
+await container.startAndWaitForPorts({ ports: [8080, 9090] });
+await container.startAndWaitForPorts({ 
+  ports: [8080],
+  startOptions: { envVars: { KEY: "value" } }
+});
+```
+
+Returns when **ports listening**. Use before HTTP/TCP requests.
+
+**Port resolution:** explicit ports → requiredPorts → defaultPort → port 33
+
+### waitForPort() - Wait for specific port
+
+```typescript
+await container.waitForPort(8080);
+await container.waitForPort(8080, { timeout: 30000 });
+```
+
+## Communication
+
+### fetch() - HTTP with WebSocket support
+
+```typescript
+// ✅ Supports WebSocket upgrades
+const response = await container.fetch(request);
+const response = await container.fetch("http://container/api", {
+  method: "POST",
+  body: JSON.stringify({ data: "value" })
+});
+```
+
+**Use for:** All HTTP, especially WebSocket.
+
+### containerFetch() - HTTP only (no WebSocket)
+
+```typescript
+// ❌ No WebSocket support
+const response = await container.containerFetch(request);
+```
+
+**⚠️ Critical:** Use `fetch()` for WebSocket, not `containerFetch()`.
+
+### TCP Connections
+
+```typescript
+const port = this.ctx.container.getTcpPort(8080);
+const conn = port.connect();
+await conn.opened;
+
+if (request.body) await request.body.pipeTo(conn.writable);
+return new Response(conn.readable);
+```
+
+### switchPort() - Change default port
+
+```typescript
+this.switchPort(8081);  // Subsequent fetch() uses this port
+```
+
+## Lifecycle Hooks
+
+### onStart()
+
+Called when container process starts (ports may not be ready). Runs in `blockConcurrencyWhile` - no concurrent requests.
+
+```typescript
+onStart() {
+  console.log("Container starting");
+}
+```
+
+### onStop()
+
+Called when SIGTERM received. 15 minutes until SIGKILL. Use for graceful shutdown.
+
+```typescript
+onStop() {
+  // Save state, close connections, flush logs
+}
+```
+
+### onError()
+
+Called when container crashes or fails to start.
+
+```typescript
+onError(error: Error) {
+  console.error("Container error:", error);
+}
+```
+
+### onActivityExpired()
+
+Called when `sleepAfter` timeout reached. Return `true` to stay alive, `false` to stop.
+
+```typescript
+onActivityExpired(): boolean {
+  if (this.hasActiveConnections()) return true;  // Keep alive
+  return false;  // OK to stop
+}
+```
+
+## Scheduling
+
+```typescript
+export class ScheduledContainer extends Container {
+  async fetch(request: Request) {
+    await this.schedule(Date.now() + 60000);  // 1 minute
+    await this.schedule("2026-01-28T00:00:00Z");  // ISO string
+    return new Response("Scheduled");
+  }
+
+  async alarm() {
+    // Called when schedule fires (SQLite-backed, survives restarts)
+  }
+}
+```
+
+**⚠️ Don't override `alarm()` directly when using `schedule()` helper.**
+
+## State Inspection
+
+### External state check
+
+```typescript
+const state = await container.getState();
+// state.status: "starting" | "running" | "stopping" | "stopped"
+```
+
+### Internal state check
+
+```typescript
+export class MyContainer extends Container {
+  async fetch(request: Request) {
+    if (this.ctx.container.running) { ... }
+  }
+}
+```
+
+**⚠️ Use `getState()` for external checks, `ctx.container.running` for internal.**

package/skills/cloudflare-deploy/references/containers/configuration.md

@@ -0,0 +1,188 @@
+## Wrangler Configuration
+
+### Basic Container Config
+
+```jsonc
+{
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-01-10",
+  "containers": [
+    {
+      "class_name": "MyContainer",
+      "image": "./Dockerfile",  // Path to Dockerfile or directory with Dockerfile
+      "instance_type": "standard-1",  // Predefined or custom (see below)
+      "max_instances": 10
+    }
+  ],
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "MY_CONTAINER",
+        "class_name": "MyContainer"
+      }
+    ]
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["MyContainer"]  // Must use new_sqlite_classes
+    }
+  ]
+}
+```
+
+Key config requirements:
+- `image` - Path to Dockerfile or directory containing Dockerfile
+- `class_name` - Must match Container class export name
+- `max_instances` - Max concurrent container instances
+- Must configure Durable Objects binding AND migrations
+
+### Instance Types
+
+#### Predefined Types
+
+| Type | vCPU | Memory | Disk |
+|------|------|--------|------|
+| lite | 1/16 | 256 MiB | 2 GB |
+| basic | 1/4 | 1 GiB | 4 GB |
+| standard-1 | 1/2 | 4 GiB | 8 GB |
+| standard-2 | 1 | 6 GiB | 12 GB |
+| standard-3 | 2 | 8 GiB | 16 GB |
+| standard-4 | 4 | 12 GiB | 20 GB |
+
+```jsonc
+{
+  "containers": [
+    {
+      "class_name": "MyContainer",
+      "image": "./Dockerfile",
+      "instance_type": "standard-2"  // Use predefined type
+    }
+  ]
+}
+```
+
+#### Custom Types (Jan 2026 Feature)
+
+```jsonc
+{
+  "containers": [
+    {
+      "class_name": "MyContainer",
+      "image": "./Dockerfile",
+      "instance_type_custom": {
+        "vcpu": 2,              // 1-4 vCPU
+        "memory_mib": 8192,     // 512-12288 MiB (up to 12 GiB)
+        "disk_mib": 16384       // 2048-20480 MiB (up to 20 GB)
+      }
+    }
+  ]
+}
+```
+
+**Custom type constraints:**
+- Minimum 3 GiB memory per vCPU
+- Maximum 2 GB disk per 1 GiB memory
+- Max 4 vCPU, 12 GiB memory, 20 GB disk per container
+
+### Account Limits
+
+| Resource | Limit | Notes |
+|----------|-------|-------|
+| Total memory (all containers) | 400 GiB | Across all running containers |
+| Total vCPU (all containers) | 100 | Across all running containers |
+| Total disk (all containers) | 2 TB | Across all running containers |
+| Image storage per account | 50 GB | Stored container images |
+
+### Container Class Properties
+
+```typescript
+import { Container } from "@cloudflare/containers";
+
+export class MyContainer extends Container {
+  // Port Configuration
+  defaultPort = 8080;             // Default port for fetch() calls
+  requiredPorts = [8080, 9090];   // Ports to wait for in startAndWaitForPorts()
+
+  // Lifecycle
+  sleepAfter = "30m";             // Inactivity timeout (5m, 30m, 2h, etc.)
+
+  // Network
+  enableInternet = true;          // Allow outbound internet access
+
+  // Health Check
+  pingEndpoint = "/health";       // Health check endpoint path
+
+  // Environment
+  envVars = {                     // Environment variables passed to container
+    NODE_ENV: "production",
+    LOG_LEVEL: "info"
+  };
+
+  // Startup
+  entrypoint = ["/bin/start.sh"]; // Override image entrypoint (optional)
+}
+```
+
+**Property details:**
+
+- **`defaultPort`**: Port used when calling `container.fetch()` without explicit port. Falls back to port 33 if not set.
+
+- **`requiredPorts`**: Array of ports that must be listening before `startAndWaitForPorts()` returns. First port becomes default if `defaultPort` not set.
+
+- **`sleepAfter`**: Duration string (e.g., "5m", "30m", "2h"). Container stops after this period of inactivity. Timer resets on each request.
+
+- **`enableInternet`**: Boolean. If `true`, container can make outbound HTTP/TCP requests.
+
+- **`pingEndpoint`**: Path used for health checks. Should respond with 2xx status.
+
+- **`envVars`**: Object of environment variables. Merged with runtime-provided vars (see below).
+
+- **`entrypoint`**: Array of strings. Overrides container image's CMD/ENTRYPOINT.
+
+### Runtime Environment Variables
+
+Cloudflare automatically provides these environment variables to containers:
+
+| Variable | Description |
+|----------|-------------|
+| `CLOUDFLARE_APPLICATION_ID` | Worker application ID |
+| `CLOUDFLARE_COUNTRY_A2` | Two-letter country code of request origin |
+| `CLOUDFLARE_LOCATION` | Cloudflare data center location |
+| `CLOUDFLARE_REGION` | Region identifier |
+| `CLOUDFLARE_DURABLE_OBJECT_ID` | Container's Durable Object ID |
+
+Custom `envVars` from Container class are merged with these. Custom vars override runtime vars if names conflict.
+
+### Image Management
+
+**Distribution model:** Images pre-fetched to all global locations before deployment. Ensures fast cold starts (2-3s typical).
+
+**Rolling deploys:** Unlike Workers (instant), container deployments roll out gradually. Old versions continue running during rollout.
+
+**Ephemeral disk:** Container disk is ephemeral and resets on each stop. Use Durable Object storage (`this.ctx.storage`) for persistence.
+
+## wrangler.toml Format
+
+```toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2026-01-10"
+
+[[containers]]
+class_name = "MyContainer"
+image = "./Dockerfile"
+instance_type = "standard-2"
+max_instances = 10
+
+[[durable_objects.bindings]]
+name = "MY_CONTAINER"
+class_name = "MyContainer"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["MyContainer"]
+```
+
+Both `wrangler.jsonc` and `wrangler.toml` are supported. Use `wrangler.jsonc` for comments and better IDE support.

package/skills/cloudflare-deploy/references/containers/gotchas.md

@@ -0,0 +1,178 @@
+## Critical Gotchas
+
+### ⚠️ WebSocket: fetch() vs containerFetch()
+
+**Problem:** WebSocket connections fail silently
+
+**Cause:** `containerFetch()` doesn't support WebSocket upgrades
+
+**Fix:** Always use `fetch()` for WebSocket
+
+```typescript
+// ❌ WRONG
+return container.containerFetch(request);
+
+// ✅ CORRECT
+return container.fetch(request);
+```
+
+### ⚠️ startAndWaitForPorts() vs start()
+
+**Problem:** "connection refused" after `start()`
+
+**Cause:** `start()` returns when process starts, NOT when ports ready
+
+**Fix:** Use `startAndWaitForPorts()` before requests
+
+```typescript
+// ❌ WRONG
+await container.start();
+return container.fetch(request);
+
+// ✅ CORRECT
+await container.startAndWaitForPorts();
+return container.fetch(request);
+```
+
+### ⚠️ Activity Timeout on Long Operations
+
+**Problem:** Container stops during long work
+
+**Cause:** `sleepAfter` based on request activity, not internal work
+
+**Fix:** Renew timeout by touching storage
+
+```typescript
+const interval = setInterval(() => {
+  this.ctx.storage.put("keepalive", Date.now());
+}, 60000);
+
+try {
+  await this.doLongWork(data);
+} finally {
+  clearInterval(interval);
+}
+```
+
+### ⚠️ blockConcurrencyWhile for Startup
+
+**Problem:** Race conditions during initialization
+
+**Fix:** Use `blockConcurrencyWhile` for atomic initialization
+
+```typescript
+await this.ctx.blockConcurrencyWhile(async () => {
+  if (!this.initialized) {
+    await this.startAndWaitForPorts();
+    this.initialized = true;
+  }
+});
+```
+
+### ⚠️ Lifecycle Hooks Block Requests
+
+**Problem:** Container unresponsive during `onStart()`
+
+**Cause:** Hooks run in `blockConcurrencyWhile` - no concurrent requests
+
+**Fix:** Keep hooks fast, avoid long operations
+
+### ⚠️ Don't Override alarm() When Using schedule()
+
+**Problem:** Scheduled tasks don't execute
+
+**Cause:** `schedule()` uses `alarm()` internally
+
+**Fix:** Implement `alarm()` to handle scheduled tasks
+
+## Common Errors
+
+### "Container start timeout"
+
+**Cause:** Container took >8s (`start()`) or >20s (`startAndWaitForPorts()`)
+
+**Solutions:**
+- Optimize image (smaller base, fewer layers)
+- Check `entrypoint` correct
+- Verify app listens on correct ports
+- Increase timeout if needed
+
+### "Port not available"
+
+**Cause:** Calling `fetch()` before port ready
+
+**Solution:** Use `startAndWaitForPorts()`
+
+### "Container memory exceeded"
+
+**Cause:** Using more memory than instance type allows
+
+**Solutions:**
+- Use larger instance type (standard-2, standard-3, standard-4)
+- Optimize app memory usage
+- Use custom instance type
+
+```jsonc
+"instance_type_custom": {
+  "vcpu": 2,
+  "memory_mib": 8192
+}
+```
+
+### "Max instances reached"
+
+**Cause:** All `max_instances` slots in use
+
+**Solutions:**
+- Increase `max_instances`
+- Implement proper `sleepAfter`
+- Use `getRandom()` for distribution
+- Check for instance leaks
+
+### "No container instance available"
+
+**Cause:** Account capacity limits reached
+
+**Solutions:**
+- Check account limits
+- Review instance types across containers
+- Contact Cloudflare support
+
+## Limits
+
+| Resource | Limit | Notes |
+|----------|-------|-------|
+| Cold start | 2-3s | Image pre-fetched globally |
+| Graceful shutdown | 15 min | SIGTERM → SIGKILL |
+| `start()` timeout | 8s | Process start |
+| `startAndWaitForPorts()` timeout | 20s | Port ready |
+| Max vCPU per container | 4 | standard-4 or custom |
+| Max memory per container | 12 GiB | standard-4 or custom |
+| Max disk per container | 20 GB | Ephemeral, resets |
+| Account total memory | 400 GiB | All containers |
+| Account total vCPU | 100 | All containers |
+| Account total disk | 2 TB | All containers |
+| Image storage | 50 GB | Per account |
+| Disk persistence | None | Use DO storage |
+
+## Best Practices
+
+1. **Use `startAndWaitForPorts()` by default** - Prevents port errors
+2. **Set appropriate `sleepAfter`** - Balance resources vs cold starts
+3. **Use `fetch()` for WebSocket** - Not `containerFetch()`
+4. **Design for restarts** - Ephemeral disk, implement graceful shutdown
+5. **Monitor resources** - Stay within account limits
+6. **Keep hooks fast** - Run in `blockConcurrencyWhile`
+7. **Renew activity for long ops** - Touch storage to prevent timeout
+
+## Beta Caveats
+
+⚠️ Containers in **beta**:
+
+- **API may change** without notice
+- **No SLA** guarantees
+- **Limited regions** initially
+- **No autoscaling** - manual via `getRandom()`
+- **Rolling deploys** only (not instant like Workers)
+
+Plan for API changes, test thoroughly before production.