@mohanscodex/spectra-code 0.4.9 → 0.5.0

package/skills/cloudflare-deploy/references/do-storage/testing.md

@@ -0,0 +1,183 @@
+# DO Storage Testing
+
+Testing Durable Objects with storage using `vitest-pool-workers`.
+
+## Setup
+
+**vitest.config.ts:**
+```typescript
+import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
+
+export default defineWorkersConfig({
+  test: {
+    poolOptions: {
+      workers: { wrangler: { configPath: "./wrangler.toml" } }
+    }
+  }
+});
+```
+
+**package.json:** Add `@cloudflare/vitest-pool-workers` and `vitest` to devDependencies
+
+## Basic Testing
+
+```typescript
+import { env, runInDurableObject } from "cloudflare:test";
+import { describe, it, expect } from "vitest";
+
+describe("Counter DO", () => {
+  it("increments counter", async () => {
+    const id = env.COUNTER.idFromName("test");
+    const result = await runInDurableObject(env.COUNTER, id, async (instance, state) => {
+      const val1 = await instance.increment();
+      const val2 = await instance.increment();
+      return { val1, val2 };
+    });
+    expect(result.val1).toBe(1);
+    expect(result.val2).toBe(2);
+  });
+});
+```
+
+## Testing SQL Storage
+
+```typescript
+it("creates and queries users", async () => {
+  const id = env.USER_MANAGER.idFromName("test");
+  await runInDurableObject(env.USER_MANAGER, id, async (instance, state) => {
+    await instance.createUser("alice@example.com", "Alice");
+    const user = await instance.getUser("alice@example.com");
+    expect(user).toEqual({ email: "alice@example.com", name: "Alice" });
+  });
+});
+
+it("handles schema migrations", async () => {
+  const id = env.USER_MANAGER.idFromName("migration-test");
+  await runInDurableObject(env.USER_MANAGER, id, async (instance, state) => {
+    const version = state.storage.sql.exec(
+      "SELECT value FROM _meta WHERE key = 'schema_version'"
+    ).one()?.value;
+    expect(version).toBe("1");
+  });
+});
+```
+
+## Testing Alarms
+
+```typescript
+import { runDurableObjectAlarm } from "cloudflare:test";
+
+it("processes batch on alarm", async () => {
+  const id = env.BATCH_PROCESSOR.idFromName("test");
+  
+  // Add items
+  await runInDurableObject(env.BATCH_PROCESSOR, id, async (instance) => {
+    await instance.addItem("item1");
+    await instance.addItem("item2");
+  });
+  
+  // Trigger alarm
+  await runDurableObjectAlarm(env.BATCH_PROCESSOR, id);
+  
+  // Verify processed
+  await runInDurableObject(env.BATCH_PROCESSOR, id, async (instance, state) => {
+    const count = state.storage.sql.exec(
+      "SELECT COUNT(*) as count FROM processed_items"
+    ).one().count;
+    expect(count).toBe(2);
+  });
+});
+```
+
+## Testing Concurrency
+
+```typescript
+it("handles concurrent increments safely", async () => {
+  const id = env.COUNTER.idFromName("concurrent-test");
+  
+  // Parallel increments
+  const results = await Promise.all([
+    runInDurableObject(env.COUNTER, id, (i) => i.increment()),
+    runInDurableObject(env.COUNTER, id, (i) => i.increment()),
+    runInDurableObject(env.COUNTER, id, (i) => i.increment())
+  ]);
+  
+  // All should get unique values
+  expect(new Set(results).size).toBe(3);
+  expect(Math.max(...results)).toBe(3);
+});
+```
+
+## Test Isolation
+
+```typescript
+// Per-test unique IDs
+let testId: string;
+beforeEach(() => { testId = crypto.randomUUID(); });
+
+it("isolated test", async () => {
+  const id = env.MY_DO.idFromName(testId);
+  // Uses unique DO instance
+});
+
+// Cleanup pattern
+it("with cleanup", async () => {
+  const id = env.MY_DO.idFromName("cleanup-test");
+  try {
+    await runInDurableObject(env.MY_DO, id, async (instance) => {});
+  } finally {
+    await runInDurableObject(env.MY_DO, id, async (instance, state) => {
+      await state.storage.deleteAll();
+    });
+  }
+});
+```
+
+## Testing PITR
+
+```typescript
+it("restores from bookmark", async () => {
+  const id = env.MY_DO.idFromName("pitr-test");
+  
+  // Create checkpoint
+  const bookmark = await runInDurableObject(env.MY_DO, id, async (instance, state) => {
+    await state.storage.put("value", 1);
+    return await state.storage.getCurrentBookmark();
+  });
+  
+  // Modify and restore
+  await runInDurableObject(env.MY_DO, id, async (instance, state) => {
+    await state.storage.put("value", 2);
+    await state.storage.onNextSessionRestoreBookmark(bookmark);
+    state.abort();
+  });
+  
+  // Verify restored
+  await runInDurableObject(env.MY_DO, id, async (instance, state) => {
+    const value = await state.storage.get("value");
+    expect(value).toBe(1);
+  });
+});
+```
+
+## Testing Transactions
+
+```typescript
+it("rolls back on error", async () => {
+  const id = env.BANK.idFromName("transaction-test");
+  
+  await runInDurableObject(env.BANK, id, async (instance, state) => {
+    await state.storage.put("balance", 100);
+    
+    await expect(
+      state.storage.transaction(async () => {
+        await state.storage.put("balance", 50);
+        throw new Error("Cancel");
+      })
+    ).rejects.toThrow("Cancel");
+    
+    const balance = await state.storage.get("balance");
+    expect(balance).toBe(100); // Rolled back
+  });
+});
+```

