memory-journal-mcp 7.7.1 → 8.0.1

package/skills/cloudflare/references/workers-vpc/gotchas.md

@@ -0,0 +1,171 @@
+# Gotchas and Troubleshooting
+
+Common pitfalls, limitations, and solutions for TCP Sockets in Cloudflare Workers.
+
+## Platform Limits
+
+### Connection Limits
+
+| Limit                              | Value                          |
+| ---------------------------------- | ------------------------------ |
+| Max concurrent sockets per request | 6 (hard limit)                 |
+| Socket lifetime                    | Request duration               |
+| Connection timeout                 | Platform-dependent, no setting |
+
+**Problem:** Exceeding 6 connections throws error
+
+**Solution:** Process in batches of 6
+
+```typescript
+for (let i = 0; i < hosts.length; i += 6) {
+  const batch = hosts.slice(i, i + 6).map((h) => connect({ hostname: h, port: 443 }))
+  await Promise.all(
+    batch.map(async (s) => {
+      /* use */ await s.close()
+    })
+  )
+}
+```
+
+### Blocked Destinations
+
+Cloudflare IPs (1.1.1.1), localhost (127.0.0.1), port 25 (SMTP), Worker's own URL blocked for security.
+
+**Solution:** Use public IPs or Tunnel hostnames: `connect({ hostname: "db.internal.company.net", port: 5432 })`
+
+### Scope Requirements
+
+**Problem:** Sockets created in global scope fail
+
+**Cause:** Sockets tied to request lifecycle
+
+**Solution:** Create inside handler: `export default { async fetch() { const socket = connect(...); } }`
+
+## Common Errors
+
+### Error: "proxy request failed"
+
+**Causes:** Blocked destination (Cloudflare IP, localhost, port 25), DNS failure, network unreachable
+
+**Solution:** Validate destinations, use Tunnel hostnames, catch errors with try/catch
+
+### Error: "TCP Loop detected"
+
+**Cause:** Worker connecting to itself
+
+**Solution:** Connect to external service, not Worker's own hostname
+
+### Error: "Port 25 prohibited"
+
+**Cause:** SMTP port blocked
+
+**Solution:** Use Email Workers API for email
+
+### Error: "socket is not open"
+
+**Cause:** Read/write after close
+
+**Solution:** Always use try/finally to ensure proper closure order
+
+### Error: Connection timeout
+
+**Cause:** No built-in timeout
+
+**Solution:** Use `Promise.race()`:
+
+```typescript
+const socket = connect(addr, opts)
+const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), 5000))
+await Promise.race([socket.opened, timeout])
+```
+
+## TLS/SSL Issues
+
+### StartTLS Timing
+
+**Problem:** Calling `startTls()` too early
+
+**Solution:** Send protocol-specific STARTTLS command, wait for server OK, then call `socket.startTls()`
+
+### Certificate Validation
+
+**Problem:** Self-signed certs fail
+
+**Solution:** Use proper certs or Tunnel (handles TLS termination)
+
+## Performance Issues
+
+### Not Using Connection Pooling
+
+**Problem:** New connection overhead per request
+
+**Solution:** Use [Hyperdrive](../hyperdrive/) for databases (built-in pooling)
+
+### Not Using Smart Placement
+
+**Problem:** High latency to backend
+
+**Solution:** Enable: `{ "placement": { "mode": "smart" } }` in wrangler.jsonc
+
+### Forgetting to Close Sockets
+
+**Problem:** Resource leaks
+
+**Solution:** Always use try/finally:
+
+```typescript
+const socket = connect({ hostname: 'api.internal', port: 443 })
+try {
+  // Use socket
+} finally {
+  await socket.close()
+}
+```
+
+## Data Handling Issues
+
+### Assuming Single Read Gets All Data
+
+**Problem:** Only reading once may miss chunked data
+
+**Solution:** Loop `reader.read()` until `done === true` (see patterns.md)
+
+### Text Encoding Issues
+
+**Problem:** Using wrong encoding
+
+**Solution:** Specify encoding: `new TextDecoder('iso-8859-1').decode(data)`
+
+## Security Issues
+
+### SSRF Vulnerability
+
+**Problem:** User-controlled destinations allow access to internal services
+
+**Solution:** Validate against strict allowlist:
+
+```typescript
+const ALLOWED = ['api1.internal.net', 'api2.internal.net']
+const host = new URL(req.url).searchParams.get('host')
+if (!host || !ALLOWED.includes(host)) return new Response('Forbidden', { status: 403 })
+```
+
+## When to Use Alternatives
+
+| Use Case                  | Alternative                  | Reason                      |
+| ------------------------- | ---------------------------- | --------------------------- |
+| PostgreSQL/MySQL          | [Hyperdrive](../hyperdrive/) | Connection pooling, caching |
+| HTTP/HTTPS                | `fetch()`                    | Simpler, built-in           |
+| HTTP with SSRF protection | VPC Services (beta 2025+)    | Declarative bindings        |
+
+## Debugging Tips
+
+1. **Log connection details:** `const info = await socket.opened; console.log(info.remoteAddress);`
+2. **Test with public services first:** Use tcpbin.com:4242 echo server
+3. **Verify Tunnel:** `cloudflared tunnel info <name>` and `cloudflared tunnel route ip list`
+
+## Related
+
+- [Hyperdrive](../hyperdrive/) - Database connections
+- [Smart Placement](../smart-placement/) - Latency optimization
+- [Tunnel Troubleshooting](../tunnel/gotchas.md)

