memory-journal-mcp 8.0.1 → 9.1.0

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

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

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

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

@@ -1,237 +0,0 @@
-# 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)