memory-journal-mcp 7.7.1 → 8.0.1

package/skills/cloudflare/references/smart-placement/configuration.md

@@ -0,0 +1,202 @@
+# Smart Placement Configuration
+
+## wrangler.jsonc Setup
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "placement": {
+    "mode": "smart",
+  },
+}
+```
+
+## Placement Mode Values
+
+| Mode          | Behavior                                                                  |
+| ------------- | ------------------------------------------------------------------------- |
+| `"smart"`     | Enable Smart Placement - automatic optimization based on traffic analysis |
+| `"off"`       | Explicitly disable Smart Placement - always run at edge closest to user   |
+| Not specified | Default behavior - run at edge closest to user (same as `"off"`)          |
+
+**Note:** Smart Placement vs Explicit Placement are separate features. Smart Placement (`mode: "smart"`) uses automatic analysis. For manual placement control, see explicit placement options (`region`, `host`, `hostname` fields - not covered in this reference).
+
+## Frontend + Backend Split Configuration
+
+### Frontend Worker (No Smart Placement)
+
+```jsonc
+// frontend-worker/wrangler.jsonc
+{
+  "name": "frontend",
+  "main": "frontend-worker.ts",
+  // No "placement" - runs at edge
+  "services": [
+    {
+      "binding": "BACKEND",
+      "service": "backend-api",
+    },
+  ],
+}
+```
+
+### Backend Worker (Smart Placement Enabled)
+
+```jsonc
+// backend-api/wrangler.jsonc
+{
+  "name": "backend-api",
+  "main": "backend-worker.ts",
+  "placement": {
+    "mode": "smart",
+  },
+  "d1_databases": [
+    {
+      "binding": "DATABASE",
+      "database_id": "xxx",
+    },
+  ],
+}
+```
+
+## Requirements & Limitations
+
+### Requirements
+
+- **Wrangler version:** 2.20.0+
+- **Analysis time:** Up to 15 minutes
+- **Traffic requirements:** Consistent multi-location traffic
+- **Workers plan:** All plans (Free, Paid, Enterprise)
+
+### What Smart Placement Affects
+
+**CRITICAL LIMITATION - Smart Placement ONLY Affects `fetch` Handlers:**
+
+Smart Placement is fundamentally limited to Workers with default `fetch` handlers. This is a key architectural constraint.
+
+- ✅ **Affects:** `fetch` event handlers ONLY (the default export's fetch method)
+- ❌ **Does NOT affect:**
+  - RPC methods (Service Bindings with `WorkerEntrypoint` - see example below)
+  - Named entrypoints (exports other than `default`)
+  - Workers without `fetch` handlers
+  - Queue consumers, scheduled handlers, or other event types
+
+**Example - Smart Placement ONLY affects `fetch`:**
+
+```typescript
+// ✅ Smart Placement affects this:
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // This runs close to backend when Smart Placement enabled
+    const data = await env.DATABASE.prepare('SELECT * FROM users').all()
+    return Response.json(data)
+  },
+}
+
+// ❌ Smart Placement DOES NOT affect these:
+export class MyRPC extends WorkerEntrypoint {
+  async myMethod() {
+    // This ALWAYS runs at edge, Smart Placement has NO EFFECT
+    const data = await this.env.DATABASE.prepare('SELECT * FROM users').all()
+    return data
+  }
+}
+
+export async function scheduled(event: ScheduledEvent, env: Env) {
+  // NOT affected by Smart Placement
+}
+```
+
+**Consequence:** If your backend logic uses RPC methods (`WorkerEntrypoint`), Smart Placement cannot optimize those calls. You must use fetch-based patterns for Smart Placement to work.
+
+**Solution:** Convert RPC methods to fetch endpoints, or use a wrapper Worker with `fetch` handler that calls your backend RPC (though this adds latency).
+
+### Baseline Traffic
+
+Smart Placement automatically routes 1% of requests WITHOUT optimization as baseline for performance comparison.
+
+### Validation Rules
+
+**Mutually exclusive fields:**
+
+- `mode` cannot be used with explicit placement fields (`region`, `host`, `hostname`)
+- Choose either Smart Placement OR explicit placement, not both
+
+```jsonc
+// ✅ Valid - Smart Placement
+{ "placement": { "mode": "smart" } }
+
+// ✅ Valid - Explicit Placement (different feature)
+{ "placement": { "region": "us-east1" } }
+
+// ❌ Invalid - Cannot combine
+{ "placement": { "mode": "smart", "region": "us-east1" } }
+```
+
+## Dashboard Configuration
+
+**Workers & Pages** → Select Worker → **Settings** → **General** → **Placement: Smart** → Wait 15min → Check **Metrics**
+
+## TypeScript Types
+
+```typescript
+interface Env {
+  BACKEND: Fetcher
+  DATABASE: D1Database
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const data = await env.DATABASE.prepare('SELECT * FROM table').all()
+    return Response.json(data)
+  },
+} satisfies ExportedHandler<Env>
+```
+
+## Cloudflare Pages/Assets Warning
+
+**CRITICAL PERFORMANCE ISSUE:** Enabling Smart Placement with `assets.run_worker_first = true` in Pages projects **severely degrades asset serving performance**. This is one of the most common misconfigurations.
+
+**Why this is bad:**
+
+- Smart Placement routes ALL requests (including static assets) away from edge to remote locations
+- Static assets (HTML, CSS, JS, images) should ALWAYS be served from edge closest to user
+- Result: 2-5x slower asset loading times, poor user experience
+
+**Problem:** Smart Placement routes asset requests away from edge, but static assets should always be served from edge closest to user.
+
+**Solutions (in order of preference):**
+
+1. **Recommended:** Split into separate Workers (frontend at edge + backend with Smart Placement)
+2. Set `"mode": "off"` to explicitly disable Smart Placement for Pages/Assets Workers
+3. Use `assets.run_worker_first = false` (serves assets first, bypasses Worker for static content)
+
+```jsonc
+// ❌ BAD - Degrades asset performance by 2-5x
+{
+  "name": "pages-app",
+  "placement": { "mode": "smart" },
+  "assets": { "run_worker_first": true }
+}
+
+// ✅ GOOD - Frontend at edge, backend optimized
+// frontend-worker/wrangler.jsonc
+{
+  "name": "frontend",
+  "assets": { "run_worker_first": true }
+  // No placement - runs at edge
+}
+
+// backend-worker/wrangler.jsonc
+{
+  "name": "backend-api",
+  "placement": { "mode": "smart" },
+  "d1_databases": [{ "binding": "DB", "database_id": "xxx" }]
+}
+```
+
+**Key takeaway:** Never enable Smart Placement on Workers that serve static assets with `run_worker_first = true`.
+
+## Local Development
+
+Smart Placement does NOT work in `wrangler dev` (local only). Test by deploying: `wrangler deploy --env staging`

package/skills/cloudflare/references/smart-placement/gotchas.md

@@ -0,0 +1,180 @@
+# Smart Placement Gotchas
+
+## Common Errors
+
+### "INSUFFICIENT_INVOCATIONS"
+
+**Cause:** Not enough traffic for Smart Placement to analyze
+**Solution:**
+
+- Ensure Worker receives consistent global traffic
+- Wait longer (analysis takes up to 15 minutes)
+- Send test traffic from multiple global locations
+- Check Worker has fetch event handler
+
+### "UNSUPPORTED_APPLICATION"
+
+**Cause:** Smart Placement made Worker slower rather than faster
+**Reasons:**
+
+- Worker doesn't make backend calls (runs faster at edge)
+- Backend calls are cached (network latency to user more important)
+- Backend service has good global distribution
+- Worker serves static assets or Pages content
+
+**Solutions:**
+
+- Disable Smart Placement: `{ "placement": { "mode": "off" } }`
+- Review whether Worker actually benefits from Smart Placement
+- Consider caching strategy to reduce backend calls
+- For Pages/Assets Workers, use separate backend Worker with Smart Placement
+
+### "No request duration metrics"
+
+**Cause:** Smart Placement not enabled, insufficient time passed, insufficient traffic, or analysis incomplete
+**Solution:**
+
+- Ensure Smart Placement enabled in config
+- Wait 15+ minutes after deployment
+- Verify Worker has sufficient traffic
+- Check `placement_status` is `SUCCESS`
+
+### "cf-placement header missing"
+
+**Cause:** Smart Placement not enabled, beta feature removed, or Worker not analyzed yet
+**Solution:** Verify Smart Placement enabled, wait for analysis (15min), check if beta feature still available
+
+## Pages/Assets + Smart Placement Performance Degradation
+
+**Problem:** Static assets load 2-5x slower when Smart Placement enabled with `run_worker_first = true`.
+
+**Cause:** Smart Placement routes ALL requests (including static assets like HTML, CSS, JS, images) to remote locations. Static content should ALWAYS be served from edge closest to user.
+
+**Solution:** Split into separate Workers OR disable Smart Placement:
+
+```jsonc
+// ❌ BAD - Assets routed away from user
+{
+  "name": "pages-app",
+  "placement": { "mode": "smart" },
+  "assets": { "run_worker_first": true }
+}
+
+// ✅ GOOD - Assets at edge, API optimized
+// frontend/wrangler.jsonc
+{
+  "name": "frontend",
+  "assets": { "run_worker_first": true }
+  // No placement field - stays at edge
+}
+
+// backend/wrangler.jsonc
+{
+  "name": "backend-api",
+  "placement": { "mode": "smart" }
+}
+```
+
+This is one of the most common and impactful Smart Placement misconfigurations.
+
+## Monolithic Full-Stack Worker
+
+**Problem:** Frontend and backend logic in single Worker with Smart Placement enabled.
+
+**Cause:** Smart Placement optimizes for backend latency but increases user-facing response time.
+
+**Solution:** Split into two Workers:
+
+```jsonc
+// frontend/wrangler.jsonc
+{
+  "name": "frontend",
+  "placement": { "mode": "off" },  // Explicit: stay at edge
+  "services": [{ "binding": "BACKEND", "service": "backend-api" }]
+}
+
+// backend/wrangler.jsonc
+{
+  "name": "backend-api",
+  "placement": { "mode": "smart" },
+  "d1_databases": [{ "binding": "DB", "database_id": "xxx" }]
+}
+```
+
+## Local Development Confusion
+
+**Issue:** Smart Placement doesn't work in `wrangler dev`.
+
+**Explanation:** Smart Placement only activates in production deployments, not local development.
+
+**Solution:** Test Smart Placement in staging environment: `wrangler deploy --env staging`
+
+## Baseline Traffic & Analysis Time
+
+**Note:** Smart Placement routes 1% of requests WITHOUT optimization for comparison (expected).
+
+**Analysis time:** Up to 15 minutes. During analysis, Worker runs at edge. Monitor `placement_status`.
+
+## RPC Methods Not Affected (Critical Limitation)
+
+**Problem:** Enabled Smart Placement on backend but RPC calls still slow.
+
+**Cause:** Smart Placement ONLY affects `fetch` handlers. RPC methods (Service Bindings with `WorkerEntrypoint`) are NEVER affected.
+
+**Why:** RPC bypasses `fetch` handler - Smart Placement can only route `fetch` requests.
+
+**Solution:** Convert to fetch-based Service Bindings:
+
+```typescript
+// ❌ RPC - Smart Placement has NO EFFECT
+export class BackendRPC extends WorkerEntrypoint {
+  async getData() {
+    // ALWAYS runs at edge
+    return await this.env.DATABASE.prepare('SELECT * FROM table').all()
+  }
+}
+
+// ✅ Fetch - Smart Placement WORKS
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // Runs close to DATABASE when Smart Placement enabled
+    const data = await env.DATABASE.prepare('SELECT * FROM table').all()
+    return Response.json(data)
+  },
+}
+```
+
+## Requirements
+
+- **Wrangler 2.20.0+** required
+- **Consistent multi-region traffic** needed for analysis
+- **Only affects fetch handlers** - RPC methods and named entrypoints not affected
+
+## Limits
+
+| Resource/Limit       | Value            | Notes                       |
+| -------------------- | ---------------- | --------------------------- |
+| Analysis time        | Up to 15 minutes | After enabling              |
+| Baseline traffic     | 1%               | Routed without optimization |
+| Min Wrangler version | 2.20.0+          | Required                    |
+| Traffic requirement  | Multi-region     | Consistent needed           |
+
+## Disabling Smart Placement
+
+```jsonc
+{ "placement": { "mode": "off" } } // Explicit disable
+// OR remove "placement" field entirely (same effect)
+```
+
+Both behaviors identical - Worker runs at edge closest to user.
+
+## When NOT to Use Smart Placement
+
+- Workers serving only static content or cached responses
+- Workers without significant backend communication
+- Pure edge logic (auth checks, redirects, simple transformations)
+- Workers without fetch event handlers
+- Pages/Assets Workers with `run_worker_first = true`
+- Workers using RPC methods instead of fetch handlers
+
+These scenarios won't benefit and may perform worse with Smart Placement.

package/skills/cloudflare/references/smart-placement/patterns.md

@@ -0,0 +1,190 @@
+# Smart Placement Patterns
+
+## Backend Worker with Database Access
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const user = await env.DATABASE.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first()
+    const orders = await env.DATABASE.prepare('SELECT * FROM orders WHERE user_id = ?')
+      .bind(userId)
+      .all()
+    return Response.json({ user, orders })
+  },
+}
+```
+
+```jsonc
+{
+  "placement": { "mode": "smart" },
+  "d1_databases": [{ "binding": "DATABASE", "database_id": "xxx" }],
+}
+```
+
+## Frontend + Backend Split (Service Bindings)
+
+**Frontend:** Runs at edge for fast user response
+**Backend:** Smart Placement runs close to database
+
+```typescript
+// Frontend Worker - routes requests to backend
+interface Env {
+  BACKEND: Fetcher // Service Binding to backend Worker
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    if (new URL(request.url).pathname.startsWith('/api/')) {
+      return env.BACKEND.fetch(request) // Forward to backend
+    }
+    return new Response('Frontend content')
+  },
+}
+
+// Backend Worker - database operations
+interface BackendEnv {
+  DATABASE: D1Database
+}
+
+export default {
+  async fetch(request: Request, env: BackendEnv): Promise<Response> {
+    const data = await env.DATABASE.prepare('SELECT * FROM table').all()
+    return Response.json(data)
+  },
+}
+```
+
+**CRITICAL:** Use fetch-based Service Bindings (shown above). If using RPC with `WorkerEntrypoint`, Smart Placement will NOT optimize those method calls - only `fetch` handlers are affected.
+
+**RPC vs Fetch - CRITICAL:** Smart Placement ONLY works with fetch-based bindings, NOT RPC.
+
+```typescript
+// ❌ RPC - Smart Placement has NO EFFECT on backend RPC methods
+export class BackendRPC extends WorkerEntrypoint {
+  async getData() {
+    // ALWAYS runs at edge, Smart Placement ignored
+    return await this.env.DATABASE.prepare('SELECT * FROM table').all()
+  }
+}
+
+// ✅ Fetch - Smart Placement WORKS
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // Runs close to DATABASE when Smart Placement enabled
+    const data = await env.DATABASE.prepare('SELECT * FROM table').all()
+    return Response.json(data)
+  },
+}
+```
+
+## External API Integration
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const apiUrl = 'https://api.partner.com'
+    const headers = { Authorization: `Bearer ${env.API_KEY}` }
+
+    const [profile, transactions] = await Promise.all([
+      fetch(`${apiUrl}/profile`, { headers }),
+      fetch(`${apiUrl}/transactions`, { headers }),
+    ])
+
+    return Response.json({
+      profile: await profile.json(),
+      transactions: await transactions.json(),
+    })
+  },
+}
+```
+
+## SSR / API Gateway Pattern
+
+```typescript
+// Frontend (edge) - auth/routing close to user
+export default {
+  async fetch(request: Request, env: Env) {
+    if (!request.headers.get('Authorization')) {
+      return new Response('Unauthorized', { status: 401 })
+    }
+    const data = await env.BACKEND.fetch(request)
+    return new Response(renderPage(await data.json()), {
+      headers: { 'Content-Type': 'text/html' },
+    })
+  },
+}
+
+// Backend (Smart Placement) - DB operations close to data
+export default {
+  async fetch(request: Request, env: Env) {
+    const data = await env.DATABASE.prepare('SELECT * FROM pages WHERE id = ?').bind(pageId).first()
+    return Response.json(data)
+  },
+}
+```
+
+## Durable Objects with Smart Placement
+
+**Key principle:** Smart Placement does NOT control WHERE Durable Objects run. DOs always run in their designated region (based on jurisdiction or smart location hints).
+
+**What Smart Placement DOES affect:** The location of the coordinator Worker's `fetch` handler that makes calls to multiple DOs.
+
+**Pattern:** Enable Smart Placement on coordinator Worker that aggregates data from multiple DOs:
+
+```typescript
+// Worker with Smart Placement - aggregates data from multiple DOs
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const userId = new URL(request.url).searchParams.get('user')
+
+    // Get DO stubs
+    const userDO = env.USER_DO.get(env.USER_DO.idFromName(userId))
+    const analyticsID = env.ANALYTICS_DO.idFromName(`analytics-${userId}`)
+    const analyticsDO = env.ANALYTICS_DO.get(analyticsID)
+
+    // Fetch from multiple DOs
+    const [userData, analyticsData] = await Promise.all([
+      userDO.fetch(new Request('https://do/profile')),
+      analyticsDO.fetch(new Request('https://do/stats')),
+    ])
+
+    return Response.json({
+      user: await userData.json(),
+      analytics: await analyticsData.json(),
+    })
+  },
+}
+```
+
+```jsonc
+// wrangler.jsonc
+{
+  "placement": { "mode": "smart" },
+  "durable_objects": {
+    "bindings": [
+      { "name": "USER_DO", "class_name": "UserDO" },
+      { "name": "ANALYTICS_DO", "class_name": "AnalyticsDO" },
+    ],
+  },
+}
+```
+
+**When this helps:**
+
+- Worker's `fetch` handler runs closer to DO regions, reducing network latency for multiple DO calls
+- Most beneficial when DOs are geographically concentrated or in specific jurisdictions
+- Helps when coordinator makes many sequential or parallel DO calls
+
+**When this DOESN'T help:**
+
+- DOs are globally distributed (no single optimal Worker location)
+- Worker only calls a single DO
+- DO calls are infrequent or cached
+
+## Best Practices
+
+- Split full-stack apps: frontend at edge, backend with Smart Placement
+- Use fetch-based Service Bindings (not RPC)
+- Enable for backend logic: APIs, data aggregation, DB operations
+- Don't enable for: static content, edge logic, RPC methods, Pages with `run_worker_first`
+- Wait 15+ min for analysis, verify `placement_status = SUCCESS`

package/skills/cloudflare/references/snippets/README.md

@@ -0,0 +1,74 @@
+# Cloudflare Snippets Skill Reference
+
+## Description
+
+Expert guidance for **Cloudflare Snippets ONLY** - a lightweight JavaScript-based edge logic platform for modifying HTTP requests and responses. Snippets run as part of the Ruleset Engine and are included at no additional cost on paid plans (Pro, Business, Enterprise).
+
+## What Are Snippets?
+
+Snippets are JavaScript functions executed at the edge as part of Cloudflare's Ruleset Engine. Key characteristics:
+
+- **Execution time**: 5ms CPU limit per request
+- **Size limit**: 32KB per snippet
+- **Runtime**: V8 isolate (subset of Workers APIs)
+- **Subrequests**: 2-5 fetch calls depending on plan
+- **Cost**: Included with Pro/Business/Enterprise plans
+
+## Snippets vs Workers Decision Matrix
+
+| Factor             | Choose Snippets If...                 | Choose Workers If...                            |
+| ------------------ | ------------------------------------- | ----------------------------------------------- |
+| **Complexity**     | Simple request/response modifications | Complex business logic, routing, middleware     |
+| **Execution time** | <5ms sufficient                       | Need >5ms or variable time                      |
+| **Subrequests**    | 2-5 fetch calls sufficient            | Need >5 subrequests or complex orchestration    |
+| **Code size**      | <32KB sufficient                      | Need >32KB or npm dependencies                  |
+| **Cost**           | Want zero additional cost             | Can afford $5/mo + usage                        |
+| **APIs**           | Need basic fetch, headers, URL        | Need KV, D1, R2, Durable Objects, cron triggers |
+| **Deployment**     | Need rule-based triggers              | Want custom routing logic                       |
+
+**Rule of thumb**: Use Snippets for modifications, Workers for applications.
+
+## Execution Model
+
+1. Request arrives at Cloudflare edge
+2. Ruleset Engine evaluates snippet rules (filter expressions)
+3. If rule matches, snippet executes within 5ms limit
+4. Modified request/response continues through pipeline
+5. Response returned to client
+
+Snippets execute synchronously in the request path - performance is critical.
+
+## Reading Order
+
+1. **[configuration.md](configuration.md)** - Start here: setup, deployment methods (Dashboard/API/Terraform)
+2. **[api.md](api.md)** - Core APIs: Request, Response, headers, `request.cf` properties
+3. **[patterns.md](patterns.md)** - Real-world examples: geo-routing, A/B tests, security headers
+4. **[gotchas.md](gotchas.md)** - Troubleshooting: common errors, performance tips, API limitations
+
+## In This Reference
+
+- **[configuration.md](configuration.md)** - Setup, deployment, configuration
+- **[api.md](api.md)** - API endpoints, methods, interfaces
+- **[patterns.md](patterns.md)** - Common patterns, use cases, examples
+- **[gotchas.md](gotchas.md)** - Troubleshooting, best practices, limitations
+
+## Quick Start
+
+```javascript
+// Snippet: Add security headers
+export default {
+  async fetch(request) {
+    const response = await fetch(request)
+    const newResponse = new Response(response.body, response)
+    newResponse.headers.set('X-Frame-Options', 'DENY')
+    newResponse.headers.set('X-Content-Type-Options', 'nosniff')
+    return newResponse
+  },
+}
+```
+
+Deploy via Dashboard (Rules → Snippets) or API/Terraform. See configuration.md for details.
+
+## See Also
+
+- [Cloudflare Docs](https://developers.cloudflare.com/rules/snippets/)