package/skills/cloudflare/references/workers-vpc/patterns.md

@@ -0,0 +1,235 @@
+# Common Patterns
+
+Real-world patterns and examples for TCP Sockets in Cloudflare Workers.
+
+```typescript
+import { connect } from 'cloudflare:sockets'
+```
+
+## Basic Patterns
+
+### Simple Request-Response
+
+```typescript
+const socket = connect({ hostname: 'echo.example.com', port: 7 }, { secureTransport: 'on' })
+try {
+  await socket.opened
+  const writer = socket.writable.getWriter()
+  await writer.write(new TextEncoder().encode('Hello\n'))
+  await writer.close()
+
+  const reader = socket.readable.getReader()
+  const { value } = await reader.read()
+  return new Response(value)
+} finally {
+  await socket.close()
+}
+```
+
+### Reading All Data
+
+```typescript
+async function readAll(socket: Socket): Promise<Uint8Array> {
+  const reader = socket.readable.getReader()
+  const chunks: Uint8Array[] = []
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    chunks.push(value)
+  }
+  const total = chunks.reduce((sum, c) => sum + c.length, 0)
+  const result = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    result.set(chunk, offset)
+    offset += chunk.length
+  }
+  return result
+}
+```
+
+### Streaming Response
+
+```typescript
+// Stream socket data directly to HTTP response
+const socket = connect({ hostname: 'stream.internal', port: 9000 }, { secureTransport: 'on' })
+const writer = socket.writable.getWriter()
+await writer.write(new TextEncoder().encode('STREAM\n'))
+await writer.close()
+return new Response(socket.readable)
+```
+
+## Protocol Examples
+
+### Redis RESP
+
+```typescript
+// Send: *2\r\n$3\r\nGET\r\n$<keylen>\r\n<key>\r\n
+// Recv: $<len>\r\n<data>\r\n or $-1\r\n for null
+const socket = connect({ hostname: 'redis.internal', port: 6379 })
+const writer = socket.writable.getWriter()
+await writer.write(new TextEncoder().encode(`*2\r\n$3\r\nGET\r\n$3\r\nkey\r\n`))
+```
+
+### PostgreSQL
+
+**Use [Hyperdrive](../hyperdrive/) for production.** Raw Postgres protocol is complex (startup, auth, query messages).
+
+### MQTT
+
+```typescript
+const socket = connect({ hostname: 'mqtt.broker', port: 1883 })
+const writer = socket.writable.getWriter()
+// CONNECT: 0x10 <len> 0x00 0x04 "MQTT" 0x04 <flags> ...
+// PUBLISH: 0x30 <len> <topic_len> <topic> <message>
+```
+
+## Error Handling Patterns
+
+### Retry with Backoff
+
+```typescript
+async function connectWithRetry(
+  addr: SocketAddress,
+  opts: SocketOptions,
+  maxRetries = 3
+): Promise<Socket> {
+  for (let i = 1; i <= maxRetries; i++) {
+    try {
+      const socket = connect(addr, opts)
+      await socket.opened
+      return socket
+    } catch (error) {
+      if (i === maxRetries) throw error
+      await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, i - 1))) // Exponential backoff
+    }
+  }
+  throw new Error('Unreachable')
+}
+```
+
+### Timeout
+
+```typescript
+async function connectWithTimeout(
+  addr: SocketAddress,
+  opts: SocketOptions,
+  ms = 5000
+): Promise<Socket> {
+  const socket = connect(addr, opts)
+  const timeout = new Promise<never>((_, reject) =>
+    setTimeout(() => reject(new Error('Timeout')), ms)
+  )
+  await Promise.race([socket.opened, timeout])
+  return socket
+}
+```
+
+### Fallback
+
+```typescript
+async function connectWithFallback(
+  primary: string,
+  fallback: string,
+  port: number
+): Promise<Socket> {
+  try {
+    const socket = connect({ hostname: primary, port }, { secureTransport: 'on' })
+    await socket.opened
+    return socket
+  } catch {
+    return connect({ hostname: fallback, port }, { secureTransport: 'on' })
+  }
+}
+```
+
+## Security Patterns
+
+### Destination Allowlist (Prevent SSRF)
+
+```typescript
+const ALLOWED_HOSTS = ['db.internal.company.net', 'api.internal.company.net', /^10\.0\.1\.\d+$/]
+
+function isAllowed(hostname: string): boolean {
+  return ALLOWED_HOSTS.some((p) => (p instanceof RegExp ? p.test(hostname) : p === hostname))
+}
+
+export default {
+  async fetch(req: Request): Promise<Response> {
+    const target = new URL(req.url).searchParams.get('host')
+    if (!target || !isAllowed(target)) return new Response('Forbidden', { status: 403 })
+    const socket = connect({ hostname: target, port: 443 })
+    // Use socket...
+  },
+}
+```
+
+### Connection Pooling
+
+```typescript
+class SocketPool {
+  private pool = new Map<string, Socket[]>()
+
+  async acquire(hostname: string, port: number): Promise<Socket> {
+    const key = `${hostname}:${port}`
+    const sockets = this.pool.get(key) || []
+    if (sockets.length > 0) return sockets.pop()!
+    const socket = connect({ hostname, port }, { secureTransport: 'on' })
+    await socket.opened
+    return socket
+  }
+
+  release(hostname: string, port: number, socket: Socket): void {
+    const key = `${hostname}:${port}`
+    const sockets = this.pool.get(key) || []
+    if (sockets.length < 3) {
+      sockets.push(socket)
+      this.pool.set(key, sockets)
+    } else socket.close()
+  }
+}
+```
+
+## Multi-Protocol Gateway
+
+```typescript
+interface Protocol {
+  name: string
+  defaultPort: number
+  test(host: string, port: number): Promise<string>
+}
+
+const PROTOCOLS: Record<string, Protocol> = {
+  redis: {
+    name: 'redis',
+    defaultPort: 6379,
+    async test(host, port) {
+      const socket = connect({ hostname: host, port })
+      try {
+        const writer = socket.writable.getWriter()
+        await writer.write(new TextEncoder().encode('*1\r\n$4\r\nPING\r\n'))
+        writer.releaseLock()
+        const reader = socket.readable.getReader()
+        const { value } = await reader.read()
+        return new TextDecoder().decode(value || new Uint8Array())
+      } finally {
+        await socket.close()
+      }
+    },
+  },
+}
+
+export default {
+  async fetch(req: Request): Promise<Response> {
+    const url = new URL(req.url)
+    const proto = url.pathname.slice(1) // /redis
+    const host = url.searchParams.get('host')
+    if (!host || !PROTOCOLS[proto]) return new Response('Invalid', { status: 400 })
+    const result = await PROTOCOLS[proto].test(
+      host,
+      parseInt(url.searchParams.get('port') || '') || PROTOCOLS[proto].defaultPort
+    )
+    return new Response(result)
+  },
+}
+```

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

