@mohanscodex/spectra-code 0.4.9 → 0.5.0

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

@@ -0,0 +1,132 @@
+# 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-deploy/references/workers-vpc/README.md

@@ -0,0 +1,127 @@
+# 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-deploy/references/workers-vpc/api.md

@@ -0,0 +1,202 @@
+# 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-deploy/references/workers-vpc/configuration.md

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