memory-journal-mcp 7.7.1 → 8.0.0

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

@@ -0,0 +1,134 @@
+# Workers Playground Patterns
+
+## JSON API
+
+```javascript
+export default {
+  async fetch(request) {
+    const url = new URL(request.url)
+    if (url.pathname === '/api/hello') return Response.json({ message: 'Hello' })
+    if (url.pathname === '/api/echo' && request.method === 'POST') {
+      return Response.json({ received: await request.json() })
+    }
+    return Response.json({ error: 'Not found' }, { status: 404 })
+  },
+}
+```
+
+## Router Pattern
+
+```javascript
+const routes = {
+  '/': () => new Response('Home'),
+  '/api/users': () => Response.json([{ id: 1, name: 'Alice' }]),
+}
+
+export default {
+  async fetch(request) {
+    const handler = routes[new URL(request.url).pathname]
+    return handler ? handler() : new Response('Not Found', { status: 404 })
+  },
+}
+```
+
+## Proxy Pattern
+
+```javascript
+export default {
+  async fetch(request) {
+    const url = new URL(request.url)
+    url.hostname = 'api.example.com'
+    return fetch(url.toString(), {
+      method: request.method,
+      headers: request.headers,
+      body: request.body,
+    })
+  },
+}
+```
+
+## CORS Handling
+
+```javascript
+export default {
+  async fetch(request) {
+    if (request.method === 'OPTIONS') {
+      return new Response(null, {
+        headers: {
+          'Access-Control-Allow-Origin': '*',
+          'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE',
+          'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+        },
+      })
+    }
+    const response = await fetch('https://api.example.com', request)
+    const modified = new Response(response.body, response)
+    modified.headers.set('Access-Control-Allow-Origin', '*')
+    return modified
+  },
+}
+```
+
+## Caching
+
+```javascript
+export default {
+  async fetch(request) {
+    if (request.method !== 'GET') return fetch(request)
+    const cache = caches.default
+    let response = await cache.match(request)
+    if (!response) {
+      response = await fetch('https://api.example.com')
+      if (response.status === 200) await cache.put(request, response.clone())
+    }
+    return response
+  },
+}
+```
+
+## Hono Framework
+
+```javascript
+import { Hono } from 'https://esm.sh/hono@3'
+const app = new Hono()
+app.get('/', (c) => c.text('Hello'))
+app.get('/api/users/:id', (c) => c.json({ id: c.req.param('id') }))
+app.notFound((c) => c.json({ error: 'Not found' }, 404))
+export default app
+```
+
+## Authentication
+
+```javascript
+export default {
+  async fetch(request) {
+    const auth = request.headers.get('Authorization')
+    if (!auth?.startsWith('Bearer ')) {
+      return Response.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+    const token = auth.substring(7)
+    if (token !== 'secret-token') {
+      return Response.json({ error: 'Invalid token' }, { status: 403 })
+    }
+    return Response.json({ message: 'Authenticated' })
+  },
+}
+```
+
+## Error Handling
+
+```javascript
+export default {
+  async fetch(request) {
+    try {
+      const response = await fetch('https://api.example.com')
+      if (!response.ok) throw new Error(`API returned ${response.status}`)
+      return response
+    } catch (error) {
+      return Response.json({ error: error.message }, { status: 500 })
+    }
+  },
+}
+```
+
+**Note:** In-memory state (Maps, variables) resets on Worker cold start. Use Durable Objects or KV for persistence.

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

