@mohanscodex/spectra-code 0.4.9 → 0.5.0

package/skills/cloudflare-deploy/references/workerd/gotchas.md

@@ -0,0 +1,139 @@
+# Workerd Gotchas
+
+## Common Errors
+
+### "Missing compatibility date"
+**Cause:** Compatibility date not set
+**Solution:**
+❌ Wrong:
+```capnp
+const worker :Workerd.Worker = (
+  serviceWorkerScript = embed "worker.js"
+)
+```
+
+✅ Correct:
+```capnp
+const worker :Workerd.Worker = (
+  serviceWorkerScript = embed "worker.js",
+  compatibilityDate = "2024-01-15"  # Always set!
+)
+```
+
+### Wrong Binding Type
+**Problem:** JSON not parsed
+**Cause:** Using `text = '{"key":"value"}'` instead of `json`
+**Solution:** Use `json = '{"key":"value"}'` for parsed objects
+
+### Service vs Namespace
+**Problem:** Cannot create DO instance
+**Cause:** Using `service = "room-service"` for Durable Object
+**Solution:** Use `durableObjectNamespace = "Room"` for DO bindings
+
+### Module Name Mismatch
+**Problem:** Import fails
+**Cause:** Module name includes path: `name = "src/index.js"`
+**Solution:** Use simple names: `name = "index.js"`, embed with path
+
+## Network Access
+
+**Problem:** Fetch fails with network error
+**Cause:** No network service configured (workerd has no global fetch)
+**Solution:** Add network service binding:
+```capnp
+services = [(name = "internet", network = (allow = ["public"]))]
+bindings = [(name = "NET", service = "internet")]
+```
+
+Or external service:
+```capnp
+bindings = [(name = "API", service = (external = (address = "api.com:443", http = (style = tls))))]
+```
+
+### "Worker not responding"
+**Cause:** Socket misconfigured, no fetch handler, or port unavailable
+**Solution:** Verify socket `address` matches, worker exports `fetch()`, port available
+
+### "Binding not found"
+**Cause:** Name mismatch or service doesn't exist
+**Solution:** Check binding name in config matches code (`env.BINDING` for ES modules)
+
+### "Module not found"
+**Cause:** Module name doesn't match import or bad embed path
+**Solution:** Module `name` must match import path exactly, verify `embed` path
+
+### "Compatibility error"
+**Cause:** Date not set or API unavailable on that date
+**Solution:** Set `compatibilityDate`, verify API available on that date
+
+## Performance Issues
+
+**Problem:** High memory usage
+**Cause:** Large caches or many isolates
+**Solution:** Set cache limits, reduce isolate count, or use V8 flags (caution)
+
+**Problem:** Slow startup
+**Cause:** Many modules or complex config
+**Solution:** Compile to binary (`workerd compile`), reduce imports
+
+**Problem:** Request timeouts
+**Cause:** External service issues or DNS problems
+**Solution:** Check connectivity, DNS resolution, TLS handshake
+
+## Build Issues
+
+**Problem:** Cap'n Proto syntax errors
+**Cause:** Invalid config or missing schema
+**Solution:** Install capnproto tools, validate: `capnp compile -I. config.capnp`
+
+**Problem:** Embed path not found
+**Cause:** Path relative to config file
+**Solution:** Use correct relative path or absolute path
+
+**Problem:** V8 flags cause crashes
+**Cause:** Unsafe V8 flags
+**Solution:** ⚠️ V8 flags unsupported in production. Test thoroughly before use.
+
+## Security Issues
+
+**Problem:** Hardcoded secrets in config
+**Cause:** `text` binding with secret value
+**Solution:** Use `fromEnvironment` to load from env vars
+
+**Problem:** Overly broad network access
+**Cause:** `network = (allow = ["*"])`
+**Solution:** Restrict to `allow = ["public"]` or specific hosts
+
+**Problem:** Extractable crypto keys
+**Cause:** `cryptoKey = (extractable = true, ...)`
+**Solution:** Set `extractable = false` unless export required
+
+## Compatibility Changes
+
+**Problem:** Breaking changes after compat date update
+**Cause:** New flags enabled between dates
+**Solution:** Review [compat dates docs](https://developers.cloudflare.com/workers/configuration/compatibility-dates/), test locally first
+
+**Problem:** "Compatibility date not supported"
+**Cause:** Workerd version older than compat date
+**Solution:** Update workerd binary (version = max compat date supported)
+
+## Limits
+
+| Resource/Limit | Value | Notes |
+|----------------|-------|-------|
+| V8 flags | Unsupported in production | Use with caution |
+| Compatibility date | Must match workerd version | Update if mismatch |
+| Module count | Affects startup time | Many imports slow |
+
+## Troubleshooting Steps
+
+1. **Enable verbose logging**: `workerd serve config.capnp --verbose`
+2. **Check logs**: Look for error messages, stack traces
+3. **Validate config**: `capnp compile -I. config.capnp`
+4. **Test bindings**: Log `Object.keys(env)` to verify
+5. **Check versions**: Workerd version vs compat date
+6. **Isolate issue**: Minimal repro config
+7. **Review schema**: [workerd.capnp](https://github.com/cloudflare/workerd/blob/main/src/workerd/server/workerd.capnp)
+
+See [configuration.md](./configuration.md) for config details, [patterns.md](./patterns.md) for working examples, [api.md](./api.md) for runtime APIs.

package/skills/cloudflare-deploy/references/workerd/patterns.md

@@ -0,0 +1,192 @@
+# Workerd Patterns
+
+## Multi-Service Architecture
+```capnp
+const config :Workerd.Config = (
+  services = [
+    (name = "frontend", worker = (
+      modules = [(name = "index.js", esModule = embed "frontend/index.js")],
+      compatibilityDate = "2024-01-15",
+      bindings = [(name = "API", service = "api")]
+    )),
+    (name = "api", worker = (
+      modules = [(name = "index.js", esModule = embed "api/index.js")],
+      compatibilityDate = "2024-01-15",
+      bindings = [(name = "DB", service = "postgres"), (name = "CACHE", kvNamespace = "kv")]
+    )),
+    (name = "postgres", external = (address = "db.internal:5432", http = ())),
+    (name = "kv", disk = (path = "/var/kv", writable = true))
+  ],
+  sockets = [(name = "http", address = "*:8080", http = (), service = "frontend")]
+);
+```
+
+## Durable Objects
+```capnp
+const worker :Workerd.Worker = (
+  modules = [(name = "index.js", esModule = embed "index.js"), (name = "room.js", esModule = embed "room.js")],
+  compatibilityDate = "2024-01-15",
+  bindings = [(name = "ROOMS", durableObjectNamespace = "Room")],
+  durableObjectNamespaces = [(className = "Room", uniqueKey = "v1")],
+  durableObjectStorage = (localDisk = "/var/do")
+);
+```
+
+## Dev vs Prod Configs
+```capnp
+# Use parameter bindings for env-specific config
+const baseWorker :Workerd.Worker = (
+  modules = [(name = "index.js", esModule = embed "src/index.js")],
+  compatibilityDate = "2024-01-15",
+  bindings = [(name = "API_URL", parameter = (type = text))]
+);
+
+const prodWorker :Workerd.Worker = (
+  inherit = "base-service",
+  bindings = [(name = "API_URL", text = "https://api.prod.com")]
+);
+```
+
+## HTTP Reverse Proxy
+```capnp
+services = [
+  (name = "proxy", worker = (serviceWorkerScript = embed "proxy.js", compatibilityDate = "2024-01-15", bindings = [(name = "BACKEND", service = "backend")])),
+  (name = "backend", external = (address = "internal:8080", http = ()))
+]
+```
+
+## Local Development
+
+**Recommended:** Use Wrangler
+```bash
+wrangler dev  # Uses workerd internally
+```
+
+**Direct workerd:**
+```bash
+workerd serve config.capnp --socket-addr http=*:3000 --verbose
+```
+
+**Environment variables:**
+```capnp
+bindings = [(name = "DATABASE_URL", fromEnvironment = "DATABASE_URL")]
+```
+
+## Testing
+```bash
+workerd test config.capnp
+workerd test config.capnp --test-only=test.js
+```
+
+Test files must be included in `modules = [...]` config.
+
+## Production Deployment
+
+### Compiled Binary (Recommended)
+```bash
+workerd compile config.capnp myConfig -o production-server
+./production-server
+```
+
+### Docker
+```dockerfile
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y ca-certificates
+COPY workerd /usr/local/bin/
+COPY config.capnp /etc/workerd/
+COPY src/ /etc/workerd/src/
+EXPOSE 8080
+CMD ["workerd", "serve", "/etc/workerd/config.capnp"]
+```
+
+### Systemd
+```ini
+# /etc/systemd/system/workerd.service
+[Service]
+ExecStart=/usr/bin/workerd serve /etc/workerd/config.capnp --socket-fd http=3
+Restart=always
+User=nobody
+```
+
+See systemd socket activation docs for complete setup.
+
+## Framework Integration
+
+### Hono
+```javascript
+import { Hono } from 'hono';
+
+const app = new Hono();
+
+app.get('/', (c) => c.text('Hello Hono!'));
+app.get('/api/:id', async (c) => {
+  const id = c.req.param('id');
+  const data = await c.env.KV.get(id);
+  return c.json({ id, data });
+});
+
+export default app;
+```
+
+### itty-router
+```javascript
+import { Router } from 'itty-router';
+
+const router = Router();
+
+router.get('/', () => new Response('Hello itty!'));
+router.get('/api/:id', async (request, env) => {
+  const { id } = request.params;
+  const data = await env.KV.get(id);
+  return Response.json({ id, data });
+});
+
+export default {
+  fetch: (request, env, ctx) => router.handle(request, env, ctx)
+};
+```
+
+## Best Practices
+
+1. **Use ES modules** over service worker syntax
+2. **Explicit bindings** - no global namespace assumptions
+3. **Type safety** - define `Env` interfaces (use `wrangler types`)
+4. **Service isolation** - split concerns into multiple services
+5. **Pin compat date** in production after testing
+6. **Use ctx.waitUntil()** for background tasks
+7. **Handle errors gracefully** with try/catch
+8. **Configure resource limits** on caches/storage
+
+## Common Patterns
+
+### Error Handling
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    try {
+      return await handleRequest(request, env);
+    } catch (error) {
+      console.error("Request failed", error);
+      return new Response("Internal Error", {status: 500});
+    }
+  }
+};
+```
+
+### Background Tasks
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    const response = new Response("OK");
+    
+    // Fire-and-forget background work
+    ctx.waitUntil(
+      env.ANALYTICS.put(request.url, Date.now())
+    );
+    
+    return response;
+  }
+};
+```
+
+See [configuration.md](./configuration.md) for config syntax, [api.md](./api.md) for runtime APIs, [gotchas.md](./gotchas.md) for common errors.

