memory-journal-mcp 7.7.0 → 8.0.0

package/skills/cloudflare/references/workers-for-platforms/README.md

@@ -0,0 +1,95 @@
+# Cloudflare Workers for Platforms
+
+Multi-tenant platform with isolated customer code execution at scale.
+
+## Use Cases
+
+- Multi-tenant SaaS running customer code
+- AI-generated code execution in secure sandboxes
+- Programmable platforms with isolated compute
+- Edge functions/serverless platforms
+- Website builders with static + dynamic content
+- Unlimited app deployment at scale
+
+**NOT for general Workers** - only for Workers for Platforms architecture.
+
+## Quick Start
+
+**One-click deploy:** [Platform Starter Kit](https://github.com/cloudflare/workers-for-platforms-example) deploys complete WfP setup with dispatch namespace, dispatch worker, and user worker example.
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/workers-for-platforms-example)
+
+**Manual setup:** See [configuration.md](./configuration.md) for namespace creation and dispatch worker configuration.
+
+## Key Features
+
+- Unlimited Workers per namespace (no script limits)
+- Automatic tenant isolation
+- Custom CPU/subrequest limits per customer
+- Hostname routing (subdomains/vanity domains)
+- Egress/ingress control
+- Static assets support
+- Tags for bulk operations
+
+## Architecture
+
+**4 Components:**
+
+1. **Dispatch Namespace** - Container for unlimited customer Workers, automatic isolation (untrusted mode by default - no request.cf access, no shared cache)
+2. **Dynamic Dispatch Worker** - Entry point, routes requests, enforces platform logic (auth, limits, validation)
+3. **User Workers** - Customer code in isolated sandboxes, API-deployed, optional bindings (KV/D1/R2/DO)
+4. **Outbound Worker** (optional) - Intercepts external fetch, controls egress, logs subrequests (blocks TCP socket connect() API)
+
+**Request Flow:**
+
+```
+Request → Dispatch Worker → Determines user Worker → env.DISPATCHER.get("customer")
+→ User Worker executes (Outbound Worker for external fetch) → Response → Dispatch Worker → Client
+```
+
+## Decision Trees
+
+### When to Use Workers for Platforms
+
+```
+Need to run code?
+├─ Your code only → Regular Workers
+├─ Customer/AI code → Workers for Platforms
+└─ Untrusted code in sandbox → Workers for Platforms OR Sandbox API
+```
+
+### Routing Strategy Selection
+
+```
+Hostname routing needed?
+├─ Subdomains only (*.saas.com) → `*.saas.com/*` route + subdomain extraction
+├─ Custom domains → `*/*` wildcard + Cloudflare for SaaS + KV/metadata routing
+└─ Path-based (/customer/app) → Any route + path parsing
+```
+
+### Isolation Mode Selection
+
+```
+Worker mode?
+├─ Running customer code → Untrusted (default)
+├─ Need request.cf geolocation → Trusted mode
+├─ Internal platform, controlled code → Trusted mode with cache key prefixes
+└─ Maximum isolation → Untrusted + unique resources per customer
+```
+
+## In This Reference
+
+| File                                   | Purpose                                        | When to Read                       |
+| -------------------------------------- | ---------------------------------------------- | ---------------------------------- |
+| [configuration.md](./configuration.md) | Namespace setup, dispatch worker config        | First-time setup, changing limits  |
+| [api.md](./api.md)                     | User worker API, dispatch API, outbound worker | Deploying workers, SDK integration |
+| [patterns.md](./patterns.md)           | Multi-tenancy, routing, egress control         | Planning architecture, scaling     |
+| [gotchas.md](./gotchas.md)             | Limits, isolation issues, best practices       | Debugging, production prep         |
+
+## See Also
+
+- [workers](../workers/) - Core Workers runtime documentation
+- [durable-objects](../durable-objects/) - Stateful multi-tenant patterns
+- [sandbox](../sandbox/) - Alternative for untrusted code execution
+- [Reference Architecture: Programmable Platforms](https://developers.cloudflare.com/reference-architecture/diagrams/serverless/programmable-platforms/)
+- [Reference Architecture: AI Vibe Coding Platform](https://developers.cloudflare.com/reference-architecture/diagrams/ai/ai-vibe-coding-platform/)

package/skills/cloudflare/references/workers-for-platforms/api.md

@@ -0,0 +1,212 @@
+# API Operations
+
+## Deploy User Worker
+
+```bash
+curl -X PUT \
+  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE/scripts/$SCRIPT_NAME" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -F 'metadata={"main_module": "worker.mjs"};type=application/json' \
+  -F 'worker.mjs=@worker.mjs;type=application/javascript+module'
+```
+
+### TypeScript SDK
+
+```typescript
+import Cloudflare from 'cloudflare'
+
+const client = new Cloudflare({ apiToken: process.env.API_TOKEN })
+
+const scriptFile = new File([scriptContent], `${scriptName}.mjs`, {
+  type: 'application/javascript+module',
+})
+
+await client.workersForPlatforms.dispatch.namespaces.scripts.update(namespace, scriptName, {
+  account_id: accountId,
+  metadata: { main_module: `${scriptName}.mjs` },
+  files: [scriptFile],
+})
+```
+
+## TypeScript Types
+
+```typescript
+import type { DispatchNamespace } from '@cloudflare/workers-types'
+
+interface DispatchNamespace {
+  get(
+    name: string,
+    options?: Record<string, unknown>,
+    dispatchOptions?: DynamicDispatchOptions
+  ): Fetcher
+}
+
+interface DynamicDispatchOptions {
+  limits?: DynamicDispatchLimits
+  outbound?: Record<string, unknown>
+}
+
+interface DynamicDispatchLimits {
+  cpuMs?: number // Max CPU milliseconds
+  subRequests?: number // Max fetch() calls
+}
+
+// Usage
+const userWorker = env.DISPATCHER.get(
+  'customer-123',
+  {},
+  {
+    limits: { cpuMs: 50, subRequests: 20 },
+    outbound: { customerId: '123', url: request.url },
+  }
+)
+```
+
+## Deploy with Bindings
+
+```bash
+curl -X PUT ".../scripts/$SCRIPT_NAME" \
+  -F 'metadata={
+    "main_module": "worker.mjs",
+    "bindings": [
+      {"type": "kv_namespace", "name": "MY_KV", "namespace_id": "'$KV_ID'"}
+    ],
+    "tags": ["customer-123", "production"],
+    "compatibility_date": "2026-01-01"  // Use current date for new projects
+  };type=application/json' \
+  -F 'worker.mjs=@worker.mjs;type=application/javascript+module'
+```
+
+## List/Delete Workers
+
+```bash
+# List
+curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE/scripts" \
+  -H "Authorization: Bearer $API_TOKEN"
+
+# Delete by name
+curl -X DELETE ".../scripts/$SCRIPT_NAME" -H "Authorization: Bearer $API_TOKEN"
+
+# Delete by tag
+curl -X DELETE ".../scripts?tags=customer-123%3Ayes" -H "Authorization: Bearer $API_TOKEN"
+```
+
+**Pagination:** SDK supports async iteration. Manual: add `?per_page=100&page=1` query params.
+
+## Static Assets
+
+**3-step process:** Create session → Upload files → Deploy Worker
+
+### 1. Create Upload Session
+
+```bash
+curl -X POST ".../scripts/$SCRIPT_NAME/assets-upload-session" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -d '{
+    "manifest": {
+      "/index.html": {"hash": "08f1dfda4574284ab3c21666d1ee8c7d4", "size": 1234}
+    }
+  }'
+# Returns: jwt, buckets
+```
+
+**Hash:** SHA-256 truncated to first 16 bytes (32 hex characters)
+
+### 2. Upload Files
+
+```bash
+curl -X POST ".../workers/assets/upload?base64=true" \
+  -H "Authorization: Bearer $UPLOAD_JWT" \
+  -F '08f1dfda4574284ab3c21666d1ee8c7d4=<BASE64_CONTENT>'
+# Returns: completion jwt
+```
+
+**Multiple buckets:** Upload to all returned bucket URLs (typically 2 for redundancy) using same JWT and hash.
+
+### 3. Deploy with Assets
+
+```bash
+curl -X PUT ".../scripts/$SCRIPT_NAME" \
+  -F 'metadata={
+    "main_module": "index.js",
+    "assets": {"jwt": "<COMPLETION_TOKEN>"},
+    "bindings": [{"type": "assets", "name": "ASSETS"}]
+  };type=application/json' \
+  -F 'index.js=export default {...};type=application/javascript+module'
+```
+
+**Asset Isolation:** Assets shared across namespace by default. For customer isolation, salt hash: `sha256(customerId + fileContents).slice(0, 32)`
+
+## Dispatch Workers
+
+### Subdomain Routing
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const userWorkerName = new URL(request.url).hostname.split('.')[0]
+    const userWorker = env.DISPATCHER.get(userWorkerName)
+    return await userWorker.fetch(request)
+  },
+}
+```
+
+### Path Routing
+
+```typescript
+const pathParts = new URL(request.url).pathname.split('/').filter(Boolean)
+const userWorker = env.DISPATCHER.get(pathParts[0])
+return await userWorker.fetch(request)
+```
+
+### KV Routing
+
+```typescript
+const hostname = new URL(request.url).hostname
+const userWorkerName = await env.ROUTING_KV.get(hostname)
+const userWorker = env.DISPATCHER.get(userWorkerName)
+return await userWorker.fetch(request)
+```
+
+## Outbound Workers
+
+Control external fetch from user Workers:
+
+### Configure
+
+```typescript
+const userWorker = env.DISPATCHER.get(
+  workerName,
+  {},
+  { outbound: { customer_context: { customer_name: workerName, url: request.url } } }
+)
+```
+
+### Implement
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const customerName = env.customer_name
+    const url = new URL(request.url)
+
+    // Block domains
+    if (['malicious.com'].some((d) => url.hostname.includes(d))) {
+      return new Response('Blocked', { status: 403 })
+    }
+
+    // Inject auth
+    if (url.hostname === 'api.example.com') {
+      const headers = new Headers(request.headers)
+      headers.set('Authorization', `Bearer ${generateJWT(customerName)}`)
+      return fetch(new Request(request, { headers }))
+    }
+
+    return fetch(request)
+  },
+}
+```
+
+**Note:** Doesn't intercept DO/mTLS fetch.
+
+See [README.md](./README.md), [configuration.md](./configuration.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)