@@ -0,0 +1,72 @@
+# Cloudflare Workflows
+
+Durable multi-step applications with automatic retries, state persistence, and long-running execution.
+
+## What It Does
+
+- Chain steps with automatic retry logic
+- Persist state between steps (minutes → weeks)
+- Handle failures without losing progress
+- Wait for external events/approvals
+- Sleep without consuming resources
+
+**Available:** Free & Paid Workers plans
+
+## Core Concepts
+
+**Workflow**: Class extending `WorkflowEntrypoint` with `run` method
+**Instance**: Single execution with unique ID & independent state
+**Steps**: Independently retriable units via `step.do()` - API calls, DB queries, AI invocations
+**State**: Persisted from step returns; step name = cache key
+
+## Quick Start
+
+```typescript
+import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers'
+
+type Env = { MY_WORKFLOW: Workflow; DB: D1Database }
+type Params = { userId: string }
+
+export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
+  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
+    const user = await step.do('fetch user', async () => {
+      return await this.env.DB.prepare('SELECT * FROM users WHERE id = ?')
+        .bind(event.payload.userId)
+        .first()
+    })
+
+    await step.sleep('wait 7 days', '7 days')
+
+    await step.do('send reminder', async () => {
+      await sendEmail(user.email, 'Reminder!')
+    })
+  }
+}
+```
+
+## Key Features
+
+- **Durability**: Failed steps don't re-run successful ones
+- **Retries**: Configurable backoff (constant/linear/exponential)
+- **Events**: `waitForEvent()` for webhooks/approvals (timeout: 1h → 365d)
+- **Sleep**: `sleep()` / `sleepUntil()` for scheduling (max 365d)
+- **Parallel**: `Promise.all()` for concurrent steps
+- **Idempotency**: Check-then-execute patterns
+
+## Reading Order
+
+**Getting Started:** configuration.md → api.md → patterns.md  
+**Troubleshooting:** gotchas.md
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc setup, step config, bindings
+- [api.md](./api.md) - Step APIs, instance management, sleep/parameters
+- [patterns.md](./patterns.md) - Common workflows, testing, orchestration
+- [gotchas.md](./gotchas.md) - Timeouts, limits, debugging strategies
+
+## See Also
+
+- [durable-objects](../durable-objects/) - Alternative stateful approach
+- [queues](../queues/) - Message-driven workflows
+- [workers](../workers/) - Entry point for workflow instances

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