package/skills/cloudflare-deploy/references/durable-objects/README.md

@@ -0,0 +1,185 @@
+# Cloudflare Durable Objects
+
+Expert guidance for building stateful applications with Cloudflare Durable Objects.
+
+## Reading Order
+
+1. **First time?** Read this overview + Quick Start
+2. **Setting up?** See [Configuration](./configuration.md)
+3. **Building features?** Use decision trees below → [Patterns](./patterns.md)
+4. **Debugging issues?** Check [Gotchas](./gotchas.md)
+5. **Deep dive?** [API](./api.md) and [DO Storage](../do-storage/README.md)
+
+## Overview
+
+Durable Objects combine compute with storage in globally-unique, strongly-consistent packages:
+- **Globally unique instances**: Each DO has unique ID for multi-client coordination
+- **Co-located storage**: Fast, strongly-consistent storage with compute
+- **Automatic placement**: Objects spawn near first request location
+- **Stateful serverless**: In-memory state + persistent storage
+- **Single-threaded**: Serial request processing (no race conditions)
+
+## Rules of Durable Objects
+
+Critical rules preventing most production issues:
+
+1. **One alarm per DO** - Schedule multiple events via queue pattern
+2. **~1K req/s per DO max** - Shard for higher throughput
+3. **Constructor runs every wake** - Keep initialization light; use lazy loading
+4. **Hibernation clears memory** - In-memory state lost; persist critical data
+5. **Use `ctx.waitUntil()` for cleanup** - Ensures completion after response sent
+6. **No setTimeout for persistence** - Use `setAlarm()` for reliable scheduling
+
+## Core Concepts
+
+### Class Structure
+All DOs extend `DurableObject` base class with constructor receiving `DurableObjectState` (storage, WebSockets, alarms) and `Env` (bindings).
+
+### Lifecycle States
+
+```
+[Not Created] → [Active] ⇄ [Hibernated] → [Evicted]
+                   ↓
+              [Destroyed]
+```
+
+- **Not Created**: DO ID exists but instance never spawned
+- **Active**: Processing requests, in-memory state valid, billed per GB-hour
+- **Hibernated**: WebSocket connections open but zero compute, zero cost
+- **Evicted**: Removed from memory; next request triggers cold start
+- **Destroyed**: Data deleted via migration or manual deletion
+
+### Accessing from Workers
+Workers use bindings to get stubs, then call RPC methods directly (recommended) or use fetch handler (legacy).
+
+**RPC vs fetch() decision:**
+```
+├─ New project + compat ≥2024-04-03 → RPC (type-safe, simpler)
+├─ Need HTTP semantics (headers, status) → fetch()
+├─ Proxying requests to DO → fetch()
+└─ Legacy compatibility → fetch()
+```
+
+See [Patterns: RPC vs fetch()](./patterns.md) for examples.
+
+### ID Generation
+- `idFromName()`: Deterministic, named coordination (rate limiting, locks)
+- `newUniqueId()`: Random IDs for sharding high-throughput workloads
+- `idFromString()`: Derive from existing IDs
+- Jurisdiction option: Data locality compliance
+
+### Storage Options
+
+**Which storage API?**
+```
+├─ Structured data, relations, transactions → SQLite (recommended)
+├─ Simple KV on SQLite DO → ctx.storage.kv (sync KV)
+└─ Legacy KV-only DO → ctx.storage (async KV)
+```
+
+- **SQLite** (recommended): Structured data, transactions, 10GB/DO
+- **Synchronous KV API**: Simple key-value on SQLite objects
+- **Asynchronous KV API**: Legacy/advanced use cases
+
+See [DO Storage](../do-storage/README.md) for deep dive.
+
+### Special Features
+- **Alarms**: Schedule future execution per-DO (1 per DO - use queue pattern for multiple)
+- **WebSocket Hibernation**: Zero-cost idle connections (memory cleared on hibernation)
+- **Point-in-Time Recovery**: Restore to any point in 30 days (SQLite only)
+
+## Quick Start
+
+```typescript
+import { DurableObject } from "cloudflare:workers";
+
+export class Counter extends DurableObject<Env> {
+  async increment(): Promise<number> {
+    const result = this.ctx.storage.sql.exec(
+      `INSERT INTO counters (id, value) VALUES (1, 1)
+       ON CONFLICT(id) DO UPDATE SET value = value + 1
+       RETURNING value`
+    ).one();
+    return result.value;
+  }
+}
+
+// Worker access
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const id = env.COUNTER.idFromName("global");
+    const stub = env.COUNTER.get(id);
+    const count = await stub.increment();
+    return new Response(`Count: ${count}`);
+  }
+};
+```
+
+## Decision Trees
+
+### What do you need?
+
+```
+├─ Coordinate requests (rate limit, lock, session)
+│   → idFromName(identifier) → [Patterns: Rate Limiting/Locks](./patterns.md)
+│
+├─ High throughput (>1K req/s)
+│   → Sharding with newUniqueId() or hash → [Patterns: Sharding](./patterns.md)
+│
+├─ Real-time updates (WebSocket, chat, collab)
+│   → WebSocket hibernation + room pattern → [Patterns: Real-time](./patterns.md)
+│
+├─ Background work (cleanup, notifications, scheduled tasks)
+│   → Alarms + queue pattern (1 alarm/DO) → [Patterns: Multiple Events](./patterns.md)
+│
+└─ User sessions with expiration
+    → Session pattern + alarm cleanup → [Patterns: Session Management](./patterns.md)
+```
+
+### Which access pattern?
+
+```
+├─ New project + typed methods → RPC (compat ≥2024-04-03)
+├─ Need HTTP semantics → fetch()
+├─ Proxying to DO → fetch()
+└─ Legacy compat → fetch()
+```
+
+See [Patterns: RPC vs fetch()](./patterns.md) for examples.
+
+### Which storage?
+
+```
+├─ Structured data, SQL queries, transactions → SQLite (recommended)
+├─ Simple KV on SQLite DO → ctx.storage.kv (sync API)
+└─ Legacy KV-only DO → ctx.storage (async API)
+```
+
+See [DO Storage](../do-storage/README.md) for complete guide.
+
+## Essential Commands
+
+```bash
+npx wrangler dev              # Local dev with DOs
+npx wrangler dev --remote     # Test against prod DOs
+npx wrangler deploy           # Deploy + auto-apply migrations
+```
+
+## Resources
+
+**Docs**: https://developers.cloudflare.com/durable-objects/  
+**API Reference**: https://developers.cloudflare.com/durable-objects/api/  
+**Examples**: https://developers.cloudflare.com/durable-objects/examples/
+
+## In This Reference
+
+- **[Configuration](./configuration.md)** - wrangler.jsonc setup, migrations, bindings, environments
+- **[API](./api.md)** - Class structure, ctx methods, alarms, WebSocket hibernation
+- **[Patterns](./patterns.md)** - Sharding, rate limiting, locks, real-time, sessions
+- **[Gotchas](./gotchas.md)** - Limits, hibernation caveats, common errors
+
+## See Also
+
+- **[DO Storage](../do-storage/README.md)** - SQLite, KV, transactions (detailed storage guide)
+- **[Workers](../workers/README.md)** - Core Workers runtime features
+- **[WebSockets](../websockets/README.md)** - WebSocket APIs and patterns

