@mohanscodex/spectra-code 0.4.8 → 0.5.0

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

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

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

@@ -0,0 +1,69 @@
+# 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.params.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-deploy/references/workflows/api.md

@@ -0,0 +1,185 @@
+# 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.params.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.params.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)