@@ -0,0 +1,237 @@
+# Workflow APIs
+
+## Step APIs
+
+```typescript
+// step.do()
+const result = await step.do('step name', async () => {
+  /* logic */
+})
+const result = await step.do('step name', { retries, timeout }, async () => {})
+
+// step.sleep()
+await step.sleep('description', '1 hour')
+await step.sleep('description', 5000) // ms
+
+// step.sleepUntil()
+await step.sleepUntil('description', Date.parse('2024-12-31'))
+
+// step.waitForEvent()
+const data = await step.waitForEvent<PayloadType>('wait', { event: 'webhook-type', timeout: '24h' }) // Default 24h, max 365d
+try {
+  const event = await step.waitForEvent('wait', { event: 'approval', timeout: '1h' })
+} catch (e) {
+  /* Timeout */
+}
+```
+
+## Instance Management
+
+```typescript
+// Create single
+const instance = await env.MY_WORKFLOW.create({
+  id: crypto.randomUUID(),
+  params: { userId: 'user123' },
+}) // id optional, auto-generated if omitted
+
+// Create with custom retention (default: 3 days free, 30 days paid)
+const instance = await env.MY_WORKFLOW.create({
+  id: crypto.randomUUID(),
+  params: { userId: 'user123' },
+  retention: '30 days', // Override default retention period
+})
+
+// Batch (max 100, idempotent: skips existing IDs)
+const instances = await env.MY_WORKFLOW.createBatch([
+  { id: 'user1', params: { name: 'John' } },
+  { id: 'user2', params: { name: 'Jane' } },
+])
+
+// Get & Status
+const instance = await env.MY_WORKFLOW.get('instance-id')
+const status = await instance.status() // {status: 'queued' | 'running' | 'paused' | 'errored' | 'terminated' | 'complete' | 'waiting' | 'waitingForPause' | 'unknown', error?, output?}
+
+// Control
+await instance.pause()
+await instance.resume()
+await instance.terminate()
+await instance.restart()
+
+// Send Events
+await instance.sendEvent({ type: 'approval', payload: { approved: true } }) // Must match waitForEvent type
+```
+
+## Triggering Workflows
+
+```typescript
+// From Worker
+export default {
+  async fetch(req, env) {
+    const instance = await env.MY_WORKFLOW.create({
+      id: crypto.randomUUID(),
+      params: { userId: 'user123' },
+    })
+    return Response.json({ id: instance.id })
+  },
+}
+
+// From Queue
+export default {
+  async queue(batch, env) {
+    for (const msg of batch.messages) {
+      await env.MY_WORKFLOW.create({ id: `job-${msg.id}`, params: msg.body })
+    }
+  },
+}
+
+// From Cron
+export default {
+  async scheduled(event, env) {
+    await env.CLEANUP_WORKFLOW.create({
+      id: `cleanup-${Date.now()}`,
+      params: { timestamp: event.scheduledTime },
+    })
+  },
+}
+
+// From Another Workflow (non-blocking)
+export class ParentWorkflow extends WorkflowEntrypoint<Env, Params> {
+  async run(event, step) {
+    const child = await step.do(
+      'start child',
+      async () =>
+        await this.env.CHILD_WORKFLOW.create({ id: `child-${event.instanceId}`, params: {} })
+    )
+  }
+}
+```
+
+## Error Handling
+
+```typescript
+import { NonRetryableError } from 'cloudflare:workers'
+
+// NonRetryableError
+await step.do('validate', async () => {
+  if (!event.payload.paymentMethod) throw new NonRetryableError('Payment method required')
+  const res = await fetch('https://api.example.com/charge', { method: 'POST' })
+  if (res.status === 401) throw new NonRetryableError('Invalid credentials') // Don't retry
+  if (!res.ok) throw new Error('Retryable failure') // Will retry
+  return res.json()
+})
+
+// Catching Errors
+try {
+  await step.do('risky op', async () => {
+    throw new NonRetryableError('Failed')
+  })
+} catch (e) {
+  await step.do('cleanup', async () => {})
+}
+
+// Idempotency
+await step.do('charge', async () => {
+  const sub = await fetch(`https://api/subscriptions/${id}`).then((r) => r.json())
+  if (sub.charged) return sub // Already done
+  return await fetch(`https://api/subscriptions/${id}`, {
+    method: 'POST',
+    body: JSON.stringify({ amount: 10.0 }),
+  }).then((r) => r.json())
+})
+```
+
+## Type Constraints
+
+Params and step returns must be `Rpc.Serializable<T>`:
+
+```typescript
+// ✅ Valid types
+type ValidParams = {
+  userId: string
+  count: number
+  tags: string[]
+  metadata: Record<string, unknown>
+}
+
+// ❌ Invalid types
+type InvalidParams = {
+  callback: () => void // Functions not serializable
+  symbol: symbol // Symbols not serializable
+  circular: any // Circular references not allowed
+}
+
+// Step returns follow same rules
+const result = await step.do('fetch', async () => {
+  return { userId: '123', data: [1, 2, 3] } // ✅ Plain object
+})
+```
+
+## Sleep & Scheduling
+
+```typescript
+// Relative
+await step.sleep('wait 1 hour', '1 hour')
+await step.sleep('wait 30 days', '30 days')
+await step.sleep('wait 5s', 5000) // ms
+
+// Absolute
+await step.sleepUntil('launch date', Date.parse('24 Oct 2024 13:00:00 UTC'))
+await step.sleepUntil('deadline', new Date('2024-12-31T23:59:59Z'))
+```
+
+Units: second, minute, hour, day, week, month, year. Max: 365 days.
+Sleeping instances don't count toward concurrency.
+
+## Parameters
+
+**Pass from Worker:**
+
+```typescript
+const instance = await env.MY_WORKFLOW.create({
+  id: crypto.randomUUID(),
+  params: { userId: 'user123', email: 'user@example.com' },
+})
+```
+
+**Access in Workflow:**
+
+```typescript
+async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
+  const userId = event.payload.userId;
+  const instanceId = event.instanceId;
+  const createdAt = event.timestamp;
+}
+```
+
+**CLI Trigger:**
+
+```bash
+npx wrangler workflows trigger my-workflow '{"userId":"user123"}'
+```
+
+## Wrangler CLI
+
+```bash
+npm create cloudflare@latest my-workflow -- --template "cloudflare/workflows-starter"
+npx wrangler deploy
+npx wrangler workflows list
+npx wrangler workflows trigger my-workflow '{"userId":"user123"}'
+npx wrangler workflows instances list my-workflow
+npx wrangler workflows instances describe my-workflow instance-id
+npx wrangler workflows instances pause/resume/terminate my-workflow instance-id
+```
+
+## REST API
+
+```bash
+# Create
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/workflows/{workflow_name}/instances" -H "Authorization: Bearer {token}" -d '{"id":"custom-id","params":{"userId":"user123"}}'
+
+# Status
+curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/status" -H "Authorization: Bearer {token}"
+
+# Send Event
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/events" -H "Authorization: Bearer {token}" -d '{"type":"approval","payload":{"approved":true}}'
+```
+
+See: [configuration.md](./configuration.md), [patterns.md](./patterns.md)