memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,219 @@
+# Workerd APIs
+
+## Worker Code (JS/TS)
+
+### ES Modules (Recommended)
+
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    const value = await env.KV.get('key') // Bindings in env
+    const response = await env.API.fetch(request) // Service binding
+    ctx.waitUntil(logRequest(request)) // Background task
+    return new Response('OK')
+  },
+  async adminApi(request, env, ctx) {
+    /* Named entrypoint */
+  },
+  async queue(batch, env, ctx) {
+    /* Queue consumer */
+  },
+  async scheduled(event, env, ctx) {
+    /* Cron handler */
+  },
+}
+```
+
+### TypeScript Types
+
+**Generate from wrangler.toml (Recommended):**
+
+```bash
+wrangler types  # Output: worker-configuration.d.ts
+```
+
+**Manual types:**
+
+```typescript
+interface Env {
+  API: Fetcher
+  CACHE: KVNamespace
+  STORAGE: R2Bucket
+  ROOMS: DurableObjectNamespace
+  API_KEY: string
+}
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    return new Response(await env.CACHE.get('key'))
+  },
+}
+```
+
+**Setup:**
+
+```bash
+npm install -D @cloudflare/workers-types
+```
+
+```json
+// tsconfig.json
+{ "compilerOptions": { "types": ["@cloudflare/workers-types"] } }
+```
+
+### Service Worker Syntax (Legacy)
+
+```javascript
+addEventListener('fetch', (event) => {
+  event.respondWith(handleRequest(event.request))
+})
+
+async function handleRequest(request) {
+  const value = await KV.get('key') // Bindings as globals
+  return new Response('OK')
+}
+```
+
+### Durable Objects
+
+```javascript
+export class Room {
+  constructor(state, env) {
+    this.state = state
+    this.env = env
+  }
+
+  async fetch(request) {
+    const url = new URL(request.url)
+    if (url.pathname === '/increment') {
+      const value = (await this.state.storage.get('counter')) || 0
+      await this.state.storage.put('counter', value + 1)
+      return new Response(String(value + 1))
+    }
+    return new Response('Not found', { status: 404 })
+  }
+}
+```
+
+### RPC Between Services
+
+```javascript
+// Caller: env.AUTH.validateToken(token) returns structured data
+const user = await env.AUTH.validateToken(request.headers.get('Authorization'))
+
+// Callee: export methods that return data
+export default {
+  async validateToken(token) {
+    return { id: 123, name: 'Alice' }
+  },
+}
+```
+
+## Web Platform APIs
+
+### Fetch
+
+- `fetch()`, `Request`, `Response`, `Headers`
+- `AbortController`, `AbortSignal`
+
+### Streams
+
+- `ReadableStream`, `WritableStream`, `TransformStream`
+- Byte streams, BYOB readers
+
+### Web Crypto
+
+- `crypto.subtle` (encrypt/decrypt/sign/verify)
+- `crypto.randomUUID()`, `crypto.getRandomValues()`
+
+### Encoding
+
+- `TextEncoder`, `TextDecoder`
+- `atob()`, `btoa()`
+
+### Web Standards
+
+- `URL`, `URLSearchParams`
+- `Blob`, `File`, `FormData`
+- `WebSocket`
+
+### Server-Sent Events (EventSource)
+
+```javascript
+// Server-side SSE
+const { readable, writable } = new TransformStream()
+const writer = writable.getWriter()
+writer.write(new TextEncoder().encode('data: Hello\n\n'))
+return new Response(readable, { headers: { 'Content-Type': 'text/event-stream' } })
+```
+
+### HTMLRewriter (HTML Parsing/Transformation)
+
+```javascript
+const response = await fetch('https://example.com')
+return new HTMLRewriter()
+  .on('a[href]', {
+    element(el) {
+      el.setAttribute('href', `/proxy?url=${encodeURIComponent(el.getAttribute('href'))}`)
+    },
+  })
+  .on('script', {
+    element(el) {
+      el.remove()
+    },
+  })
+  .transform(response)
+```
+
+### TCP Sockets (Experimental)
+
+```javascript
+const socket = await connect({ hostname: 'example.com', port: 80 })
+const writer = socket.writable.getWriter()
+await writer.write(new TextEncoder().encode('GET / HTTP/1.1\r\n\r\n'))
+const reader = socket.readable.getReader()
+const { value } = await reader.read()
+return new Response(value)
+```
+
+### Performance
+
+- `performance.now()`, `performance.timeOrigin`
+- `setTimeout()`, `setInterval()`, `queueMicrotask()`
+
+### Console
+
+- `console.log()`, `console.error()`, `console.warn()`
+
+### Node.js Compat (`nodejs_compat` flag)
+
+```javascript
+import { Buffer } from 'node:buffer'
+import { randomBytes } from 'node:crypto'
+
+const buf = Buffer.from('Hello')
+const random = randomBytes(16)
+```
+
+**Available:** `node:buffer`, `node:crypto`, `node:stream`, `node:util`, `node:events`, `node:assert`, `node:path`, `node:querystring`, `node:url`
+**NOT available:** `node:fs`, `node:http`, `node:net`, `node:child_process`
+
+## CLI Commands
+
+```bash
+workerd serve config.capnp [constantName]          # Start server
+workerd serve config.capnp --socket-addr http=*:3000 --verbose
+workerd compile config.capnp constantName -o binary  # Compile to binary
+workerd test config.capnp [--test-only=test.js]    # Run tests
+```
+
+## Wrangler Integration
+
+Use Wrangler for development:
+
+```bash
+wrangler dev     # Uses workerd internally
+wrangler types   # Generate TypeScript types from wrangler.toml
+```
+
+See [patterns.md](./patterns.md) for usage examples, [configuration.md](./configuration.md) for config details.

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

@@ -0,0 +1,200 @@
+# Workerd Configuration
+
+## Basic Structure
+
+```capnp
+using Workerd = import "/workerd/workerd.capnp";
+
+const config :Workerd.Config = (
+  services = [(name = "main", worker = .mainWorker)],
+  sockets = [(name = "http", address = "*:8080", http = (), service = "main")]
+);
+
+const mainWorker :Workerd.Worker = (
+  modules = [(name = "index.js", esModule = embed "src/index.js")],
+  compatibilityDate = "2024-01-15",
+  bindings = [...]
+);
+```
+
+## Services
+
+**Worker**: Run JS/Wasm code
+
+```capnp
+(name = "api", worker = (
+  modules = [(name = "index.js", esModule = embed "index.js")],
+  compatibilityDate = "2024-01-15",
+  bindings = [...]
+))
+```
+
+**Network**: Internet access
+
+```capnp
+(name = "internet", network = (allow = ["public"], tlsOptions = (trustBrowserCas = true)))
+```
+
+**External**: Reverse proxy
+
+```capnp
+(name = "backend", external = (address = "api.com:443", http = (style = tls)))
+```
+
+**Disk**: Static files
+
+```capnp
+(name = "assets", disk = (path = "/var/www", writable = false))
+```
+
+## Sockets
+
+```capnp
+(name = "http", address = "*:8080", http = (), service = "main")
+(name = "https", address = "*:443", https = (options = (), tlsOptions = (keypair = (...))), service = "main")
+(name = "app", address = "unix:/tmp/app.sock", http = (), service = "main")
+```
+
+## Worker Formats
+
+```capnp
+# ES Modules (recommended)
+modules = [(name = "index.js", esModule = embed "src/index.js"), (name = "wasm.wasm", wasm = embed "build/module.wasm")]
+
+# Service Worker (legacy)
+serviceWorkerScript = embed "worker.js"
+
+# CommonJS
+(name = "legacy.js", commonJsModule = embed "legacy.js", namedExports = ["foo"])
+```
+
+## Bindings
+
+Bindings expose resources to workers. ES modules: `env.BINDING`, Service workers: globals.
+
+### Primitive Types
+
+```capnp
+(name = "API_KEY", text = "secret")                    # String
+(name = "CONFIG", json = '{"key":"val"}')              # Parsed JSON
+(name = "DATA", data = embed "data.bin")               # ArrayBuffer
+(name = "DATABASE_URL", fromEnvironment = "DB_URL")    # System env var
+```
+
+### Service Binding
+
+```capnp
+(name = "AUTH", service = "auth-worker")               # Basic
+(name = "API", service = (
+  name = "backend",
+  entrypoint = "adminApi",                             # Named export
+  props = (json = '{"role":"admin"}')                  # ctx.props
+))
+```
+
+### Storage
+
+```capnp
+(name = "CACHE", kvNamespace = "kv-service")           # KV
+(name = "STORAGE", r2Bucket = "r2-service")            # R2
+(name = "ROOMS", durableObjectNamespace = (
+  serviceName = "room-service",
+  className = "Room"
+))
+(name = "FAST", memoryCache = (
+  id = "cache-id",
+  limits = (maxKeys = 1000, maxValueSize = 1048576)
+))
+```
+
+### Other
+
+```capnp
+(name = "TASKS", queue = "queue-service")
+(name = "ANALYTICS", analyticsEngine = "analytics")
+(name = "LOADER", workerLoader = (id = "dynamic"))
+(name = "KEY", cryptoKey = (format = raw, algorithm = (name = "HMAC", hash = "SHA-256"), keyData = embed "key.bin", usages = [sign, verify], extractable = false))
+(name = "TRACED", wrapped = (moduleName = "tracing", entrypoint = "makeTracer", innerBindings = [(name = "backend", service = "backend")]))
+```
+
+## Compatibility
+
+```capnp
+compatibilityDate = "2024-01-15"                       # Always set!
+compatibilityFlags = ["nodejs_compat", "streams_enable_constructors"]
+```
+
+Version = max compat date. Update carefully after testing.
+
+## Parameter Bindings (Inheritance)
+
+```capnp
+const base :Workerd.Worker = (
+  modules = [...], compatibilityDate = "2024-01-15",
+  bindings = [(name = "API_URL", parameter = (type = text)), (name = "DB", parameter = (type = service))]
+);
+
+const derived :Workerd.Worker = (
+  inherit = "base-service",
+  bindings = [(name = "API_URL", text = "https://api.com"), (name = "DB", service = "postgres")]
+);
+```
+
+## Durable Objects Config
+
+```capnp
+const worker :Workerd.Worker = (
+  modules = [...],
+  compatibilityDate = "2024-01-15",
+  bindings = [(name = "ROOMS", durableObjectNamespace = "Room")],
+  durableObjectNamespaces = [(className = "Room", uniqueKey = "v1")],
+  durableObjectStorage = (localDisk = "/var/do")
+);
+```
+
+## Remote Bindings (Development)
+
+Connect local workerd to production Cloudflare resources:
+
+```capnp
+bindings = [
+  # Remote KV (requires API token)
+  (name = "PROD_KV", kvNamespace = (
+    remote = (
+      accountId = "your-account-id",
+      namespaceId = "your-namespace-id",
+      apiToken = .envVar("CF_API_TOKEN")
+    )
+  )),
+
+  # Remote R2
+  (name = "PROD_R2", r2Bucket = (
+    remote = (
+      accountId = "your-account-id",
+      bucketName = "my-bucket",
+      apiToken = .envVar("CF_API_TOKEN")
+    )
+  )),
+
+  # Remote Durable Object
+  (name = "PROD_DO", durableObjectNamespace = (
+    remote = (
+      accountId = "your-account-id",
+      scriptName = "my-worker",
+      className = "MyDO",
+      apiToken = .envVar("CF_API_TOKEN")
+    )
+  ))
+]
+```
+
+**Note:** Remote bindings require network access and valid Cloudflare API credentials.
+
+## Logging & Debugging
+
+```capnp
+logging = (structuredLogging = true, stdoutPrefix = "OUT: ", stderrPrefix = "ERR: ")
+v8Flags = ["--expose-gc", "--max-old-space-size=2048"]  # ⚠️ Unsupported in production
+```
+
+See [patterns.md](./patterns.md) for multi-service examples, [gotchas.md](./gotchas.md) for config errors.

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

@@ -0,0 +1,151 @@
+# 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.