memory-journal-mcp 7.7.1 → 8.0.0

package/skills/cloudflare/references/secrets-store/gotchas.md

@@ -0,0 +1,97 @@
+# Gotchas
+
+## Common Errors
+
+### ".get() Throws on Error"
+
+**Cause:** Assuming `.get()` returns null on failure instead of throwing  
+**Solution:** Always wrap `.get()` calls in try/catch blocks to handle errors gracefully
+
+```typescript
+try {
+  const key = await env.API_KEY.get()
+} catch (error) {
+  return new Response('Configuration error', { status: 500 })
+}
+```
+
+### "Logging Secret Values"
+
+**Cause:** Accidentally logging secret values in console or error messages  
+**Solution:** Only log metadata (e.g., "Retrieved API_KEY") never the actual secret value
+
+### "Module-Level Secret Access"
+
+**Cause:** Attempting to access secrets during module initialization before env is available  
+**Solution:** Cache secrets in request scope only, not at module level
+
+### "Secret not found in store"
+
+**Cause:** Secret name doesn't exist, case mismatch, missing workers scope, or incorrect store_id  
+**Solution:** Verify secret exists with `wrangler secrets-store secret list <store-id> --remote`, check name matches exactly (case-sensitive), ensure secret has `workers` scope, and verify correct store_id
+
+### "Scope Mismatch"
+
+**Cause:** Secret exists but missing `workers` scope (only has `ai-gateway` scope)  
+**Solution:** Update secret scopes: `wrangler secrets-store secret update <store-id> --name SECRET --scopes workers --remote` or add via Dashboard
+
+### "JSON Parsing Failure"
+
+**Cause:** Storing invalid JSON in secret, then failing to parse during runtime  
+**Solution:** Validate JSON before storing:
+
+```bash
+# Validate before storing
+echo '{"key":"value"}' | jq . && \
+  echo '{"key":"value"}' | wrangler secrets-store secret create <store-id> \
+    --name CONFIG --scopes workers --remote
+```
+
+Runtime parsing with error handling:
+
+```typescript
+try {
+  const configStr = await env.CONFIG.get()
+  const config = JSON.parse(configStr)
+} catch (error) {
+  console.error('Invalid config JSON:', error)
+  return new Response('Invalid configuration', { status: 500 })
+}
+```
+
+### "Cannot access secret in local dev"
+
+**Cause:** Attempting to access production secrets in local development environment  
+**Solution:** Create local-only secrets (without `--remote` flag) for development: `wrangler secrets-store secret create <store-id> --name API_KEY --scopes workers`
+
+### "Property 'get' does not exist"
+
+**Cause:** Missing TypeScript type definition for secret binding  
+**Solution:** Define interface with get method: `interface Env { API_KEY: { get(): Promise<string> }; }`
+
+### "Binding already exists"
+
+**Cause:** Duplicate binding in dashboard or conflict between wrangler.jsonc and dashboard  
+**Solution:** Remove duplicate from dashboard Settings → Bindings, check for conflicts, or delete old Worker secret with `wrangler secret delete API_KEY`
+
+### "Account secret quota exceeded"
+
+**Cause:** Account has reached 100 secret limit (beta)  
+**Solution:** Check quota with `wrangler secrets-store quota --remote`, delete unused secrets, consolidate duplicates, or contact Cloudflare for increase
+
+## Limits
+
+| Limit                   | Value                       | Notes                                 |
+| ----------------------- | --------------------------- | ------------------------------------- |
+| Max secrets per account | 100                         | Beta limit                            |
+| Max stores per account  | 1                           | Beta limit                            |
+| Max secret size         | 1024 bytes                  | Per secret                            |
+| Local secrets           | Don't count toward limit    | Only production secrets count         |
+| Scopes available        | `workers`, `ai-gateway`     | Must have correct scope for access    |
+| Scope                   | Account-level               | Can be reused across multiple Workers |
+| Access method           | `await env.BINDING.get()`   | Async only, throws on error           |
+| Management              | Centralized                 | Via secrets-store commands            |
+| Local dev               | Separate local secrets      | Use without `--remote` flag           |
+| Regional availability   | Global except China Network | Unavailable in China Network          |
+
+See: [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md)