package/skills/cloudflare-deploy/references/durable-objects/api.md

@@ -0,0 +1,187 @@
+# Durable Objects API
+
+## Class Structure
+
+```typescript
+import { DurableObject } from "cloudflare:workers";
+
+export class MyDO extends DurableObject<Env> {
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    // Runs on EVERY wake - keep light!
+  }
+  
+  // RPC methods (called directly from worker)
+  async myMethod(arg: string): Promise<string> { return arg; }
+  
+  // fetch handler (legacy/HTTP semantics)
+  async fetch(req: Request): Promise<Response> { /* ... */ }
+  
+  // Lifecycle handlers
+  async alarm() { /* alarm fired */ }
+  async webSocketMessage(ws: WebSocket, msg: string | ArrayBuffer) { /* ... */ }
+  async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) { /* ... */ }
+  async webSocketError(ws: WebSocket, error: unknown) { /* ... */ }
+}
+```
+
+## DurableObjectState Context Methods
+
+### Concurrency Control
+
+```typescript
+// Complete work after response sent (e.g., cleanup, logging)
+this.ctx.waitUntil(promise: Promise<any>): void
+
+// Critical section - blocks all other requests until complete
+await this.ctx.blockConcurrencyWhile(async () => {
+  // No other requests processed during this block
+  // Use for initialization or critical operations
+})
+```
+
+**When to use:**
+- `waitUntil()`: Background cleanup, logging, non-critical work after response
+- `blockConcurrencyWhile()`: First-time init, schema migration, critical state setup
+
+### Lifecycle
+
+```typescript
+this.ctx.id              // DurableObjectId of this instance
+this.ctx.abort()         // Force eviction (use after PITR restore to reload state)
+```
+
+### Storage Access
+
+```typescript
+this.ctx.storage.sql     // SQLite API (recommended)
+this.ctx.storage.kv      // Sync KV API (SQLite DOs only)
+this.ctx.storage         // Async KV API (legacy/KV-only DOs)
+```
+
+See **[DO Storage](../do-storage/README.md)** for complete storage API reference.
+
+### WebSocket Management
+
+```typescript
+this.ctx.acceptWebSocket(ws: WebSocket, tags?: string[])  // Enable hibernation
+this.ctx.getWebSockets(tag?: string): WebSocket[]         // Get by tag or all
+this.ctx.getTags(ws: WebSocket): string[]                 // Get tags for connection
+```
+
+### Alarms
+
+```typescript
+await this.ctx.storage.setAlarm(timestamp: number | Date)  // Schedule (overwrites existing)
+await this.ctx.storage.getAlarm(): number | null           // Get next alarm time
+await this.ctx.storage.deleteAlarm(): void                 // Cancel alarm
+```
+
+**Limit:** 1 alarm per DO. Use queue pattern for multiple events (see [Patterns](./patterns.md)).
+
+## Storage APIs
+
+For detailed storage documentation including SQLite queries, KV operations, transactions, and Point-in-Time Recovery, see **[DO Storage](../do-storage/README.md)**.
+
+Quick reference:
+
+```typescript
+// SQLite (recommended)
+this.ctx.storage.sql.exec("SELECT * FROM users WHERE id = ?", userId).one()
+
+// Sync KV (SQLite DOs only)
+this.ctx.storage.kv.get("key")
+
+// Async KV (legacy)
+await this.ctx.storage.get("key")
+```
+
+## Alarms
+
+Schedule future work that survives eviction:
+
+```typescript
+// Set alarm (overwrites any existing alarm)
+await this.ctx.storage.setAlarm(Date.now() + 3600000)  // 1 hour from now
+await this.ctx.storage.setAlarm(new Date("2026-02-01"))  // Absolute time
+
+// Check next alarm
+const nextRun = await this.ctx.storage.getAlarm()  // null if none
+
+// Cancel alarm
+await this.ctx.storage.deleteAlarm()
+
+// Handler called when alarm fires
+async alarm() {
+  // Runs once alarm triggers
+  // DO wakes from hibernation if needed
+  // Use for cleanup, notifications, scheduled tasks
+}
+```
+
+**Limitations:**
+- 1 alarm per DO maximum
+- Overwrites previous alarm when set
+- Use queue pattern for multiple scheduled events (see [Patterns](./patterns.md))
+
+**Reliability:**
+- Alarms survive DO eviction/restart
+- Cloudflare retries failed alarms automatically
+- Not guaranteed exactly-once (handle idempotently)
+
+## WebSocket Hibernation
+
+Hibernation allows DOs with open WebSocket connections to consume zero compute/memory until message arrives.
+
+```typescript
+async fetch(req: Request): Promise<Response> {
+  const [client, server] = Object.values(new WebSocketPair());
+  this.ctx.acceptWebSocket(server, ["room:123"]);  // Tags for filtering
+  server.serializeAttachment({ userId: "abc" });    // Persisted metadata
+  return new Response(null, { status: 101, webSocket: client });
+}
+
+// Called when message arrives (DO wakes from hibernation)
+async webSocketMessage(ws: WebSocket, msg: string | ArrayBuffer) {
+  const data = ws.deserializeAttachment();          // Retrieve metadata
+  for (const c of this.ctx.getWebSockets("room:123")) c.send(msg);
+}
+
+// Called on close (optional handler)
+async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) {
+  // Cleanup logic, remove from lists, etc.
+}
+
+// Called on error (optional handler)
+async webSocketError(ws: WebSocket, error: unknown) {
+  console.error("WebSocket error:", error);
+  // Handle error, close connection, etc.
+}
+```
+
+**Key concepts:**
+- **Auto-hibernation:** DO hibernates when no active requests/alarms
+- **Zero cost:** Hibernated DOs incur no charges while preserving connections
+- **Memory cleared:** All in-memory state lost on hibernation
+- **Attachment persistence:** Use `serializeAttachment()` for per-connection metadata that survives hibernation
+- **Tags for filtering:** Group connections by room/channel/user for targeted broadcasts
+
+**Handler lifecycle:**
+- `webSocketMessage`: DO wakes, processes message, may hibernate after
+- `webSocketClose`: Called when client closes (optional - implement for cleanup)
+- `webSocketError`: Called on connection error (optional - implement for error handling)
+
+**Metadata persistence:**
+```typescript
+// Store connection metadata (survives hibernation)
+ws.serializeAttachment({ userId: "abc", room: "lobby" })
+
+// Retrieve after hibernation
+const { userId, room } = ws.deserializeAttachment()
+```
+
+## See Also
+
+- **[DO Storage](../do-storage/README.md)** - Complete storage API reference
+- **[Patterns](./patterns.md)** - Real-world usage patterns
+- **[Gotchas](./gotchas.md)** - Hibernation caveats and limits