package/skills/cloudflare-deploy/references/workers/README.md

@@ -0,0 +1,108 @@
+# Cloudflare Workers
+
+Expert guidance for building, deploying, and optimizing Cloudflare Workers applications.
+
+## Overview
+
+Cloudflare Workers run on V8 isolates (NOT containers/VMs):
+- Extremely fast cold starts (< 1ms)
+- Global deployment across 300+ locations
+- Web standards compliant (fetch, URL, Headers, Request, Response)
+- Support JS/TS, Python, Rust, and WebAssembly
+
+**Key principle**: Workers use web platform APIs wherever possible for portability.
+
+## Module Worker Pattern (Recommended)
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    return new Response('Hello World!');
+  },
+};
+```
+
+**Handler parameters**:
+- `request`: Incoming HTTP request (standard Request object)
+- `env`: Environment bindings (KV, D1, R2, secrets, vars)
+- `ctx`: Execution context (`waitUntil`, `passThroughOnException`)
+
+## Essential Commands
+
+```bash
+npx wrangler dev                    # Local dev
+npx wrangler dev --remote           # Remote dev (actual resources)
+npx wrangler deploy                 # Production
+npx wrangler deploy --env staging   # Specific environment
+npx wrangler tail                   # Stream logs
+npx wrangler secret put API_KEY     # Set secret
+```
+
+## When to Use Workers
+
+- API endpoints at the edge
+- Request/response transformation
+- Authentication/authorization layers
+- Static asset optimization
+- A/B testing and feature flags
+- Rate limiting and security
+- Proxy/routing logic
+- WebSocket applications
+
+## Quick Start
+
+```bash
+npm create cloudflare@latest my-worker -- --type hello-world
+cd my-worker
+npx wrangler dev
+```
+
+## Handler Signatures
+
+```typescript
+// HTTP requests
+async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response>
+
+// Cron triggers
+async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promise<void>
+
+// Queue consumer
+async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext): Promise<void>
+
+// Tail consumer
+async tail(events: TraceItem[], env: Env, ctx: ExecutionContext): Promise<void>
+```
+
+## Resources
+
+**Docs**: https://developers.cloudflare.com/workers/  
+**Examples**: https://developers.cloudflare.com/workers/examples/  
+**Runtime APIs**: https://developers.cloudflare.com/workers/runtime-apis/
+
+## In This Reference
+
+- [Configuration](./configuration.md) - wrangler.jsonc setup, bindings, environments
+- [API](./api.md) - Runtime APIs, bindings, execution context
+- [Patterns](./patterns.md) - Common workflows, testing, optimization
+- [Frameworks](./frameworks.md) - Hono, routing, validation
+- [Gotchas](./gotchas.md) - Common issues, limits, troubleshooting
+
+## Reading Order
+
+| Task | Start With | Then Read |
+|------|------------|-----------|
+| First Worker | README → Configuration → API | Patterns |
+| Add framework | Frameworks | Configuration (bindings) |
+| Add storage/bindings | Configuration → API (binding usage) | See Also links |
+| Debug issues | Gotchas | API (specific binding docs) |
+| Production optimization | Patterns | API (caching, streaming) |
+| Type safety | Configuration (TypeScript) | Frameworks (Hono typing) |
+
+## See Also
+
+- [KV](../kv/README.md) - Key-value storage
+- [D1](../d1/README.md) - SQL database
+- [R2](../r2/README.md) - Object storage
+- [Durable Objects](../durable-objects/README.md) - Stateful coordination
+- [Queues](../queues/README.md) - Message queues
+- [Wrangler](../wrangler/README.md) - CLI tool reference

package/skills/cloudflare-deploy/references/workers/api.md

@@ -0,0 +1,195 @@
+# Workers Runtime APIs
+
+## Fetch Handler
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+    if (request.method === 'POST' && url.pathname === '/api') {
+      const body = await request.json();
+      return new Response(JSON.stringify({ id: 1 }), {
+        headers: { 'Content-Type': 'application/json' }
+      });
+    }
+    return fetch(request);  // Subrequest to origin
+  },
+};
+```
+
+## Execution Context
+
+```typescript
+ctx.waitUntil(logAnalytics(request));  // Background work, don't block response
+ctx.passThroughOnException();  // Failover to origin on error
+```
+
+**Never** `await` background operations - use `ctx.waitUntil()`.
+
+## Bindings
+
+```typescript
+// KV
+await env.MY_KV.get('key');
+await env.MY_KV.put('key', 'value', { expirationTtl: 3600 });
+
+// R2
+const obj = await env.MY_BUCKET.get('file.txt');
+await env.MY_BUCKET.put('file.txt', 'content');
+
+// D1
+const result = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(1).first();
+
+// D1 Sessions (2024+) - read-after-write consistency
+const session = env.DB.withSession();
+await session.prepare('INSERT INTO users (name) VALUES (?)').bind('Alice').run();
+const user = await session.prepare('SELECT * FROM users WHERE name = ?').bind('Alice').first(); // Guaranteed fresh
+
+// Queues
+await env.MY_QUEUE.send({ timestamp: Date.now() });
+
+// Secrets/vars
+const key = env.API_KEY;
+```
+
+## Cache API
+
+```typescript
+const cache = caches.default;
+let response = await cache.match(request);
+
+if (!response) {
+  response = await fetch(request);
+  response = new Response(response.body, response);
+  response.headers.set('Cache-Control', 'max-age=3600');
+  ctx.waitUntil(cache.put(request, response.clone()));  // Clone before caching
+}
+```
+
+## HTMLRewriter
+
+```typescript
+return new HTMLRewriter()
+  .on('a[href]', {
+    element(el) {
+      const href = el.getAttribute('href');
+      if (href?.startsWith('http://')) {
+        el.setAttribute('href', href.replace('http://', 'https://'));
+      }
+    }
+  })
+  .transform(response);
+```
+
+**Use cases**: A/B testing, analytics injection, link rewriting
+
+## WebSockets
+
+### Standard WebSocket
+
+```typescript
+const [client, server] = Object.values(new WebSocketPair());
+
+server.accept();
+server.addEventListener('message', event => {
+  server.send(`Echo: ${event.data}`);
+});
+
+return new Response(null, { status: 101, webSocket: client });
+```
+
+### WebSocket Hibernation (Recommended for idle connections)
+
+```typescript
+// In Durable Object
+export class WebSocketDO {
+  async webSocketMessage(ws: WebSocket, message: string) {
+    ws.send(`Echo: ${message}`);
+  }
+  
+  async webSocketClose(ws: WebSocket, code: number, reason: string) {
+    // Cleanup on close
+  }
+  
+  async webSocketError(ws: WebSocket, error: Error) {
+    console.error('WebSocket error:', error);
+  }
+}
+```
+
+Hibernation automatically suspends inactive connections (no CPU cost), wakes on events
+
+## Durable Objects
+
+### RPC Pattern (Recommended 2024+)
+
+```typescript
+export class Counter {
+  private value = 0;
+  
+  constructor(private state: DurableObjectState) {
+    state.blockConcurrencyWhile(async () => {
+      this.value = (await state.storage.get('value')) || 0;
+    });
+  }
+  
+  // Export methods directly - called via RPC (type-safe, zero serialization)
+  async increment(): Promise<number> {
+    this.value++;
+    await this.state.storage.put('value', this.value);
+    return this.value;
+  }
+  
+  async getValue(): Promise<number> {
+    return this.value;
+  }
+}
+
+// Worker usage:
+const stub = env.COUNTER.get(env.COUNTER.idFromName('global'));
+const count = await stub.increment(); // Direct method call, full type safety
+```
+
+### Legacy Fetch Pattern (Pre-2024)
+
+```typescript
+async fetch(request: Request): Promise<Response> {
+  const url = new URL(request.url);
+  if (url.pathname === '/increment') {
+    await this.state.storage.put('value', ++this.value);
+  }
+  return new Response(String(this.value));
+}
+// Usage: await stub.fetch('http://x/increment')
+```
+
+**When to use DOs**: Real-time collaboration, rate limiting, strongly consistent state
+
+## Other Handlers
+
+```typescript
+// Cron: async scheduled(event, env, ctx) { ctx.waitUntil(doCleanup(env)); }
+// Queue: async queue(batch) { for (const msg of batch.messages) { await process(msg.body); msg.ack(); } }
+// Tail: async tail(events, env) { for (const e of events) if (e.outcome === 'exception') await log(e); }
+```
+
+## Service Bindings
+
+```typescript
+// Worker-to-worker RPC (zero latency, no internet round-trip)
+return env.SERVICE_B.fetch(request);
+
+// With RPC (2024+) - same as Durable Objects RPC
+export class ServiceWorker {
+  async getData() { return { data: 'value' }; }
+}
+// Usage: const data = await env.SERVICE_B.getData();
+```
+
+**Benefits**: Type-safe method calls, no HTTP overhead, share code between Workers
+
+## See Also
+
+- [Configuration](./configuration.md) - Binding setup
+- [Patterns](./patterns.md) - Common workflows
+- [KV](../kv/README.md), [D1](../d1/README.md), [R2](../r2/README.md), [Durable Objects](../durable-objects/README.md), [Queues](../queues/README.md)