@bcelep/capint 0.4.2 → 0.7.0

package/skills/cloudflare/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.

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

@@ -0,0 +1,202 @@
+## Routing Patterns
+
+### Session Affinity (Stateful)
+
+```typescript
+export class SessionBackend extends Container {
+  defaultPort = 3000;
+  sleepAfter = "30m";
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const sessionId = request.headers.get("X-Session-ID") || crypto.randomUUID();
+    const container = env.SESSION_BACKEND.getByName(sessionId);
+    await container.startAndWaitForPorts();
+    return container.fetch(request);
+  }
+};
+```
+
+**Use:** User sessions, WebSocket, stateful games, per-user caching.
+
+### Load Balancing (Stateless)
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    const container = env.STATELESS_API.getRandom();
+    await container.startAndWaitForPorts();
+    return container.fetch(request);
+  }
+};
+```
+
+**Use:** Stateless HTTP APIs, CPU-intensive work, read-only queries.
+
+### Singleton Pattern
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    const container = env.GLOBAL_SERVICE.getByName("singleton");
+    await container.startAndWaitForPorts();
+    return container.fetch(request);
+  }
+};
+```
+
+**Use:** Global cache, centralized coordinator, single source of truth.
+
+## WebSocket Forwarding
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    if (request.headers.get("Upgrade") === "websocket") {
+      const sessionId = request.headers.get("X-Session-ID") || crypto.randomUUID();
+      const container = env.WS_BACKEND.getByName(sessionId);
+      await container.startAndWaitForPorts();
+      
+      // ⚠️ MUST use fetch(), not containerFetch()
+      return container.fetch(request);
+    }
+    return new Response("Not a WebSocket request", { status: 400 });
+  }
+};
+```
+
+**⚠️ Critical:** Always use `fetch()` for WebSocket.
+
+## Graceful Shutdown
+
+```typescript
+export class GracefulContainer extends Container {
+  private connections = new Set<WebSocket>();
+
+  onStop() {
+    // SIGTERM received, 15 minutes until SIGKILL
+    for (const ws of this.connections) {
+      ws.close(1001, "Server shutting down");
+    }
+    this.ctx.storage.put("shutdown-time", Date.now());
+  }
+
+  onActivityExpired(): boolean {
+    return this.connections.size > 0;  // Keep alive if connections
+  }
+}
+```
+
+## Concurrent Request Handling
+
+```typescript
+export class SafeContainer extends Container {
+  private initialized = false;
+
+  async fetch(request: Request) {
+    await this.ctx.blockConcurrencyWhile(async () => {
+      if (!this.initialized) {
+        await this.startAndWaitForPorts();
+        this.initialized = true;
+      }
+    });
+    return super.fetch(request);
+  }
+}
+```
+
+**Use:** One-time initialization, preventing concurrent startup.
+
+## Activity Timeout Renewal
+
+```typescript
+export class LongRunningContainer extends Container {
+  sleepAfter = "5m";
+
+  async processLongJob(data: unknown) {
+    const interval = setInterval(() => {
+      this.ctx.storage.put("keepalive", Date.now());
+    }, 60000);
+
+    try {
+      await this.doLongWork(data);
+    } finally {
+      clearInterval(interval);
+    }
+  }
+}
+```
+
+**Use:** Long operations exceeding `sleepAfter`.
+
+## Multiple Port Routing
+
+```typescript
+export class MultiPortContainer extends Container {
+  requiredPorts = [8080, 8081, 9090];
+
+  async fetch(request: Request) {
+    const path = new URL(request.url).pathname;
+    if (path.startsWith("/grpc")) this.switchPort(8081);
+    else if (path.startsWith("/metrics")) this.switchPort(9090);
+    return super.fetch(request);
+  }
+}
+```
+
+**Use:** Multi-protocol services (HTTP + gRPC), separate metrics endpoints.
+
+## Workflow Integration
+
+```typescript
+import { WorkflowEntrypoint } from "cloudflare:workers";
+
+export class ProcessingWorkflow extends WorkflowEntrypoint {
+  async run(event, step) {
+    const container = this.env.PROCESSOR.getByName(event.payload.jobId);
+    
+    await step.do("start", async () => {
+      await container.startAndWaitForPorts();
+    });
+    
+    const result = await step.do("process", async () => {
+      return container.fetch("/process", {
+        method: "POST",
+        body: JSON.stringify(event.payload.data)
+      }).then(r => r.json());
+    });
+    
+    return result;
+  }
+}
+```
+
+**Use:** Orchestrating multi-step container operations, durable execution.
+
+## Queue Consumer Integration
+
+```typescript
+export default {
+  async queue(batch, env) {
+    for (const msg of batch.messages) {
+      try {
+        const container = env.PROCESSOR.getByName(msg.body.jobId);
+        await container.startAndWaitForPorts();
+        
+        const response = await container.fetch("/process", {
+          method: "POST",
+          body: JSON.stringify(msg.body)
+        });
+        
+        response.ok ? msg.ack() : msg.retry();
+      } catch (err) {
+        console.error("Queue processing error:", err);
+        msg.retry();
+      }
+    }
+  }
+};
+```
+
+**Use:** Asynchronous job processing, batch operations, event-driven execution.

package/skills/cloudflare/references/cron-triggers/README.md

@@ -0,0 +1,99 @@
+# Cloudflare Cron Triggers
+
+Schedule Workers execution using cron expressions. Runs on Cloudflare's global network during underutilized periods.
+
+## Key Features
+
+- **UTC-only execution** - All schedules run on UTC time
+- **5-field cron syntax** - Quartz scheduler extensions (L, W, #)
+- **Global propagation** - 15min deployment delay
+- **At-least-once delivery** - Rare duplicate executions possible
+- **Workflow integration** - Trigger long-running multi-step tasks
+- **Green Compute** - Optional carbon-aware scheduling during low-carbon periods
+
+## Cron Syntax
+
+```
+ ┌─────────── minute (0-59)
+ │ ┌───────── hour (0-23)
+ │ │ ┌─────── day of month (1-31)
+ │ │ │ ┌───── month (1-12, JAN-DEC)
+ │ │ │ │ ┌─── day of week (1-7, SUN-SAT, 1=Sunday)
+ * * * * *
+```
+
+**Special chars:** `*` (any), `,` (list), `-` (range), `/` (step), `L` (last), `W` (weekday), `#` (nth)
+
+## Common Schedules
+
+```bash
+*/5 * * * *        # Every 5 minutes
+0 * * * *          # Hourly
+0 2 * * *          # Daily 2am UTC (off-peak)
+0 9 * * MON-FRI    # Weekdays 9am UTC
+0 0 1 * *          # Monthly 1st midnight UTC
+0 9 L * *          # Last day of month 9am UTC
+0 10 * * MON#2     # 2nd Monday 10am UTC
+*/10 9-17 * * MON-FRI  # Every 10min, 9am-5pm weekdays
+```
+
+## Quick Start
+
+**wrangler.jsonc:**
+```jsonc
+{
+  "name": "my-cron-worker",
+  "triggers": {
+    "crons": ["*/5 * * * *", "0 2 * * *"]
+  }
+}
+```
+
+**Handler:**
+```typescript
+export default {
+  async scheduled(
+    controller: ScheduledController,
+    env: Env,
+    ctx: ExecutionContext,
+  ): Promise<void> {
+    console.log("Cron:", controller.cron);
+    console.log("Time:", new Date(controller.scheduledTime));
+    
+    ctx.waitUntil(asyncTask(env)); // Non-blocking
+  },
+};
+```
+
+**Test locally:**
+```bash
+npx wrangler dev
+curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"
+```
+
+## Limits
+
+- **Free:** 3 triggers/worker, 10ms CPU
+- **Paid:** Unlimited triggers, 50ms CPU
+- **Propagation:** 15min global deployment
+- **Timezone:** UTC only
+
+## Reading Order
+
+**New to cron triggers?** Start here:
+1. This README - Overview and quick start
+2. [configuration.md](./configuration.md) - Set up your first cron trigger
+3. [api.md](./api.md) - Understand the handler API
+4. [patterns.md](./patterns.md) - Common use cases and examples
+
+**Troubleshooting?** Jump to [gotchas.md](./gotchas.md)
+
+## In This Reference
+- [configuration.md](./configuration.md) - wrangler config, env-specific schedules, Green Compute
+- [api.md](./api.md) - ScheduledController, noRetry(), waitUntil, testing patterns
+- [patterns.md](./patterns.md) - Use cases, monitoring, queue integration, Durable Objects
+- [gotchas.md](./gotchas.md) - Timezone issues, idempotency, security, testing
+
+## See Also
+- [workflows](../workflows/) - Alternative for long-running scheduled tasks
+- [workers](../workers/) - Worker runtime documentation

