@mohanscodex/spectra-code 0.4.8 → 0.5.0

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

package/skills/cloudflare-deploy/references/cron-triggers/configuration.md

@@ -0,0 +1,180 @@
+# Cron Triggers Configuration
+
+## wrangler.jsonc
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "my-cron-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01", // Use current date for new projects
+  
+  "triggers": {
+    "crons": [
+      "*/5 * * * *",     // Every 5 minutes
+      "0 */2 * * *",     // Every 2 hours
+      "0 9 * * MON-FRI", // Weekdays at 9am UTC
+      "0 2 1 * *"        // Monthly on 1st at 2am UTC
+    ]
+  }
+}
+```
+
+## Green Compute (Beta)
+
+Schedule crons during low-carbon periods for carbon-aware execution:
+
+```jsonc
+{
+  "name": "eco-cron-worker",
+  "triggers": {
+    "crons": ["0 2 * * *"]
+  },
+  "placement": {
+    "mode": "smart"  // Runs during low-carbon periods
+  }
+}
+```
+
+**Modes:**
+- `"smart"` - Carbon-aware scheduling (may delay up to 24h for optimal window)
+- Default (no placement config) - Standard scheduling (no delay)
+
+**How it works:**
+- Cloudflare delays execution until grid carbon intensity is lower
+- Maximum delay: 24 hours from scheduled time
+- Ideal for batch jobs with flexible timing requirements
+
+**Use cases:** 
+- Nightly data processing and ETL pipelines
+- Weekly/monthly report generation
+- Database backups and maintenance
+- Analytics aggregation
+- ML model training
+
+**Not suitable for:** 
+- Time-sensitive operations (SLA requirements)
+- User-facing features requiring immediate execution
+- Real-time monitoring and alerting
+- Compliance tasks with strict time windows
+
+## Environment-Specific Schedules
+
+```jsonc
+{
+  "name": "my-cron-worker",
+  "triggers": {
+    "crons": ["0 */6 * * *"]  // Prod: every 6 hours
+  },
+  "env": {
+    "staging": {
+      "triggers": {
+        "crons": ["*/15 * * * *"]  // Staging: every 15min
+      }
+    },
+    "dev": {
+      "triggers": {
+        "crons": ["*/5 * * * *"]  // Dev: every 5min
+      }
+    }
+  }
+}
+```
+
+## Schedule Format
+
+**Structure:** `minute hour day-of-month month day-of-week`
+
+**Special chars:** `*` (any), `,` (list), `-` (range), `/` (step), `L` (last), `W` (weekday), `#` (nth)
+
+## Managing Triggers
+
+**Remove all:** `"triggers": { "crons": [] }`  
+**Preserve existing:** Omit `"triggers"` field entirely
+
+## Deployment
+
+```bash
+# Deploy with config crons
+npx wrangler deploy
+
+# Deploy specific environment
+npx wrangler deploy --env production
+
+# View deployments
+npx wrangler deployments list
+```
+
+**⚠️ Changes take up to 15 minutes to propagate globally**
+
+## API Management
+
+**Get triggers:**
+```bash
+curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/schedules" \
+  -H "Authorization: Bearer {api_token}"
+```
+
+**Update triggers:**
+```bash
+curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/schedules" \
+  -H "Authorization: Bearer {api_token}" \
+  -H "Content-Type: application/json" \
+  -d '{"crons": ["*/5 * * * *", "0 2 * * *"]}'
+```
+
+**Delete all:**
+```bash
+curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/schedules" \
+  -H "Authorization: Bearer {api_token}" \
+  -H "Content-Type: application/json" \
+  -d '{"crons": []}'
+```
+
+## Combining Multiple Workers
+
+For complex schedules, use multiple workers:
+
+```jsonc
+// worker-frequent.jsonc
+{
+  "name": "data-sync-frequent",
+  "triggers": { "crons": ["*/5 * * * *"] }
+}
+
+// worker-daily.jsonc
+{
+  "name": "reports-daily",
+  "triggers": { "crons": ["0 2 * * *"] },
+  "placement": { "mode": "smart" }
+}
+
+// worker-weekly.jsonc
+{
+  "name": "cleanup-weekly",
+  "triggers": { "crons": ["0 3 * * SUN"] }
+}
+```
+
+**Benefits:**
+- Separate CPU limits per worker
+- Independent error isolation
+- Different Green Compute policies
+- Easier to maintain and debug
+
+## Validation
+
+**Test cron syntax:**
+- [crontab.guru](https://crontab.guru/) - Interactive validator
+- Wrangler validates on deploy but won't catch logic errors
+
+**Common mistakes:**
+- `0 0 * * *` runs daily at midnight UTC, not your local timezone
+- `*/60 * * * *` is invalid (use `0 * * * *` for hourly)
+- `0 2 31 * *` only runs on months with 31 days
+
+## See Also
+
+- [README.md](./README.md) - Overview, quick start
+- [api.md](./api.md) - Handler implementation
+- [patterns.md](./patterns.md) - Multi-cron routing examples