memory-journal-mcp 7.7.1 → 8.0.0

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

@@ -0,0 +1,205 @@
+# 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/references/workers/README.md

@@ -0,0 +1,110 @@
+# 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/references/workers/api.md

@@ -0,0 +1,197 @@
+# 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)

package/skills/cloudflare/references/workers/configuration.md

@@ -0,0 +1,184 @@
+# Workers Configuration
+
+## wrangler.jsonc (Recommended)
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01", // Use current date for new projects
+
+  // Bindings (non-inheritable)
+  "vars": { "ENVIRONMENT": "production" },
+  "kv_namespaces": [{ "binding": "MY_KV", "id": "abc123" }],
+  "r2_buckets": [{ "binding": "MY_BUCKET", "bucket_name": "my-bucket" }],
+  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "xyz789" }],
+
+  // Environments
+  "env": {
+    "staging": {
+      "vars": { "ENVIRONMENT": "staging" },
+      "kv_namespaces": [{ "binding": "MY_KV", "id": "staging-id" }],
+    },
+  },
+}
+```
+
+## Configuration Rules
+
+**Inheritable**: `name`, `main`, `compatibility_date`, `routes`, `workers_dev`  
+**Non-inheritable**: All bindings (`vars`, `kv_namespaces`, `r2_buckets`, etc.)  
+**Top-level only**: `migrations`, `keep_vars`, `send_metrics`
+
+**ALWAYS set `compatibility_date` to current date for new projects**
+
+## Bindings
+
+```jsonc
+{
+  // Environment variables - access via env.VAR_NAME
+  "vars": { "ENVIRONMENT": "production" },
+
+  // KV (key-value storage)
+  "kv_namespaces": [{ "binding": "MY_KV", "id": "abc123" }],
+
+  // R2 (object storage)
+  "r2_buckets": [{ "binding": "MY_BUCKET", "bucket_name": "my-bucket" }],
+
+  // D1 (SQL database)
+  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "xyz789" }],
+
+  // Durable Objects (stateful coordination)
+  "durable_objects": {
+    "bindings": [{ "name": "COUNTER", "class_name": "Counter" }],
+  },
+
+  // Queues (message queues)
+  "queues": {
+    "producers": [{ "binding": "MY_QUEUE", "queue": "my-queue" }],
+    "consumers": [{ "queue": "my-queue", "max_batch_size": 10 }],
+  },
+
+  // Service bindings (worker-to-worker RPC)
+  "services": [{ "binding": "SERVICE_B", "service": "service-b" }],
+
+  // Analytics Engine
+  "analytics_engine_datasets": [{ "binding": "ANALYTICS" }],
+}
+```
+
+### Secrets
+
+Set via CLI (never in config):
+
+```bash
+npx wrangler secret put API_KEY
+```
+
+Access: `env.API_KEY`
+
+### Automatic Provisioning (Beta)
+
+Bindings without IDs are auto-created:
+
+```jsonc
+{ "kv_namespaces": [{ "binding": "MY_KV" }] } // ID added on deploy
+```
+
+## Routes & Triggers
+
+```jsonc
+{
+  "routes": [{ "pattern": "example.com/*", "zone_name": "example.com" }],
+  "triggers": {
+    "crons": ["0 */6 * * *"], // Every 6 hours
+  },
+}
+```
+
+## TypeScript Setup
+
+### Automatic Type Generation (Recommended)
+
+```bash
+npm install -D @cloudflare/workers-types
+npx wrangler types  # Generates .wrangler/types/runtime.d.ts from wrangler.jsonc
+```
+
+`tsconfig.json`:
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types"],
+  },
+  "include": [".wrangler/types/**/*.ts", "src/**/*"],
+}
+```
+
+Import generated types:
+
+```typescript
+import type { Env } from './.wrangler/types/runtime'
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    await env.MY_KV.get('key') // Fully typed, autocomplete works
+    return new Response('OK')
+  },
+}
+```
+
+Re-run `npx wrangler types` after changing bindings in wrangler.jsonc
+
+### Manual Type Definition (Legacy)
+
+```typescript
+interface Env {
+  MY_KV: KVNamespace
+  DB: D1Database
+  API_KEY: string
+}
+```
+
+## Advanced Options
+
+```jsonc
+{
+  // Auto-locate compute near data sources
+  "placement": { "mode": "smart" },
+
+  // Enable Node.js built-ins (Buffer, process, path, etc.)
+  "compatibility_flags": ["nodejs_compat_v2"],
+
+  // Observability (10% sampling)
+  "observability": { "enabled": true, "head_sampling_rate": 0.1 },
+}
+```
+
+### Node.js Compatibility
+
+`nodejs_compat_v2` enables:
+
+- `Buffer`, `process.env`, `path`, `stream`
+- CommonJS `require()` for Node modules
+- `node:` imports (e.g., `import { Buffer } from 'node:buffer'`)
+
+**Note:** Adds ~1-2ms cold start overhead. Use Workers APIs (R2, KV) when possible
+
+## Deployment Commands
+
+```bash
+npx wrangler deploy              # Production
+npx wrangler deploy --env staging
+npx wrangler deploy --dry-run    # Validate only
+```
+
+## See Also
+
+- [API](./api.md) - Runtime APIs and bindings usage
+- [Patterns](./patterns.md) - Deployment strategies
+- [Wrangler](../wrangler/README.md) - CLI reference