package/skills/cloudflare/references/cron-triggers/api.md

@@ -0,0 +1,196 @@
+# Cron Triggers API
+
+## Basic Handler
+
+```typescript
+export default {
+  async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext): Promise<void> {
+    console.log("Cron executed:", new Date(controller.scheduledTime));
+  },
+};
+```
+
+**JavaScript:** Same signature without types  
+**Python:** `class Default(WorkerEntrypoint): async def scheduled(self, controller, env, ctx)`
+
+## ScheduledController
+
+```typescript
+interface ScheduledController {
+  scheduledTime: number;  // Unix ms when scheduled to run
+  cron: string;           // Expression that triggered (e.g., "*/5 * * * *")
+  type: string;           // Always "scheduled"
+  noRetry(): void;        // Prevent automatic retry on failure
+}
+```
+
+**Prevent retry on failure:**
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    try {
+      await riskyOperation(env);
+    } catch (error) {
+      // Don't retry - failure is expected/acceptable
+      controller.noRetry();
+      console.error("Operation failed, not retrying:", error);
+    }
+  },
+};
+```
+
+**When to use noRetry():**
+- External API failures outside your control (avoid hammering failed services)
+- Rate limit errors (retry would fail again immediately)
+- Duplicate execution detected (idempotency check failed)
+- Non-critical operations where skip is acceptable (analytics, caching)
+- Validation errors that won't resolve on retry
+
+## Handler Parameters
+
+**`controller: ScheduledController`**
+- Access cron expression and scheduled time
+
+**`env: Env`**
+- All bindings: KV, R2, D1, secrets, service bindings
+
+**`ctx: ExecutionContext`**
+- `ctx.waitUntil(promise)` - Extend execution for async tasks (logging, cleanup, external APIs)
+- First `waitUntil` failure recorded in Cron Events
+
+## Multiple Schedules
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    switch (controller.cron) {
+      case "*/3 * * * *": ctx.waitUntil(updateRecentData(env)); break;
+      case "0 * * * *": ctx.waitUntil(processHourlyAggregation(env)); break;
+      case "0 2 * * *": ctx.waitUntil(performDailyMaintenance(env)); break;
+      default: console.warn(`Unhandled: ${controller.cron}`);
+    }
+  },
+};
+```
+
+## ctx.waitUntil Usage
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const data = await fetchCriticalData(); // Critical path
+    
+    // Non-blocking background tasks
+    ctx.waitUntil(Promise.all([
+      logToAnalytics(data),
+      cleanupOldRecords(env.DB),
+      notifyWebhook(env.WEBHOOK_URL, data),
+    ]));
+  },
+};
+```
+
+## Workflow Integration
+
+```typescript
+import { WorkflowEntrypoint } from "cloudflare:workers";
+
+export class DataProcessingWorkflow extends WorkflowEntrypoint {
+  async run(event, step) {
+    const data = await step.do("fetch-data", () => fetchLargeDataset());
+    const processed = await step.do("process-data", () => processDataset(data));
+    await step.do("store-results", () => storeResults(processed));
+  }
+}
+
+export default {
+  async scheduled(controller, env, ctx) {
+    const instance = await env.MY_WORKFLOW.create({
+      params: { scheduledTime: controller.scheduledTime, cron: controller.cron },
+    });
+    console.log(`Started workflow: ${instance.id}`);
+  },
+};
+```
+
+## Testing Handler
+
+**Local development (/__scheduled endpoint):**
+```bash
+# Start dev server
+npx wrangler dev
+
+# Trigger any cron
+curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"
+
+# Trigger specific cron with custom time
+curl "http://localhost:8787/__scheduled?cron=0+2+*+*+*&scheduledTime=1704067200000"
+```
+
+**Query parameters:**
+- `cron` - Required. URL-encoded cron expression (use `+` for spaces)
+- `scheduledTime` - Optional. Unix timestamp in milliseconds (defaults to current time)
+
+**Production security:** The `/__scheduled` endpoint is available in production and can be triggered by anyone. Block it or implement authentication - see [gotchas.md](./gotchas.md#security-concerns)
+
+**Unit testing (Vitest):**
+```typescript
+// test/scheduled.test.ts
+import { describe, it, expect } from "vitest";
+import { env } from "cloudflare:test";
+import worker from "../src/index";
+
+describe("Scheduled Handler", () => {
+  it("processes scheduled event", async () => {
+    const controller = { scheduledTime: Date.now(), cron: "*/5 * * * *", type: "scheduled" as const, noRetry: () => {} };
+    const ctx = { waitUntil: (p: Promise<any>) => p, passThroughOnException: () => {} };
+    await worker.scheduled(controller, env, ctx);
+    expect(await env.MY_KV.get("last_run")).toBeDefined();
+  });
+  
+  it("handles multiple crons", async () => {
+    const ctx = { waitUntil: () => {}, passThroughOnException: () => {} };
+    await worker.scheduled({ scheduledTime: Date.now(), cron: "*/5 * * * *", type: "scheduled", noRetry: () => {} }, env, ctx);
+    expect(await env.MY_KV.get("last_type")).toBe("frequent");
+  });
+});
+```
+
+## Error Handling
+
+**Automatic retries:**
+- Failed cron executions are retried automatically unless `noRetry()` is called
+- Retry happens after a delay (typically minutes)
+- Only first `waitUntil()` failure is recorded in Cron Events
+
+**Best practices:**
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    try {
+      await criticalOperation(env);
+    } catch (error) {
+      // Log error details
+      console.error("Cron failed:", {
+        cron: controller.cron,
+        scheduledTime: controller.scheduledTime,
+        error: error.message,
+        stack: error.stack,
+      });
+      
+      // Decide: retry or skip
+      if (error.message.includes("rate limit")) {
+        controller.noRetry(); // Skip retry for rate limits
+      }
+      // Otherwise allow automatic retry
+      throw error;
+    }
+  },
+};
+```
+
+## See Also
+
+- [README.md](./README.md) - Overview
+- [patterns.md](./patterns.md) - Use cases, examples
+- [gotchas.md](./gotchas.md) - Common errors, testing issues