package/skills/cloudflare/references/workers-for-platforms/configuration.md

@@ -0,0 +1,178 @@
+# Configuration
+
+## Dispatch Namespace Binding
+
+### wrangler.jsonc
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "dispatch_namespaces": [
+    {
+      "binding": "DISPATCHER",
+      "namespace": "production",
+    },
+  ],
+}
+```
+
+## Worker Isolation Mode
+
+Workers in a namespace run in **untrusted mode** by default for security:
+
+- No access to `request.cf` object
+- Isolated cache per Worker (no shared cache)
+- `caches.default` disabled
+
+### Enable Trusted Mode
+
+For internal platforms where you control all code:
+
+```bash
+curl -X PUT \
+  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -d '{"name": "'$NAMESPACE'", "trusted_workers": true}'
+```
+
+**Caveats:**
+
+- Workers share cache within namespace (use cache key prefixes: `customer-${id}:${key}`)
+- `request.cf` object accessible
+- Redeploy existing Workers after enabling trusted mode
+
+**When to use:** Internal platforms, A/B testing platforms, need geolocation data
+
+### With Outbound Worker
+
+```jsonc
+{
+  "dispatch_namespaces": [
+    {
+      "binding": "DISPATCHER",
+      "namespace": "production",
+      "outbound": {
+        "service": "outbound-worker",
+        "parameters": ["customer_context"],
+      },
+    },
+  ],
+}
+```
+
+## Wrangler Commands
+
+```bash
+wrangler dispatch-namespace list
+wrangler dispatch-namespace get production
+wrangler dispatch-namespace create production
+wrangler dispatch-namespace delete staging
+wrangler dispatch-namespace rename old new
+```
+
+## Custom Limits
+
+Set CPU time and subrequest limits per invocation:
+
+```typescript
+const userWorker = env.DISPATCHER.get(
+  workerName,
+  {},
+  {
+    limits: {
+      cpuMs: 10, // Max CPU ms
+      subRequests: 5, // Max fetch() calls
+    },
+  }
+)
+```
+
+Handle limit violations:
+
+```typescript
+try {
+  return await userWorker.fetch(request)
+} catch (e) {
+  if (e.message.includes('CPU time limit')) {
+    return new Response('CPU limit exceeded', { status: 429 })
+  }
+  throw e
+}
+```
+
+## Static Assets
+
+Deploy HTML/CSS/images with Workers. See [api.md](./api.md#static-assets) for upload process.
+
+### Wrangler
+
+```jsonc
+{
+  "name": "customer-site",
+  "main": "./src/index.js",
+  "assets": {
+    "directory": "./public",
+    "binding": "ASSETS",
+  },
+}
+```
+
+```bash
+npx wrangler deploy --name customer-site --dispatch-namespace production
+```
+
+### Dashboard Deployment
+
+Alternative to CLI:
+
+1. Upload Worker file in dashboard
+2. Add `--dispatch-namespace` flag: `wrangler deploy --dispatch-namespace production`
+3. Or configure in wrangler.jsonc under `dispatch_namespaces`
+
+See [api.md](./api.md) for programmatic deployment via REST API or SDK.
+
+## Tags
+
+Organize/search Workers (max 8/script):
+
+```bash
+# Set tags
+curl -X PUT ".../tags" -d '["customer-123", "pro", "production"]'
+
+# Filter by tag
+curl ".../scripts?tags=production%3Ayes"
+
+# Delete by tag
+curl -X DELETE ".../scripts?tags=customer-123%3Ayes"
+```
+
+Common patterns: `customer-123`, `free|pro|enterprise`, `production|staging`
+
+## Bindings
+
+**Supported binding types:** 29 total including KV, D1, R2, Durable Objects, Analytics Engine, Service, Assets, Queue, Vectorize, Hyperdrive, Workflow, AI, Browser, and more.
+
+Add via API metadata (see [api.md](./api.md#deploy-with-bindings)):
+
+```json
+{
+  "bindings": [
+    { "type": "kv_namespace", "name": "USER_KV", "namespace_id": "..." },
+    { "type": "r2_bucket", "name": "STORAGE", "bucket_name": "..." },
+    { "type": "d1", "name": "DB", "id": "..." }
+  ]
+}
+```
+
+Preserve existing bindings:
+
+```json
+{
+  "bindings": [{ "type": "r2_bucket", "name": "STORAGE", "bucket_name": "new" }],
+  "keep_bindings": ["kv_namespace", "d1"] // Preserves existing bindings of these types
+}
+```
+
+For complete binding type reference, see [bindings](../bindings/) documentation
+
+See [README.md](./README.md), [api.md](./api.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)

package/skills/cloudflare/references/workers-for-platforms/gotchas.md

@@ -0,0 +1,134 @@
+# Gotchas & Limits
+
+## Common Errors
+
+### "Worker not found"
+
+**Cause:** Attempting to get Worker that doesn't exist in namespace  
+**Solution:** Catch error and return 404:
+
+```typescript
+try {
+  const userWorker = env.DISPATCHER.get(workerName)
+  return userWorker.fetch(request)
+} catch (e) {
+  if (e.message.startsWith('Worker not found')) {
+    return new Response('Worker not found', { status: 404 })
+  }
+  throw e // Re-throw unexpected errors
+}
+```
+
+### "CPU time limit exceeded"
+
+**Cause:** User Worker exceeded configured CPU time limit  
+**Solution:** Track violations in Analytics Engine and return 429 response; consider adjusting limits per customer tier
+
+### "Hostname Routing Issues"
+
+**Cause:** DNS proxy settings causing routing problems  
+**Solution:** Use `*/*` wildcard route which works regardless of proxy settings for orange-to-orange routing
+
+### "Bindings Lost on Update"
+
+**Cause:** Not using `keep_bindings` flag when updating Worker  
+**Solution:** Use `keep_bindings: true` in API requests to preserve existing bindings during updates
+
+### "Tag Filtering Not Working"
+
+**Cause:** Special characters not URL encoded in tag filters  
+**Solution:** URL encode tags (e.g., `tags=production%3Ayes`) and avoid special chars like `,` and `&`
+
+### "Deploy Failures with ES Modules"
+
+**Cause:** Incorrect upload format for ES modules  
+**Solution:** Use multipart form upload, specify `main_module` in metadata, and set file type to `application/javascript+module`
+
+### "Static Asset Upload Failed"
+
+**Cause:** Invalid hash format, expired token, or incorrect encoding  
+**Solution:** Hash must be first 16 bytes (32 hex chars) of SHA-256, upload within 1 hour of session creation, deploy within 1 hour of upload completion, and Base64 encode file contents
+
+### "Outbound Worker Not Intercepting Calls"
+
+**Cause:** Outbound Workers don't intercept Durable Object or mTLS binding fetch  
+**Solution:** Plan egress control accordingly; not all fetch calls are intercepted
+
+### "TCP Socket Connection Failed"
+
+**Cause:** Outbound Worker enabled blocks `connect()` API for TCP sockets  
+**Solution:** Outbound Workers only intercept `fetch()` calls; TCP socket connections unavailable when outbound configured. Remove outbound if TCP needed, or use proxy pattern.
+
+### "API Rate Limit Exceeded"
+
+**Cause:** Exceeded Cloudflare API rate limits (1200 requests per 5 minutes per account, 200 requests per second per IP)  
+**Solution:** Implement exponential backoff:
+
+```typescript
+async function deployWithBackoff(deploy: () => Promise<void>, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await deploy()
+    } catch (e) {
+      if (e.status === 429 && i < maxRetries - 1) {
+        await new Promise((r) => setTimeout(r, Math.pow(2, i) * 1000))
+        continue
+      }
+      throw e
+    }
+  }
+}
+```
+
+### "Gradual Deployment Not Supported"
+
+**Cause:** Attempted to use gradual deployments with user Workers  
+**Solution:** Gradual deployments not supported for Workers in dispatch namespaces. Use all-at-once deployment with staged rollout via dispatch worker logic (feature flags, percentage-based routing).
+
+### "Asset Session Expired"
+
+**Cause:** Upload JWT expired (1 hour validity) or completion token expired (1 hour after upload)  
+**Solution:** Complete asset upload within 1 hour of session creation, and deploy Worker within 1 hour of upload completion. For large uploads, batch files or increase upload parallelism.
+
+## Platform Limits
+
+| Limit                     | Value                  | Notes                                      |
+| ------------------------- | ---------------------- | ------------------------------------------ |
+| Workers per namespace     | Unlimited              | Unlike regular Workers (500 per account)   |
+| Namespaces per account    | Unlimited              | Best practice: 1 production + 1 staging    |
+| Max tags per Worker       | 8                      | For filtering and organization             |
+| Worker mode               | Untrusted (default)    | No `request.cf` access unless trusted mode |
+| Cache isolation           | Per-Worker (untrusted) | Shared in trusted mode with key prefixes   |
+| Durable Object namespaces | Unlimited              | No per-account limit for WfP               |
+| Gradual Deployments       | Not supported          | All-at-once only                           |
+| `caches.default`          | Disabled (untrusted)   | Use Cache API with custom keys             |
+
+## Asset Upload Limits
+
+| Limit                       | Value                  | Notes                                     |
+| --------------------------- | ---------------------- | ----------------------------------------- |
+| Upload session JWT validity | 1 hour                 | Must complete upload within this time     |
+| Completion token validity   | 1 hour                 | Must deploy within this time after upload |
+| Asset hash format           | First 16 bytes SHA-256 | 32 hex characters                         |
+| Base64 encoding             | Required               | For binary files                          |
+
+## API Rate Limits
+
+| Limit Type | Value                 | Scope            |
+| ---------- | --------------------- | ---------------- |
+| Client API | 1200 requests / 5 min | Per account      |
+| Client API | 200 requests / sec    | Per IP address   |
+| GraphQL    | Varies by query cost  | Query complexity |
+
+See [Cloudflare API Rate Limits](https://developers.cloudflare.com/fundamentals/api/reference/limits/) for details.
+
+## Operational Limits
+
+| Operation                   | Limit                       | Notes                                 |
+| --------------------------- | --------------------------- | ------------------------------------- |
+| CPU time (custom limits)    | Up to Workers plan limit    | Set per-invocation in dispatch worker |
+| Subrequests (custom limits) | Up to Workers plan limit    | Set per-invocation in dispatch worker |
+| Outbound Worker subrequests | Not intercepted for DO/mTLS | Only regular fetch() calls            |
+| TCP sockets with outbound   | Disabled                    | `connect()` API unavailable           |
+
+See [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md)