@@ -0,0 +1,130 @@
+# Workers VPC Connectivity
+
+Connect Cloudflare Workers to private networks and internal infrastructure using TCP Sockets.
+
+## Overview
+
+Workers VPC connectivity enables outbound TCP connections from Workers to private resources in AWS, Azure, GCP, on-premises datacenters, or any private network. This is achieved through the **TCP Sockets API** (`cloudflare:sockets`), which provides low-level network access for custom protocols and services.
+
+**Key capabilities:**
+
+- Direct TCP connections to private IPs and hostnames
+- TLS/StartTLS support for encrypted connections
+- Integration with Cloudflare Tunnel for secure private network access
+- Full control over wire protocols (database protocols, SSH, MQTT, custom TCP)
+
+**Note:** This reference documents the TCP Sockets API. For the newer Workers VPC Services product (HTTP-only service bindings with built-in SSRF protection), refer to separate documentation when available. VPC Services is currently in beta (2025+).
+
+## Quick Decision: Which Technology?
+
+Need private network connectivity from Workers?
+
+| Requirement                                   | Use                                                  | Why                                    |
+| --------------------------------------------- | ---------------------------------------------------- | -------------------------------------- |
+| HTTP/HTTPS APIs in private network            | VPC Services (beta, separate docs)                   | SSRF-safe, declarative bindings        |
+| PostgreSQL/MySQL databases                    | [Hyperdrive](../hyperdrive/)                         | Connection pooling, caching, optimized |
+| Custom TCP protocols (SSH, MQTT, proprietary) | **TCP Sockets (this doc)**                           | Full protocol control                  |
+| Simple HTTP with lowest latency               | TCP Sockets + [Smart Placement](../smart-placement/) | Manual optimization                    |
+| Expose on-prem to internet (inbound)          | [Cloudflare Tunnel](../tunnel/)                      | Not Worker-specific                    |
+
+## When to Use TCP Sockets
+
+**Use TCP Sockets when you need:**
+
+- ✅ Direct control over wire protocols (e.g., Postgres wire protocol, SSH, Redis RESP)
+- ✅ Non-HTTP protocols (MQTT, SMTP, custom binary protocols)
+- ✅ StartTLS or custom TLS negotiation
+- ✅ Streaming binary data over TCP
+
+**Don't use TCP Sockets when:**
+
+- ❌ You just need HTTP/HTTPS (use `fetch()` or VPC Services)
+- ❌ You need PostgreSQL/MySQL (use Hyperdrive for pooling)
+- ❌ You need WebSocket (use native Workers WebSocket)
+
+## Quick Start
+
+```typescript
+import { connect } from 'cloudflare:sockets'
+
+export default {
+  async fetch(req: Request): Promise<Response> {
+    // Connect to private service
+    const socket = connect(
+      { hostname: 'db.internal.company.net', port: 5432 },
+      { secureTransport: 'on' }
+    )
+
+    try {
+      await socket.opened // Wait for connection
+
+      const writer = socket.writable.getWriter()
+      await writer.write(new TextEncoder().encode('QUERY\r\n'))
+      await writer.close()
+
+      const reader = socket.readable.getReader()
+      const { value } = await reader.read()
+
+      return new Response(value)
+    } finally {
+      await socket.close()
+    }
+  },
+}
+```
+
+## Architecture Pattern: Workers + Tunnel
+
+Most private network connectivity combines TCP Sockets with Cloudflare Tunnel:
+
+```
+┌─────────┐     ┌─────────────┐     ┌──────────────┐     ┌─────────────┐
+│ Worker  │────▶│ TCP Socket  │────▶│   Tunnel     │────▶│   Private   │
+│         │     │ (this API)  │     │ (cloudflared)│     │   Network   │
+└─────────┘     └─────────────┘     └──────────────┘     └─────────────┘
+```
+
+1. Worker opens TCP socket to Tunnel hostname
+2. Tunnel endpoint routes to private IP
+3. Response flows back through Tunnel to Worker
+
+See [configuration.md](./configuration.md) for Tunnel setup details.
+
+## Reading Order
+
+1. **Start here (README.md)** - Overview and decision guide
+2. **[api.md](./api.md)** - Socket interface, types, methods
+3. **[configuration.md](./configuration.md)** - Wrangler setup, Tunnel integration
+4. **[patterns.md](./patterns.md)** - Real-world examples (databases, protocols, error handling)
+5. **[gotchas.md](./gotchas.md)** - Limits, blocked ports, common errors
+
+## Key Limits
+
+| Limit                              | Value                               |
+| ---------------------------------- | ----------------------------------- |
+| Max concurrent sockets per request | 6                                   |
+| Blocked destinations               | Cloudflare IPs, localhost, port 25  |
+| Scope requirement                  | Must create in handler (not global) |
+
+See [gotchas.md](./gotchas.md) for complete limits and troubleshooting.
+
+## Best Practices
+
+1. **Always close sockets** - Use try/finally blocks
+2. **Validate destinations** - Prevent SSRF by allowlisting hosts
+3. **Use Hyperdrive for databases** - Better performance than raw TCP
+4. **Prefer fetch() for HTTP** - Only use TCP when necessary
+5. **Combine with Smart Placement** - Reduce latency to private networks
+
+## Related Technologies
+
+- **[Hyperdrive](../hyperdrive/)** - PostgreSQL/MySQL with connection pooling
+- **[Cloudflare Tunnel](../tunnel/)** - Secure private network access
+- **[Smart Placement](../smart-placement/)** - Auto-locate Workers near backends
+- **VPC Services (beta)** - HTTP-only service bindings with SSRF protection (separate docs)
+
+## Reference
+
+- [TCP Sockets API Documentation](https://developers.cloudflare.com/workers/runtime-apis/tcp-sockets/)
+- [Connect to databases guide](https://developers.cloudflare.com/workers/tutorials/connect-to-postgres/)
+- [Cloudflare Tunnel setup](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)

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

@@ -0,0 +1,196 @@
+# TCP Sockets API Reference
+
+Complete API reference for the Cloudflare Workers TCP Sockets API (`cloudflare:sockets`).
+
+## Core Function: `connect()`
+
+```typescript
+function connect(address: SocketAddress, options?: SocketOptions): Socket
+```
+
+Creates an outbound TCP connection to the specified address.
+
+### Parameters
+
+#### `SocketAddress`
+
+```typescript
+interface SocketAddress {
+  hostname: string // DNS hostname or IP address
+  port: number // TCP port (1-65535, excluding blocked ports)
+}
+```
+
+| Field      | Type     | Description           | Example                            |
+| ---------- | -------- | --------------------- | ---------------------------------- |
+| `hostname` | `string` | Target hostname or IP | `"db.internal.net"`, `"10.0.1.50"` |
+| `port`     | `number` | TCP port number       | `5432`, `443`, `22`                |
+
+DNS names are resolved at connection time. IPv4, IPv6, and private IPs (10.x, 172.16.x, 192.168.x) supported.
+
+#### `SocketOptions`
+
+```typescript
+interface SocketOptions {
+  secureTransport?: 'off' | 'on' | 'starttls'
+  allowHalfOpen?: boolean
+}
+```
+
+| Field             | Type                          | Default | Description                   |
+| ----------------- | ----------------------------- | ------- | ----------------------------- |
+| `secureTransport` | `"off" \| "on" \| "starttls"` | `"off"` | TLS mode                      |
+| `allowHalfOpen`   | `boolean`                     | `false` | Allow half-closed connections |
+
+**`secureTransport` modes:**
+
+| Mode         | Behavior                                     | Use Case                           |
+| ------------ | -------------------------------------------- | ---------------------------------- |
+| `"off"`      | Plain TCP, no encryption                     | Testing, internal trusted networks |
+| `"on"`       | Immediate TLS handshake                      | HTTPS, secure databases, SSH       |
+| `"starttls"` | Start plain, upgrade later with `startTls()` | Postgres, SMTP, IMAP               |
+
+**`allowHalfOpen`:** When `false` (default), closing read stream auto-closes write stream. When `true`, streams are independent.
+
+### Returns
+
+A `Socket` object with readable/writable streams.
+
+## Socket Interface
+
+```typescript
+interface Socket {
+  // Streams
+  readable: ReadableStream<Uint8Array>
+  writable: WritableStream<Uint8Array>
+
+  // Connection state
+  opened: Promise<SocketInfo>
+  closed: Promise<void>
+
+  // Methods
+  close(): Promise<void>
+  startTls(): Socket
+}
+```
+
+### Properties
+
+#### `readable: ReadableStream<Uint8Array>`
+
+Stream for reading data from the socket. Use `getReader()` to consume data.
+
+```typescript
+const reader = socket.readable.getReader()
+const { done, value } = await reader.read() // Read one chunk
+```
+
+#### `writable: WritableStream<Uint8Array>`
+
+Stream for writing data to the socket. Use `getWriter()` to send data.
+
+```typescript
+const writer = socket.writable.getWriter()
+await writer.write(new TextEncoder().encode('HELLO\r\n'))
+await writer.close()
+```
+
+#### `opened: Promise<SocketInfo>`
+
+Promise that resolves when connection succeeds, rejects on failure.
+
+```typescript
+interface SocketInfo {
+  remoteAddress?: string // May be undefined
+  localAddress?: string // May be undefined
+}
+
+try {
+  const info = await socket.opened
+} catch (error) {
+  // Connection failed
+}
+```
+
+#### `closed: Promise<void>`
+
+Promise that resolves when socket is fully closed (both directions).
+
+### Methods
+
+#### `close(): Promise<void>`
+
+Closes the socket gracefully, waiting for pending writes to complete.
+
+```typescript
+const socket = connect({ hostname: 'api.internal', port: 443 })
+try {
+  // Use socket
+} finally {
+  await socket.close() // Always call in finally block
+}
+```
+
+#### `startTls(): Socket`
+
+Upgrades connection to TLS. Only available when `secureTransport: "starttls"` was specified.
+
+```typescript
+const socket = connect({ hostname: 'db.internal', port: 5432 }, { secureTransport: 'starttls' })
+
+// Send protocol-specific StartTLS command
+const writer = socket.writable.getWriter()
+await writer.write(new TextEncoder().encode('STARTTLS\r\n'))
+
+// Upgrade to TLS - use returned socket, not original
+const secureSocket = socket.startTls()
+const secureWriter = secureSocket.writable.getWriter()
+```
+
+## Complete Example
+
+```typescript
+import { connect } from 'cloudflare:sockets'
+
+export default {
+  async fetch(req: Request): Promise<Response> {
+    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, TCP!\n'))
+      await writer.close()
+
+      const reader = socket.readable.getReader()
+      const { value } = await reader.read()
+
+      return new Response(value)
+    } finally {
+      await socket.close()
+    }
+  },
+}
+```
+
+See [patterns.md](./patterns.md) for multi-chunk reading, error handling, and protocol implementations.
+
+## Quick Reference
+
+| Task           | Code                                              |
+| -------------- | ------------------------------------------------- |
+| Import         | `import { connect } from 'cloudflare:sockets';`   |
+| Connect        | `connect({ hostname: "host", port: 443 })`        |
+| With TLS       | `connect(addr, { secureTransport: "on" })`        |
+| StartTLS       | `socket.startTls()` after handshake               |
+| Write          | `await writer.write(data); await writer.close();` |
+| Read           | `const { value } = await reader.read();`          |
+| Error handling | `try { await socket.opened; } catch { }`          |
+| Always close   | `try { } finally { await socket.close(); }`       |
+
+## See Also
+
+- [patterns.md](./patterns.md) - Real-world protocol implementations
+- [configuration.md](./configuration.md) - Wrangler setup and environment variables
+- [gotchas.md](./gotchas.md) - Limits and error handling

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

@@ -0,0 +1,151 @@
+# Configuration
+
+Setup and configuration for TCP Sockets in Cloudflare Workers.
+
+## Wrangler Configuration
+
+### Basic Setup
+
+TCP Sockets are available by default in Workers runtime. No special configuration required in `wrangler.jsonc`:
+
+```jsonc
+{
+  "name": "private-network-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01",
+}
+```
+
+### Environment Variables
+
+Store connection details as env vars:
+
+```jsonc
+{
+  "vars": { "DB_HOST": "10.0.1.50", "DB_PORT": "5432" },
+}
+```
+
+```typescript
+interface Env {
+  DB_HOST: string
+  DB_PORT: string
+}
+
+export default {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    const socket = connect({ hostname: env.DB_HOST, port: parseInt(env.DB_PORT) })
+  },
+}
+```
+
+### Per-Environment Configuration
+
+```jsonc
+{
+  "vars": { "DB_HOST": "localhost" },
+  "env": {
+    "staging": { "vars": { "DB_HOST": "staging-db.internal.net" } },
+    "production": { "vars": { "DB_HOST": "prod-db.internal.net" } },
+  },
+}
+```
+
+Deploy: `wrangler deploy --env staging` or `wrangler deploy --env production`
+
+## Integration with Cloudflare Tunnel
+
+To connect Workers to private networks, combine TCP Sockets with Cloudflare Tunnel:
+
+```
+Worker (TCP Socket) → Tunnel hostname → cloudflared → Private Network
+```
+
+### Quick Setup
+
+1. **Install cloudflared** on a server inside your private network
+2. **Create tunnel**: `cloudflared tunnel create my-private-network`
+3. **Configure routing** in `config.yml`:
+
+```yaml
+tunnel: <TUNNEL_ID>
+credentials-file: /path/to/<TUNNEL_ID>.json
+ingress:
+  - hostname: db.internal.example.com
+    service: tcp://10.0.1.50:5432
+  - service: http_status:404 # Required catch-all
+```
+
+4. **Run tunnel**: `cloudflared tunnel run my-private-network`
+5. **Connect from Worker**:
+
+```typescript
+const socket = connect(
+  { hostname: 'db.internal.example.com', port: 5432 }, // Tunnel hostname
+  { secureTransport: 'on' }
+)
+```
+
+For detailed Tunnel setup, see [Tunnel configuration reference](../tunnel/configuration.md).
+
+## Smart Placement Integration
+
+Reduce latency by auto-placing Workers near backends:
+
+```jsonc
+{ "placement": { "mode": "smart" } }
+```
+
+Workers automatically relocate closer to TCP socket destinations after observing connection latency. See [Smart Placement reference](../smart-placement/).
+
+## Secrets Management
+
+Store sensitive credentials as secrets (not in wrangler.jsonc):
+
+```bash
+wrangler secret put DB_PASSWORD  # Enter value when prompted
+```
+
+Access in Worker via `env.DB_PASSWORD`. Use in protocol handshake or authentication.
+
+## Local Development
+
+Test with `wrangler dev`. Note: Local mode may not access private networks. Use public endpoints or mock servers for development:
+
+```typescript
+const config =
+  process.env.NODE_ENV === 'dev'
+    ? { hostname: 'localhost', port: 5432 } // Mock
+    : { hostname: 'db.internal.example.com', port: 5432 } // Production
+```
+
+## Connection String Patterns
+
+Parse connection strings to extract host and port:
+
+```typescript
+function parseConnectionString(connStr: string): SocketAddress {
+  const url = new URL(connStr) // e.g., "postgres://10.0.1.50:5432/mydb"
+  return { hostname: url.hostname, port: parseInt(url.port) || 5432 }
+}
+```
+
+## Hyperdrive Integration
+
+For PostgreSQL/MySQL, prefer Hyperdrive over raw TCP sockets (includes connection pooling):
+
+```jsonc
+{ "hyperdrive": [{ "binding": "DB", "id": "<HYPERDRIVE_ID>" }] }
+```
+
+See [Hyperdrive reference](../hyperdrive/) for complete setup.
+
+## Compatibility
+
+TCP Sockets available in all modern Workers. Use current date: `"compatibility_date": "2025-01-01"`. No special flags required.
+
+## Related Configuration
+
+- **[Tunnel Configuration](../tunnel/configuration.md)** - Detailed cloudflared setup
+- **[Smart Placement](../smart-placement/configuration.md)** - Placement mode options
+- **[Hyperdrive](../hyperdrive/configuration.md)** - Database connection pooling setup