pi-cloudflare 0.1.0

package/skills/durable-objects/references/rules.md

@@ -0,0 +1,295 @@
+# Durable Objects Rules & Best Practices
+
+## Design & Sharding
+
+### Model Around Coordination Atoms
+
+Create one DO per logical unit needing coordination: chat room, game session, document, user, tenant.
+
+```typescript
+// ✅ Good: One DO per chat room
+const stub = env.CHAT_ROOM.getByName(roomId);
+
+// ❌ Bad: Single global DO
+const stub = env.CHAT_ROOM.getByName("global"); // Bottleneck!
+```
+
+### Parent-Child Relationships
+
+For hierarchical data, create separate child DOs. Parent tracks references, children handle own state.
+
+```typescript
+// Parent: GameServer tracks match references
+// Children: GameMatch handles individual match state
+async createMatch(name: string): Promise<string> {
+  const matchId = crypto.randomUUID();
+  this.ctx.storage.sql.exec(
+    "INSERT INTO matches (id, name) VALUES (?, ?)",
+    matchId, name
+  );
+  const child = this.env.GAME_MATCH.getByName(matchId);
+  await child.init(matchId, name);
+  return matchId;
+}
+```
+
+### Location Hints
+
+Influence DO creation location for latency-sensitive apps:
+
+```typescript
+const id = env.GAME.idFromName(gameId, { locationHint: "wnam" });
+```
+
+Available hints: `wnam`, `enam`, `sam`, `weur`, `eeur`, `apac`, `oc`, `afr`, `me`.
+
+## Storage
+
+### SQLite (Recommended)
+
+Configure in wrangler:
+```jsonc
+{ "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyDO"] }] }
+```
+
+SQL API is synchronous:
+```typescript
+// Write
+this.ctx.storage.sql.exec(
+  "INSERT INTO items (name, value) VALUES (?, ?)",
+  name, value
+);
+
+// Read
+const rows = this.ctx.storage.sql.exec<{ id: number; name: string }>(
+  "SELECT * FROM items WHERE name = ?", name
+).toArray();
+
+// Single row
+const row = this.ctx.storage.sql.exec<{ count: number }>(
+  "SELECT COUNT(*) as count FROM items"
+).one();
+```
+
+### Migrations
+
+**Note:** `PRAGMA user_version` is **not supported** in Durable Objects SQLite storage. Use a `_sql_schema_migrations` table instead:
+
+```typescript
+constructor(ctx: DurableObjectState, env: Env) {
+  super(ctx, env);
+  ctx.blockConcurrencyWhile(async () => this.migrate());
+}
+
+private migrate() {
+  this.ctx.storage.sql.exec(`
+    CREATE TABLE IF NOT EXISTS _sql_schema_migrations (
+      id INTEGER PRIMARY KEY,
+      applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+
+  const currentVersion = this.ctx.storage.sql
+    .exec<{ version: number }>("SELECT COALESCE(MAX(id), 0) as version FROM _sql_schema_migrations")
+    .one().version;
+
+  if (currentVersion < 1) {
+    this.ctx.storage.sql.exec(`
+      CREATE TABLE IF NOT EXISTS items (id INTEGER PRIMARY KEY, data TEXT);
+      CREATE INDEX IF NOT EXISTS idx_items_data ON items(data);
+      INSERT INTO _sql_schema_migrations (id) VALUES (1);
+    `);
+  }
+  if (currentVersion < 2) {
+    this.ctx.storage.sql.exec(`
+      ALTER TABLE items ADD COLUMN created_at INTEGER;
+      INSERT INTO _sql_schema_migrations (id) VALUES (2);
+    `);
+  }
+}
+```
+
+For production apps, consider [`durable-utils`](https://github.com/lambrospetrou/durable-utils#sqlite-schema-migrations) — provides a `SQLSchemaMigrations` class that tracks executed migrations both in memory and in storage. Also see [`@cloudflare/actors` storage utilities](https://github.com/cloudflare/actors/blob/main/packages/storage/src/sql-schema-migrations.ts) — a reference implementation of the same pattern used by the Cloudflare Actors framework.
+
+### State Types
+
+| Type | Speed | Persistence | Use Case |
+|------|-------|-------------|----------|
+| Class properties | Fastest | Lost on eviction | Caching, active connections |
+| SQLite storage | Fast | Durable | Primary data |
+| External (R2, D1) | Variable | Durable, cross-DO | Large files, shared data |
+
+**Rule**: Always persist critical state to SQLite first, then update in-memory cache.
+
+## Concurrency
+
+### Input/Output Gates
+
+Storage operations automatically block other requests (input gates). Responses wait for writes (output gates).
+
+```typescript
+async increment(): Promise<number> {
+  // Safe: input gates block interleaving during storage ops
+  const val = (await this.ctx.storage.get<number>("count")) ?? 0;
+  await this.ctx.storage.put("count", val + 1);
+  return val + 1;
+}
+```
+
+### Write Coalescing
+
+Multiple writes without `await` between them are batched atomically:
+
+```typescript
+// ✅ Good: All three writes commit atomically
+this.ctx.storage.sql.exec("UPDATE accounts SET balance = balance - ? WHERE id = ?", amount, fromId);
+this.ctx.storage.sql.exec("UPDATE accounts SET balance = balance + ? WHERE id = ?", amount, toId);
+this.ctx.storage.sql.exec("INSERT INTO transfers (from_id, to_id, amount) VALUES (?, ?, ?)", fromId, toId, amount);
+
+// ❌ Bad: await breaks coalescing
+await this.ctx.storage.put("key1", val1);
+await this.ctx.storage.put("key2", val2); // Separate transaction!
+```
+
+### Race Conditions with External I/O
+
+`fetch()` and other non-storage I/O allows interleaving:
+
+```typescript
+// ⚠️ Race condition possible
+async processItem(id: string) {
+  const item = await this.ctx.storage.get<Item>(`item:${id}`);
+  if (item?.status === "pending") {
+    await fetch("https://api.example.com/process"); // Other requests can run here!
+    await this.ctx.storage.put(`item:${id}`, { status: "completed" });
+  }
+}
+```
+
+**Solution**: Use optimistic locking (version numbers) or `transaction()`.
+
+### blockConcurrencyWhile()
+
+Blocks ALL concurrency. Use sparingly - only for initialization:
+
+```typescript
+// ✅ Good: One-time init
+constructor(ctx: DurableObjectState, env: Env) {
+  super(ctx, env);
+  ctx.blockConcurrencyWhile(async () => this.migrate());
+}
+
+// ❌ Bad: On every request (kills throughput)
+async handleRequest() {
+  await this.ctx.blockConcurrencyWhile(async () => {
+    // ~5ms = max 200 req/sec
+  });
+}
+```
+
+**Never** hold across external I/O (fetch, R2, KV).
+
+## RPC Methods
+
+Use RPC (compatibility date >= 2024-04-03) instead of fetch() handler:
+
+```typescript
+export class ChatRoom extends DurableObject<Env> {
+  async sendMessage(userId: string, content: string): Promise<Message> {
+    // Public methods are RPC endpoints
+    const result = this.ctx.storage.sql.exec<{ id: number }>(
+      "INSERT INTO messages (user_id, content) VALUES (?, ?) RETURNING id",
+      userId, content
+    );
+    return { id: result.one().id, userId, content };
+  }
+}
+
+// Caller
+const stub = env.CHAT_ROOM.getByName(roomId);
+const msg = await stub.sendMessage("user-123", "Hello!"); // Typed!
+```
+
+### Explicit init() Method
+
+DOs don't know their own ID. Pass identity explicitly:
+
+```typescript
+async init(entityId: string, metadata: Metadata): Promise<void> {
+  await this.ctx.storage.put("entityId", entityId);
+  await this.ctx.storage.put("metadata", metadata);
+}
+```
+
+## Alarms
+
+One alarm per DO. `setAlarm()` replaces existing.
+
+```typescript
+// Schedule
+await this.ctx.storage.setAlarm(Date.now() + 60_000);
+
+// Handler
+async alarm(): Promise<void> {
+  const tasks = this.ctx.storage.sql.exec<Task>(
+    "SELECT * FROM tasks WHERE due_at <= ?", Date.now()
+  ).toArray();
+  
+  for (const task of tasks) {
+    await this.processTask(task);
+  }
+  
+  // Reschedule if more work
+  const next = this.ctx.storage.sql.exec<{ due_at: number }>(
+    "SELECT MIN(due_at) as due_at FROM tasks WHERE due_at > ?", Date.now()
+  ).one();
+  if (next?.due_at) {
+    await this.ctx.storage.setAlarm(next.due_at);
+  }
+}
+
+// Get/Delete
+const alarm = await this.ctx.storage.getAlarm();
+await this.ctx.storage.deleteAlarm();
+```
+
+**Retry**: Alarms auto-retry on failure. Use idempotent handlers.
+
+## WebSockets (Hibernation API)
+
+```typescript
+async fetch(request: Request): Promise<Response> {
+  const pair = new WebSocketPair();
+  this.ctx.acceptWebSocket(pair[1]);
+  return new Response(null, { status: 101, webSocket: pair[0] });
+}
+
+async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
+  const data = JSON.parse(message as string);
+  // Handle message
+  ws.send(JSON.stringify({ type: "ack" }));
+}
+
+async webSocketClose(ws: WebSocket, code: number, reason: string) {
+  // Cleanup
+}
+
+// Broadcast
+getWebSockets().forEach(ws => ws.send(JSON.stringify(payload)));
+```
+
+## Error Handling
+
+```typescript
+async safeOperation(): Promise<Result> {
+  try {
+    return await this.riskyOperation();
+  } catch (error) {
+    console.error("Operation failed:", error);
+    // Log to external service if needed
+    throw error; // Re-throw to signal failure to caller
+  }
+}
+```
+
+**Note**: Uncaught exceptions may terminate the DO instance. In-memory state is lost, but SQLite storage persists.

package/skills/durable-objects/references/testing.md

@@ -0,0 +1,264 @@
+# Testing Durable Objects
+
+Use `@cloudflare/vitest-pool-workers` to test DOs inside the Workers runtime.
+
+## Setup
+
+### Install Dependencies
+
+```bash
+npm i -D vitest@~3.2.0 @cloudflare/vitest-pool-workers
+```
+
+### vitest.config.ts
+
+```typescript
+import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
+
+export default defineWorkersConfig({
+  test: {
+    poolOptions: {
+      workers: {
+        wrangler: { configPath: "./wrangler.toml" },
+      },
+    },
+  },
+});
+```
+
+### TypeScript Config (test/tsconfig.json)
+
+```jsonc
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "types": ["@cloudflare/vitest-pool-workers"]
+  },
+  "include": ["./**/*.ts", "../src/worker-configuration.d.ts"]
+}
+```
+
+### Environment Types (env.d.ts)
+
+```typescript
+declare module "cloudflare:test" {
+  interface ProvidedEnv extends Env {}
+}
+```
+
+## Unit Tests (Direct DO Access)
+
+```typescript
+import { env } from "cloudflare:test";
+import { describe, it, expect } from "vitest";
+
+describe("Counter DO", () => {
+  it("should increment", async () => {
+    const stub = env.COUNTER.getByName("test-counter");
+    
+    expect(await stub.increment()).toBe(1);
+    expect(await stub.increment()).toBe(2);
+    expect(await stub.getCount()).toBe(2);
+  });
+
+  it("isolates different instances", async () => {
+    const stub1 = env.COUNTER.getByName("counter-1");
+    const stub2 = env.COUNTER.getByName("counter-2");
+    
+    await stub1.increment();
+    await stub1.increment();
+    await stub2.increment();
+    
+    expect(await stub1.getCount()).toBe(2);
+    expect(await stub2.getCount()).toBe(1);
+  });
+});
+```
+
+## Integration Tests (HTTP via SELF)
+
+```typescript
+import { SELF } from "cloudflare:test";
+import { describe, it, expect } from "vitest";
+
+describe("Worker HTTP", () => {
+  it("should increment via POST", async () => {
+    const res = await SELF.fetch("http://example.com?id=test", {
+      method: "POST",
+    });
+    
+    expect(res.status).toBe(200);
+    const data = await res.json<{ count: number }>();
+    expect(data.count).toBe(1);
+  });
+
+  it("should get count via GET", async () => {
+    await SELF.fetch("http://example.com?id=get-test", { method: "POST" });
+    await SELF.fetch("http://example.com?id=get-test", { method: "POST" });
+    
+    const res = await SELF.fetch("http://example.com?id=get-test");
+    const data = await res.json<{ count: number }>();
+    expect(data.count).toBe(2);
+  });
+});
+```
+
+## Direct Internal Access
+
+Use `runInDurableObject()` to access instance internals and storage:
+
+```typescript
+import { env, runInDurableObject } from "cloudflare:test";
+import { describe, it, expect } from "vitest";
+import { Counter } from "../src";
+
+describe("DO internals", () => {
+  it("can verify storage directly", async () => {
+    const stub = env.COUNTER.getByName("direct-test");
+    await stub.increment();
+    await stub.increment();
+
+    await runInDurableObject(stub, async (instance: Counter, state) => {
+      expect(instance).toBeInstanceOf(Counter);
+      
+      const result = state.storage.sql
+        .exec<{ value: number }>(
+          "SELECT value FROM counters WHERE name = ?",
+          "default"
+        )
+        .one();
+      expect(result.value).toBe(2);
+    });
+  });
+});
+```
+
+## List DO IDs
+
+```typescript
+import { env, listDurableObjectIds } from "cloudflare:test";
+import { describe, it, expect } from "vitest";
+
+describe("DO listing", () => {
+  it("can list all IDs in namespace", async () => {
+    const id1 = env.COUNTER.idFromName("list-1");
+    const id2 = env.COUNTER.idFromName("list-2");
+    
+    await env.COUNTER.get(id1).increment();
+    await env.COUNTER.get(id2).increment();
+    
+    const ids = await listDurableObjectIds(env.COUNTER);
+    expect(ids.length).toBe(2);
+    expect(ids.some(id => id.equals(id1))).toBe(true);
+    expect(ids.some(id => id.equals(id2))).toBe(true);
+  });
+});
+```
+
+## Testing Alarms
+
+Use `runDurableObjectAlarm()` to trigger alarms immediately:
+
+```typescript
+import { env, runInDurableObject, runDurableObjectAlarm } from "cloudflare:test";
+import { describe, it, expect } from "vitest";
+
+describe("DO alarms", () => {
+  it("can trigger alarms immediately", async () => {
+    const stub = env.COUNTER.getByName("alarm-test");
+    await stub.increment();
+    await stub.increment();
+    expect(await stub.getCount()).toBe(2);
+
+    // Schedule alarm
+    await runInDurableObject(stub, async (instance, state) => {
+      await state.storage.setAlarm(Date.now() + 60_000);
+    });
+
+    // Execute immediately without waiting
+    const ran = await runDurableObjectAlarm(stub);
+    expect(ran).toBe(true);
+
+    // Verify alarm handler ran (if it resets counter)
+    expect(await stub.getCount()).toBe(0);
+
+    // No alarm scheduled now
+    const ranAgain = await runDurableObjectAlarm(stub);
+    expect(ranAgain).toBe(false);
+  });
+});
+```
+
+Example alarm handler:
+```typescript
+async alarm(): Promise<void> {
+  this.ctx.storage.sql.exec("DELETE FROM counters");
+}
+```
+
+## Test Isolation
+
+Each test gets isolated storage automatically. DOs from one test don't affect others:
+
+```typescript
+describe("Isolation", () => {
+  it("first test creates DO", async () => {
+    const stub = env.COUNTER.getByName("isolated");
+    await stub.increment();
+    expect(await stub.getCount()).toBe(1);
+  });
+
+  it("second test has fresh state", async () => {
+    const ids = await listDurableObjectIds(env.COUNTER);
+    expect(ids.length).toBe(0); // Previous test's DO is gone
+    
+    const stub = env.COUNTER.getByName("isolated");
+    expect(await stub.getCount()).toBe(0); // Fresh instance
+  });
+});
+```
+
+## SQLite Storage Testing
+
+```typescript
+describe("SQLite", () => {
+  it("can verify SQL storage", async () => {
+    const stub = env.COUNTER.getByName("sqlite-test");
+    await stub.increment("page-views");
+    await stub.increment("page-views");
+    await stub.increment("api-calls");
+
+    await runInDurableObject(stub, async (instance, state) => {
+      const rows = state.storage.sql
+        .exec<{ name: string; value: number }>(
+          "SELECT name, value FROM counters ORDER BY name"
+        )
+        .toArray();
+
+      expect(rows).toEqual([
+        { name: "api-calls", value: 1 },
+        { name: "page-views", value: 2 },
+      ]);
+
+      expect(state.storage.sql.databaseSize).toBeGreaterThan(0);
+    });
+  });
+});
+```
+
+## Running Tests
+
+```bash
+npx vitest        # Watch mode
+npx vitest run    # Single run
+```
+
+package.json:
+```json
+{
+  "scripts": {
+    "test": "vitest"
+  }
+}
+```