package/skills/cloudflare/references/secrets-store/patterns.md

@@ -0,0 +1,218 @@
+# Patterns
+
+## Secret Rotation
+
+Zero-downtime rotation with versioned naming (`api_key_v1`, `api_key_v2`):
+
+```typescript
+interface Env {
+  PRIMARY_KEY: { get(): Promise<string> }
+  FALLBACK_KEY?: { get(): Promise<string> }
+}
+
+async function fetchWithAuth(url: string, key: string) {
+  return fetch(url, { headers: { Authorization: `Bearer ${key}` } })
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    let resp = await fetchWithAuth('https://api.example.com', await env.PRIMARY_KEY.get())
+
+    // Fallback during rotation
+    if (!resp.ok && env.FALLBACK_KEY) {
+      resp = await fetchWithAuth('https://api.example.com', await env.FALLBACK_KEY.get())
+    }
+
+    return resp
+  },
+}
+```
+
+Workflow: Create `api_key_v2` → add fallback binding → deploy → swap primary → deploy → remove `v1`
+
+## Encryption with KV
+
+```typescript
+interface Env {
+  CACHE: KVNamespace
+  ENCRYPTION_KEY: { get(): Promise<string> }
+}
+
+async function encryptValue(value: string, key: string): Promise<string> {
+  const enc = new TextEncoder()
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw',
+    enc.encode(key),
+    { name: 'AES-GCM' },
+    false,
+    ['encrypt']
+  )
+  const iv = crypto.getRandomValues(new Uint8Array(12))
+  const encrypted = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    keyMaterial,
+    enc.encode(value)
+  )
+
+  const combined = new Uint8Array(iv.length + encrypted.byteLength)
+  combined.set(iv)
+  combined.set(new Uint8Array(encrypted), iv.length)
+  return btoa(String.fromCharCode(...combined))
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const key = await env.ENCRYPTION_KEY.get()
+    const encrypted = await encryptValue('sensitive-data', key)
+    await env.CACHE.put('user:123:data', encrypted)
+    return Response.json({ ok: true })
+  },
+}
+```
+
+## HMAC Signing
+
+```typescript
+interface Env {
+  HMAC_SECRET: { get(): Promise<string> }
+}
+
+async function signRequest(data: string, secret: string): Promise<string> {
+  const enc = new TextEncoder()
+  const key = await crypto.subtle.importKey(
+    'raw',
+    enc.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign']
+  )
+  const sig = await crypto.subtle.sign('HMAC', key, enc.encode(data))
+  return btoa(String.fromCharCode(...new Uint8Array(sig)))
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const secret = await env.HMAC_SECRET.get()
+    const payload = await request.text()
+    const signature = await signRequest(payload, secret)
+    return Response.json({ signature })
+  },
+}
+```
+
+## Audit & Monitoring
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    const startTime = Date.now()
+    try {
+      const apiKey = await env.API_KEY.get()
+      const resp = await fetch('https://api.example.com', {
+        headers: { Authorization: `Bearer ${apiKey}` },
+      })
+
+      ctx.waitUntil(
+        fetch('https://log.example.com/log', {
+          method: 'POST',
+          body: JSON.stringify({
+            event: 'secret_used',
+            secret_name: 'API_KEY',
+            timestamp: new Date().toISOString(),
+            duration_ms: Date.now() - startTime,
+            success: resp.ok,
+          }),
+        })
+      )
+      return resp
+    } catch (error) {
+      ctx.waitUntil(
+        fetch('https://log.example.com/log', {
+          method: 'POST',
+          body: JSON.stringify({
+            event: 'secret_access_failed',
+            secret_name: 'API_KEY',
+            error: error instanceof Error ? error.message : 'Unknown',
+          }),
+        })
+      )
+      return new Response('Error', { status: 500 })
+    }
+  },
+}
+```
+
+## Migration from Worker Secrets
+
+Change `env.SECRET` (direct) to `await env.SECRET.get()` (async).
+
+Steps:
+
+1. Create in Secrets Store: `wrangler secrets-store secret create <store-id> --name API_KEY --scopes workers --remote`
+2. Add binding to `wrangler.jsonc`: `{"binding": "API_KEY", "store_id": "abc123", "secret_name": "api_key"}`
+3. Update code: `const key = await env.API_KEY.get();`
+4. Test staging, deploy
+5. Remove old: `wrangler secret delete API_KEY`
+
+## Sharing Across Workers
+
+Same secret, different binding names:
+
+```jsonc
+// worker-1: binding="SHARED_DB", secret_name="postgres_url"
+// worker-2: binding="DB_CONN", secret_name="postgres_url"
+```
+
+## JSON Secret Parsing
+
+Store structured config as JSON secrets:
+
+```typescript
+interface Env {
+  DB_CONFIG: { get(): Promise<string> }
+}
+
+interface DbConfig {
+  host: string
+  port: number
+  username: string
+  password: string
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    try {
+      const configStr = await env.DB_CONFIG.get()
+      const config: DbConfig = JSON.parse(configStr)
+
+      // Use parsed config
+      const dbUrl = `postgres://${config.username}:${config.password}@${config.host}:${config.port}`
+
+      return Response.json({ connected: true })
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        return new Response('Invalid config JSON', { status: 500 })
+      }
+      throw error
+    }
+  },
+}
+```
+
+Store JSON secret:
+
+```bash
+echo '{"host":"db.example.com","port":5432,"username":"app","password":"secret"}' | \
+  wrangler secrets-store secret create <store-id> \
+    --name DB_CONFIG --scopes workers --remote
+```
+
+## Integration
+
+### Service Bindings
+
+Auth Worker signs JWT with Secrets Store; API Worker verifies via service binding.
+
+See: [workers](../workers/) for service binding patterns.
+
+See: [api.md](./api.md), [gotchas.md](./gotchas.md)

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

@@ -0,0 +1,143 @@
+# Cloudflare Workers Smart Placement
+
+Automatic workload placement optimization to minimize latency by running Workers closer to backend infrastructure rather than end users.
+
+## Core Concept
+
+Smart Placement automatically analyzes Worker request duration across Cloudflare's global network and intelligently routes requests to optimal data center locations. Instead of defaulting to the location closest to the end user, Smart Placement can forward requests to locations closer to backend infrastructure when this reduces overall request duration.
+
+### When to Use
+
+**Enable Smart Placement when:**
+
+- Worker makes multiple round trips to backend services/databases
+- Backend infrastructure is geographically concentrated
+- Request duration dominated by backend latency rather than network latency from user
+- Running backend logic in Workers (APIs, data aggregation, SSR with DB calls)
+- Worker uses `fetch` handler (not RPC methods)
+
+**Do NOT enable for:**
+
+- 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
+- Workers with RPC methods or named entrypoints (only `fetch` handlers are affected)
+- Pages/Assets Workers with `run_worker_first = true` (degrades asset serving)
+
+### Decision Tree
+
+```
+Does your Worker have a fetch handler?
+├─ No → Smart Placement won't work (skip)
+└─ Yes
+   │
+   Does it make multiple backend calls (DB/API)?
+   ├─ No → Don't enable (won't help)
+   └─ Yes
+      │
+      Is backend geographically concentrated?
+      ├─ No (globally distributed) → Probably won't help
+      └─ Yes or uncertain
+         │
+         Does it serve static assets with run_worker_first=true?
+         ├─ Yes → Don't enable (will hurt performance)
+         └─ No → Enable Smart Placement
+            │
+            After 15min, check placement_status
+            ├─ SUCCESS → Monitor metrics
+            ├─ INSUFFICIENT_INVOCATIONS → Need more traffic
+            └─ UNSUPPORTED_APPLICATION → Disable (hurting performance)
+```
+
+### Key Architecture Pattern
+
+**Recommended:** Split full-stack applications into separate Workers:
+
+```
+User → Frontend Worker (at edge, close to user)
+         ↓ Service Binding
+       Backend Worker (Smart Placement enabled, close to DB/API)
+         ↓
+       Database/Backend Service
+```
+
+This maintains fast, reactive frontends while optimizing backend latency.
+
+## Quick Start
+
+```jsonc
+// wrangler.jsonc
+{
+  "placement": {
+    "mode": "smart", // or "off" to explicitly disable
+  },
+}
+```
+
+Deploy and wait 15 minutes for analysis. Check status via API or dashboard metrics.
+
+**To disable:** Set `"mode": "off"` or remove `placement` field entirely (both equivalent).
+
+## Requirements
+
+- Wrangler 2.20.0+
+- Analysis time: Up to 15 minutes after enabling
+- Traffic requirements: Consistent traffic from multiple global locations
+- Available on all Workers plans (Free, Paid, Enterprise)
+
+## Placement Status Values
+
+```typescript
+type PlacementStatus =
+  | undefined // Not yet analyzed
+  | 'SUCCESS' // Successfully optimized
+  | 'INSUFFICIENT_INVOCATIONS' // Not enough traffic
+  | 'UNSUPPORTED_APPLICATION' // Made Worker slower (reverted)
+```
+
+## CLI Commands
+
+```bash
+# Deploy with Smart Placement
+wrangler deploy
+
+# Check placement status
+curl -H "Authorization: Bearer $TOKEN" \
+  https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/services/$WORKER_NAME \
+  | jq .result.placement_status
+
+# Monitor
+wrangler tail your-worker-name --header cf-placement
+```
+
+## Reading Order
+
+**First time?** Start here:
+
+1. This README - understand core concepts and when to use Smart Placement
+2. [configuration.md](./configuration.md) - set up wrangler.jsonc and understand limitations
+3. [patterns.md](./patterns.md) - see practical examples for your use case
+4. [api.md](./api.md) - monitor and verify Smart Placement is working
+5. [gotchas.md](./gotchas.md) - troubleshoot common issues
+
+**Quick lookup:**
+
+- "Should I enable Smart Placement?" → See "When to Use" above
+- "How do I configure it?" → [configuration.md](./configuration.md)
+- "How do I split frontend/backend?" → [patterns.md](./patterns.md)
+- "Why isn't it working?" → [gotchas.md](./gotchas.md)
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc setup, mode values, validation rules
+- [api.md](./api.md) - Placement Status API, cf-placement header, monitoring
+- [patterns.md](./patterns.md) - Frontend/backend split, database workers, SSR patterns
+- [gotchas.md](./gotchas.md) - Troubleshooting INSUFFICIENT_INVOCATIONS, performance issues
+
+## See Also
+
+- [workers](../workers/) - Worker runtime and fetch handlers
+- [d1](../d1/) - D1 database that benefits from Smart Placement
+- [durable-objects](../durable-objects/) - Durable Objects with backend logic
+- [bindings](../bindings/) - Service bindings for frontend/backend split

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

@@ -0,0 +1,192 @@
+# Smart Placement API
+
+## Placement Status API
+
+Query Worker placement status via Cloudflare API:
+
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/workers/services/{WORKER_NAME}" \
+  -H "Authorization: Bearer <TOKEN>" \
+  -H "Content-Type: application/json"
+```
+
+Response includes `placement_status` field:
+
+```typescript
+type PlacementStatus =
+  | undefined // Not yet analyzed
+  | 'SUCCESS' // Successfully optimized
+  | 'INSUFFICIENT_INVOCATIONS' // Not enough traffic
+  | 'UNSUPPORTED_APPLICATION' // Made Worker slower (reverted)
+```
+
+## Status Meanings
+
+**`undefined` (not present)**
+
+- Worker not yet analyzed
+- Always runs at default edge location closest to user
+
+**`SUCCESS`**
+
+- Analysis complete, Smart Placement active
+- Worker runs in optimal location (may be edge or remote)
+
+**`INSUFFICIENT_INVOCATIONS`**
+
+- Not enough requests to make placement decision
+- Requires consistent multi-region traffic
+- Always runs at default edge location
+
+**`UNSUPPORTED_APPLICATION`** (rare, <1% of Workers)
+
+- Smart Placement made Worker slower
+- Placement decision reverted
+- Always runs at edge location
+- Won't be re-analyzed until redeployed
+
+## cf-placement Header (Beta)
+
+Smart Placement adds response header indicating routing decision:
+
+```typescript
+// Remote placement (Smart Placement routed request)
+'cf-placement: remote-LHR' // Routed to London
+
+// Local placement (default edge routing)
+'cf-placement: local-EWR' // Stayed at Newark edge
+```
+
+Format: `{placement-type}-{IATA-code}`
+
+- `remote-*` = Smart Placement routed to remote location
+- `local-*` = Stayed at default edge location
+- IATA code = nearest airport to data center
+
+**Warning:** Beta feature, may be removed before GA.
+
+## Detecting Smart Placement in Code
+
+**Note:** `cf-placement` header is a beta feature and may change or be removed.
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const placementHeader = request.headers.get('cf-placement')
+
+    if (placementHeader?.startsWith('remote-')) {
+      const location = placementHeader.split('-')[1]
+      console.log(`Smart Placement routed to ${location}`)
+    } else if (placementHeader?.startsWith('local-')) {
+      const location = placementHeader.split('-')[1]
+      console.log(`Running at edge location ${location}`)
+    }
+
+    return new Response('OK')
+  },
+} satisfies ExportedHandler<Env>
+```
+
+## Request Duration Metrics
+
+Available in Cloudflare dashboard when Smart Placement enabled:
+
+**Workers & Pages → [Your Worker] → Metrics → Request Duration**
+
+Shows histogram comparing:
+
+- Request duration WITH Smart Placement (99% of traffic)
+- Request duration WITHOUT Smart Placement (1% baseline)
+
+**Request Duration vs Execution Duration:**
+
+- **Request duration:** Total time from request arrival to response delivery (includes network latency)
+- **Execution duration:** Time Worker code actively executing (excludes network waits)
+
+Use request duration to measure Smart Placement impact.
+
+### Interpreting Metrics
+
+| Metric Comparison | Interpretation          | Action                               |
+| ----------------- | ----------------------- | ------------------------------------ |
+| WITH < WITHOUT    | Smart Placement helping | Keep enabled                         |
+| WITH ≈ WITHOUT    | Neutral impact          | Consider disabling to free resources |
+| WITH > WITHOUT    | Smart Placement hurting | Disable with `mode: "off"`           |
+
+**Why Smart Placement might hurt performance:**
+
+- Worker primarily serves static assets or cached content
+- Backend services are globally distributed (no single optimal location)
+- Worker has minimal backend communication
+- Using Pages with `assets.run_worker_first = true`
+
+**Typical improvements when Smart Placement helps:**
+
+- 20-50% reduction in request duration for database-heavy Workers
+- 30-60% reduction for Workers making multiple backend API calls
+- Larger improvements when backend is geographically concentrated
+
+## Monitoring Commands
+
+```bash
+# Tail Worker logs
+wrangler tail your-worker-name
+
+# Tail with filters
+wrangler tail your-worker-name --status error
+wrangler tail your-worker-name --header cf-placement
+
+# Check placement status via API
+curl -H "Authorization: Bearer $TOKEN" \
+  https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/services/$WORKER_NAME \
+  | jq .result.placement_status
+```
+
+## TypeScript Types
+
+```typescript
+// Placement status returned by API (field may be absent)
+type PlacementStatus =
+  | 'SUCCESS'
+  | 'INSUFFICIENT_INVOCATIONS'
+  | 'UNSUPPORTED_APPLICATION'
+  | undefined
+
+// Placement configuration in wrangler.jsonc
+type PlacementMode = 'smart' | 'off'
+
+interface PlacementConfig {
+  mode: PlacementMode
+  // Legacy fields (deprecated/removed):
+  // hint?: string;  // REMOVED - no longer supported
+}
+
+// Explicit placement (separate feature from Smart Placement)
+interface ExplicitPlacementConfig {
+  region?: string
+  host?: string
+  hostname?: string
+  // Cannot combine with mode field
+}
+
+// Worker metadata from API response
+interface WorkerMetadata {
+  placement?: PlacementConfig | ExplicitPlacementConfig
+  placement_status?: PlacementStatus
+}
+
+// Service Binding for backend Worker
+interface Env {
+  BACKEND_SERVICE: Fetcher // Service Binding to backend Worker
+  DATABASE: D1Database
+}
+
+// Example Worker with Service Binding
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // Forward to backend Worker with Smart Placement enabled
+    const response = await env.BACKEND_SERVICE.fetch(request)
+    return response
+  },
+} satisfies ExportedHandler<Env>
+```