memory-journal-mcp 7.7.1 → 8.0.0

package/skills/cloudflare/references/containers/README.md

@@ -0,0 +1,87 @@
+# Cloudflare Containers Skill Reference
+
+**APPLIES TO: Cloudflare Containers ONLY - NOT general Cloudflare Workers**
+
+Use when working with Cloudflare Containers: deploying containerized apps on Workers platform, configuring container-enabled Durable Objects, managing container lifecycle, or implementing stateful/stateless container patterns.
+
+## Beta Status
+
+⚠️ Containers is currently in **beta**. API may change without notice. No SLA guarantees. Custom instance types added Jan 2026.
+
+## Core Concepts
+
+**Container as Durable Object:** Each container is a Durable Object with persistent identity. Accessed via `getByName(id)` or `getRandom()`.
+
+**Image deployment:** Images pre-fetched globally. Deployments use rolling strategy (not instant like Workers).
+
+**Lifecycle:** cold start (2-3s) → running → `sleepAfter` timeout → stopped. No autoscaling - manual load balancing via `getRandom()`.
+
+**Persistent identity, ephemeral disk:** Container ID persists, but disk resets on stop. Use Durable Object storage for persistence.
+
+## Quick Start
+
+```typescript
+import { Container } from '@cloudflare/containers'
+
+export class MyContainer extends Container {
+  defaultPort = 8080
+  sleepAfter = '30m'
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const container = env.MY_CONTAINER.getByName('instance-1')
+    await container.startAndWaitForPorts()
+    return container.fetch(request)
+  },
+}
+```
+
+## Reading Order
+
+| Task                        | Files                                |
+| --------------------------- | ------------------------------------ |
+| Setup new container project | README → configuration.md            |
+| Implement container logic   | README → api.md → patterns.md        |
+| Choose routing pattern      | patterns.md (routing section)        |
+| Debug issues                | gotchas.md                           |
+| Production hardening        | gotchas.md → patterns.md (lifecycle) |
+
+## Routing Decision Tree
+
+**How should requests reach containers?**
+
+- **Same user/session → same container:** Use `getByName(sessionId)` for session affinity
+- **Stateless, spread load:** Use `getRandom()` for load balancing
+- **Job per container:** Use `getByName(jobId)` + explicit lifecycle management
+- **Single global instance:** Use `getByName("singleton")`
+
+## When to Use Containers vs Workers
+
+**Use Containers when:**
+
+- Need stateful, long-lived processes (sessions, WebSockets, games)
+- Running existing containerized apps (Node.js, Python, custom binaries)
+- Need filesystem access or specific system dependencies
+- Per-user/session isolation with dedicated compute
+
+**Use Workers when:**
+
+- Stateless HTTP handlers
+- Sub-millisecond cold starts required
+- Auto-scaling to zero critical
+- Simple request/response patterns
+
+## In This Reference
+
+- **[configuration.md](configuration.md)** - Wrangler config, instance types, Container class properties, environment variables, account limits
+- **[api.md](api.md)** - Container class API, startup methods, communication (HTTP/TCP/WebSocket), routing helpers, lifecycle hooks, scheduling, state inspection
+- **[patterns.md](patterns.md)** - Routing patterns (session affinity, load balancing, singleton), WebSocket forwarding, graceful shutdown, Workflow/Queue integration
+- **[gotchas.md](gotchas.md)** - Critical gotchas (WebSocket, startup methods), common errors with solutions, specific limits, beta caveats
+
+## See Also
+
+- [Durable Objects](../durable-objects/) - Containers extend Durable Objects
+- [Workflows](../workflows/) - Orchestrate container operations
+- [Queues](../queues/) - Trigger containers from queue messages
+- [Cloudflare Docs](https://developers.cloudflare.com/containers/)

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

@@ -0,0 +1,197 @@
+## 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/references/containers/configuration.md

@@ -0,0 +1,191 @@
+## 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/references/containers/gotchas.md

@@ -0,0 +1,182 @@
+## 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.