@prmichaelsen/acp-visualizer 0.1.0

package/agent/patterns/tanstack-cloudflare.websocket-manager.md

@@ -0,0 +1,237 @@
+# WebSocket Manager
+
+**Category**: Architecture
+**Applicable To**: Real-time WebSocket connections with auto-reconnect, visibility recovery, and discriminated union message types
+**Status**: Stable
+
+---
+
+## Overview
+
+A class-based WebSocket client (`ChatWebSocket`) with exponential backoff reconnection (5 attempts, 1s base), page visibility recovery, discriminated union message types, and init-based pre-warming. The server side uses a Cloudflare Durable Object (`ChatRoom`) for session multiplexing with ACL-filtered broadcasting. Each component instance creates its own WebSocket with proper message handlers.
+
+---
+
+## Implementation
+
+### ChatWebSocket Client
+
+**File**: `src/lib/chat/websocket.ts`
+
+```typescript
+interface ChatWebSocketConfig {
+  userId: string
+  conversationId?: string
+  ghostOwner?: string
+  onMessage: (message: WebSocketMessage) => void
+}
+
+class ChatWebSocket {
+  private ws: WebSocket | null = null
+  private reconnectAttempts = 0
+  private maxReconnectAttempts = 5
+  private reconnectDelay = 1000         // Base delay (ms)
+  private intentionalDisconnect = false
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private visibilityHandler: (() => void) | null = null
+}
+```
+
+### Connection Lifecycle
+
+```
+connect()
+  ├─ Set intentionalDisconnect = false
+  ├─ Clean up old visibility handler
+  ├─ Cancel pending reconnect timer
+  ├─ Close zombie WebSocket (clear handlers first)
+  ├─ Construct URL: wss://{host}/api/chat-ws?userId=X&conversationId=Y
+  └─ Create new WebSocket
+      ├─ onopen:
+      │   ├─ Reset reconnectAttempts = 0
+      │   ├─ Emit connection_change { connected: true }
+      │   └─ Send init message (triggers server pre-warming)
+      ├─ onmessage: Parse JSON → handleMessage(data)
+      ├─ onerror: Emit error event
+      └─ onclose:
+          ├─ Emit connection_change { connected: false }
+          ├─ Register visibilitychange handler
+          └─ attemptReconnect()
+```
+
+### Reconnection (Exponential Backoff)
+
+```typescript
+private attemptReconnect() {
+  if (this.intentionalDisconnect) return
+  if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+    this.config.onMessage({ type: 'error', error: 'Failed to reconnect' })
+    return
+  }
+  this.reconnectAttempts++
+  const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1)
+  // Sequence: 1s, 2s, 4s, 8s, 16s → give up
+  this.reconnectTimer = setTimeout(() => this.connect(), delay)
+}
+```
+
+### Visibility Recovery
+
+When the tab becomes visible and the WebSocket is dead, reconnect immediately with reset retry counter:
+
+```typescript
+this.visibilityHandler = () => {
+  if (document.visibilityState === 'visible' &&
+      (!this.ws || this.ws.readyState === WebSocket.CLOSED)) {
+    this.reconnectAttempts = 0
+    this.connect()
+  }
+}
+document.addEventListener('visibilitychange', this.visibilityHandler)
+```
+
+### Discriminated Union Message Types
+
+```typescript
+type WebSocketMessage =
+  | { type: 'chunk'; content: string }
+  | { type: 'tool_call'; toolCall: ToolCall; persistedToolCallId?: string }
+  | { type: 'tool_result'; toolResult: ToolResult; persistedToolCallId?: string }
+  | { type: 'message'; message: Message }
+  | { type: 'messages_loaded'; messages: Message[]; hasMore: boolean }
+  | { type: 'connection_change'; connected: boolean }
+  | { type: 'complete' }
+  | { type: 'cancelled' }
+  | { type: 'error'; error: string }
+  | { type: 'generation_in_progress' }
+  | { type: 'token_limit_warning'; percentage: number; estimatedTokens: number; maxTokens: number }
+  | { type: 'progress_start'; toolCallId: string; command: string }
+  | { type: 'progress_update'; toolCallId: string; output: string }
+  | { type: 'progress_complete'; toolCallId: string; exitCode: number }
+  | { type: 'progress_error'; toolCallId: string; error: string }
+  | { type: 'status'; serverName?: string; statusMessage?: string }
+  | { type: 'conversation_created'; conversationId: string }
+  | { type: 'usage'; input_tokens: number; output_tokens: number }
+```
+
+### Sending Messages
+
+```typescript
+sendMessage(content: string | ContentBlock[], conversationId?: string) {
+  if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+    this.config.onMessage({ type: 'error', error: 'Not connected' })
+    return
+  }
+  this.ws.send(JSON.stringify({
+    type: 'message', message: content,
+    userId: this.config.userId, conversationId, ghostOwner: this.config.ghostOwner,
+  }))
+}
+
+cancelGeneration(conversationId?: string) { /* send type: 'cancel' */ }
+loadMessages(conversationId: string, limit?: number, startAfter?: string) { /* send type: 'load_messages' */ }
+```
+
+### Graceful Disconnect
+
+```typescript
+disconnect() {
+  this.intentionalDisconnect = true
+  clearTimeout(this.reconnectTimer)
+  document.removeEventListener('visibilitychange', this.visibilityHandler)
+  if (this.ws) {
+    this.ws.onclose = null; this.ws.onmessage = null; this.ws.onerror = null
+    this.ws.close()
+    this.ws = null
+  }
+}
+```
+
+### Component Integration
+
+```typescript
+// Each ChatInterface creates its own WebSocket
+useEffect(() => {
+  if (!user) return
+  const ws = new ChatWebSocket({
+    userId: user.uid,
+    conversationId,
+    ghostOwner,
+    onMessage: (msg) => {
+      switch (msg.type) {
+        case 'chunk': /* append to streaming blocks */ break
+        case 'message': /* add to message list */ break
+        case 'complete': /* finalize assistant message */ break
+        // ...
+      }
+    },
+  })
+  ws.connect()
+  wsClientRef.current = ws
+  return () => ws.disconnect()
+}, [user, conversationId, ghostOwner])
+```
+
+### Server: Init Pre-Warming
+
+On `init` message, the ChatRoom DO:
+1. Registers user session
+2. Loads last 50 messages from Firestore
+3. Sends `messages_loaded` event
+4. If active generation exists, sends `generation_in_progress`
+5. Sends `ready` signal
+
+### Server: ACL-Filtered Broadcasting
+
+```typescript
+private broadcastMessage(message: ServerMessage, conversationId?: string) {
+  for (const [socket, userId] of this.sessions.entries()) {
+    if (conversationId && this.sessionConversations.get(socket) !== conversationId) continue
+    if (message.visible_to_user_ids && !message.visible_to_user_ids.includes(userId)) continue
+    socket.send(JSON.stringify(message))
+  }
+}
+```
+
+---
+
+## Anti-Patterns
+
+### Sharing a Single WebSocket Across Components
+
+```typescript
+// Bad: Pre-connected WebSocket has no-op handlers — messages get lost
+const ws = useWebSocketManager()  // Returns shared instance
+<ChatInterface ws={ws} />         // Can't register proper handlers
+
+// Good: Each component creates its own WebSocket
+const ws = new ChatWebSocket({ userId, conversationId, onMessage: handleMessage })
+```
+
+### Not Clearing Handlers Before Closing
+
+```typescript
+// Bad: Old onclose fires and triggers reconnect
+this.ws.close()
+
+// Good: Clear handlers first
+this.ws.onclose = null; this.ws.onmessage = null; this.ws.onerror = null
+this.ws.close()
+```
+
+---
+
+## Checklist
+
+- [ ] Each component creates its own `ChatWebSocket` instance
+- [ ] `onMessage` handler covers all discriminated union cases
+- [ ] `disconnect()` called on component unmount
+- [ ] Visibility handler registered for tab recovery
+- [ ] Event handlers cleared before closing WebSocket
+- [ ] Server broadcasts filter by conversationId + ACL visibility
+
+---
+
+**Status**: Stable
+**Last Updated**: 2026-03-14
+**Contributors**: Community

package/agent/patterns/tanstack-cloudflare.wrangler-configuration.md

@@ -0,0 +1,358 @@
+# Wrangler Configuration Pattern
+
+**Category**: Infrastructure
+**Applicable To**: TanStack Start + Cloudflare Workers applications
+**Status**: Stable
+
+---
+
+## Overview
+
+The `wrangler.toml` file configures how your TanStack Start application runs on Cloudflare Workers. This pattern documents the complete configuration required for a production TanStack Start application, including Durable Object bindings, rate limiting, migrations, observability, and environment management.
+
+Getting the wrangler configuration right is essential — incorrect settings can cause deployment failures, missing bindings, or production runtime errors.
+
+---
+
+## When to Use This Pattern
+
+✅ **Use this pattern when:**
+- Deploying TanStack Start applications to Cloudflare Workers
+- Using Durable Objects for stateful features
+- Need rate limiting, observability, or environment variables
+- Setting up production deployment configuration
+
+❌ **Don't use this pattern when:**
+- Not using Cloudflare Workers
+- Using Cloudflare Pages instead of Workers
+
+---
+
+## Core Principles
+
+1. **Single Configuration File**: All Worker configuration in `wrangler.toml`
+2. **Explicit Bindings**: All Durable Objects, rate limiters, and KV namespaces explicitly declared
+3. **Migration Tags**: Durable Object class changes tracked via sequential migration tags
+4. **Secrets via CLI**: Sensitive values stored as Cloudflare secrets, never in wrangler.toml
+5. **Compatibility Date**: Pin to a specific date for API stability
+
+---
+
+## Implementation
+
+### Complete wrangler.toml Reference
+
+```toml
+# ─── Basic Configuration ─────────────────────────────────────────────────────
+
+name = "my-app"
+main = "src/server.ts"
+compatibility_date = "2026-02-10"
+compatibility_flags = ["nodejs_compat"]
+
+# ─── CPU Limits (Workers Paid) ────────────────────────────────────────────────
+
+[limits]
+cpu_ms = 300000  # 5 minutes (300,000 ms) — maximum for Workers Paid plan
+
+# ─── Observability ────────────────────────────────────────────────────────────
+
+[observability]
+enabled = true
+
+[observability.logs]
+enabled = true
+invocation_logs = true
+
+# ─── Durable Objects ──────────────────────────────────────────────────────────
+
+[[durable_objects.bindings]]
+name = "CHAT_ROOM"
+class_name = "ChatRoom"
+
+[[durable_objects.bindings]]
+name = "UPLOAD_MANAGER"
+class_name = "UploadManager"
+
+# ─── Durable Object Migrations ───────────────────────────────────────────────
+# Tags must be sequential. Each deployment reads these to determine schema changes.
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["ChatRoom"]
+
+[[migrations]]
+tag = "v2"
+new_sqlite_classes = ["UploadManager"]
+
+# To delete a Durable Object class:
+# [[migrations]]
+# tag = "v3"
+# deleted_classes = ["ObsoleteClass"]
+
+# ─── Rate Limiting ────────────────────────────────────────────────────────────
+# namespace_id must be a string containing a positive integer
+
+[[unsafe.bindings]]
+name = "AUTH_RATE_LIMITER"
+type = "ratelimit"
+namespace_id = "1001"
+simple = { limit = 5, period = 60 }
+
+[[unsafe.bindings]]
+name = "API_RATE_LIMITER"
+type = "ratelimit"
+namespace_id = "1002"
+simple = { limit = 100, period = 60 }
+
+[[unsafe.bindings]]
+name = "WS_RATE_LIMITER"
+type = "ratelimit"
+namespace_id = "1003"
+simple = { limit = 10, period = 60 }
+
+# ─── Environment Variables (non-secret) ──────────────────────────────────────
+# [vars]
+# APP_ENV = "production"
+# LOG_LEVEL = "info"
+
+# ─── Secrets (set via CLI, never in this file) ───────────────────────────────
+# wrangler secret put AWS_ACCESS_KEY_ID
+# wrangler secret put AWS_SECRET_ACCESS_KEY
+# wrangler secret put FIREBASE_PROJECT_ID
+# wrangler secret put FIREBASE_CLIENT_EMAIL
+# wrangler secret put FIREBASE_PRIVATE_KEY
+```
+
+### Vite Configuration
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { cloudflare } from '@opennextjs/cloudflare'
+import { TanStackStartVite as tanstackStart } from '@tanstack/start/vite-plugin'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+import viteTsConfigPaths from 'vite-tsconfig-paths'
+
+export default defineConfig({
+  plugins: [
+    cloudflare({ viteEnvironment: { name: 'ssr' } }),
+    viteTsConfigPaths(),
+    tailwindcss(),
+    tanstackStart(),
+    react(),
+  ],
+})
+```
+
+### TypeScript Env Types
+
+```typescript
+// src/env.d.ts (or generated via wrangler types)
+interface Env {
+  // Durable Objects
+  CHAT_ROOM: DurableObjectNamespace
+  UPLOAD_MANAGER: DurableObjectNamespace
+
+  // Rate Limiters
+  AUTH_RATE_LIMITER: RateLimit
+  API_RATE_LIMITER: RateLimit
+  WS_RATE_LIMITER: RateLimit
+
+  // Secrets
+  AWS_ACCESS_KEY_ID: string
+  AWS_SECRET_ACCESS_KEY: string
+  FIREBASE_PROJECT_ID: string
+  FIREBASE_CLIENT_EMAIL: string
+  FIREBASE_PRIVATE_KEY: string
+}
+```
+
+---
+
+## Configuration Sections Explained
+
+### Basic Configuration
+
+| Field | Purpose | Example |
+|-------|---------|---------|
+| `name` | Worker name (used in deployment) | `"my-app"` |
+| `main` | Entry point file | `"src/server.ts"` |
+| `compatibility_date` | Pin Cloudflare API version | `"2026-02-10"` |
+| `compatibility_flags` | Enable Node.js APIs | `["nodejs_compat"]` |
+
+### CPU Limits
+
+| Field | Purpose | Default | Paid Plan Max |
+|-------|---------|---------|---------------|
+| `cpu_ms` | Max CPU time per request | 10ms (free) | 300,000ms (paid) |
+
+### Durable Object Bindings
+
+Each binding creates a `DurableObjectNamespace` accessible via `env.BINDING_NAME`:
+- `name`: The binding name in your code (e.g., `env.CHAT_ROOM`)
+- `class_name`: The exported class name in your source code
+
+### Migrations
+
+Migrations track Durable Object schema changes:
+- `new_sqlite_classes`: New DO classes that use SQLite storage
+- `new_classes`: New DO classes (without SQLite)
+- `deleted_classes`: Classes being removed
+- Tags must be sequential and never reused
+
+### Secrets Management
+
+```bash
+# Upload individual secrets
+wrangler secret put FIREBASE_PRIVATE_KEY
+
+# Upload from .env file (script)
+while IFS='=' read -r key value; do
+  echo "$value" | wrangler secret put "$key"
+done < .env.secrets
+```
+
+---
+
+## Examples
+
+### Example 1: Adding a New Durable Object
+
+```toml
+# 1. Add binding
+[[durable_objects.bindings]]
+name = "TASK_EXECUTOR"
+class_name = "TaskExecutor"
+
+# 2. Add migration (use next sequential tag)
+[[migrations]]
+tag = "v3"
+new_sqlite_classes = ["TaskExecutor"]
+```
+
+### Example 2: Removing a Durable Object
+
+```toml
+# Migration to delete — add this, don't remove the binding yet
+[[migrations]]
+tag = "v4"
+deleted_classes = ["TaskExecutor"]
+
+# After deploying, remove the binding:
+# [[durable_objects.bindings]]
+# name = "TASK_EXECUTOR"
+# class_name = "TaskExecutor"
+```
+
+### Example 3: Custom Domain Route
+
+```toml
+# Route to custom domain
+[[routes]]
+pattern = "app.example.com/*"
+zone_name = "example.com"
+```
+
+---
+
+## Benefits
+
+### 1. Declarative Configuration
+All infrastructure described in a single, version-controlled file.
+
+### 2. Type-Safe Bindings
+Generate TypeScript types with `wrangler types` for full type safety.
+
+### 3. Sequential Migrations
+Durable Object schema changes are tracked and applied in order.
+
+### 4. Edge Observability
+Built-in logging and invocation tracking without external services.
+
+---
+
+## Trade-offs
+
+### 1. Rate Limiting Uses unsafe.bindings
+**Downside**: The `unsafe.bindings` API may change in future Cloudflare versions.
+**Mitigation**: Abstract rate limiting behind utility functions for easy migration.
+
+### 2. No Environment Inheritance
+**Downside**: No built-in way to share config between staging and production.
+**Mitigation**: Use separate wrangler.toml files or environment sections.
+
+---
+
+## Anti-Patterns
+
+### ❌ Anti-Pattern 1: Secrets in wrangler.toml
+
+```toml
+# ❌ BAD: Secrets in config file (committed to git!)
+[vars]
+FIREBASE_PRIVATE_KEY = "-----BEGIN PRIVATE KEY-----..."
+
+# ✅ GOOD: Use wrangler secret
+# wrangler secret put FIREBASE_PRIVATE_KEY
+```
+
+### ❌ Anti-Pattern 2: Reusing Migration Tags
+
+```toml
+# ❌ BAD: Reusing tag "v1" after changing it
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["ChatRoom", "UploadManager"]  # Changed!
+
+# ✅ GOOD: Sequential tags, never modified
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["ChatRoom"]
+
+[[migrations]]
+tag = "v2"
+new_sqlite_classes = ["UploadManager"]
+```
+
+### ❌ Anti-Pattern 3: Missing nodejs_compat
+
+```toml
+# ❌ BAD: Missing Node.js compatibility (crypto, Buffer, etc. won't work)
+compatibility_flags = []
+
+# ✅ GOOD: Enable Node.js compatibility
+compatibility_flags = ["nodejs_compat"]
+```
+
+---
+
+## Related Patterns
+
+- **[Durable Objects WebSocket](./tanstack-cloudflare.durable-objects-websocket.md)**: DO bindings and migrations
+- **[Rate Limiting](./tanstack-cloudflare.rate-limiting.md)**: Rate limiter bindings
+- **[Auth Session Management](./tanstack-cloudflare.auth-session-management.md)**: Secret management for auth keys
+
+---
+
+## Checklist for Implementation
+
+- [ ] `name` set to your worker name
+- [ ] `main` points to server entry point
+- [ ] `compatibility_date` set to recent date
+- [ ] `nodejs_compat` flag enabled
+- [ ] CPU limits configured for paid plan
+- [ ] Observability and invocation logs enabled
+- [ ] All Durable Objects have bindings
+- [ ] Migrations use sequential, never-reused tags
+- [ ] Rate limiters configured per endpoint category
+- [ ] Secrets stored via `wrangler secret`, never in config
+- [ ] Env types generated or manually maintained
+
+---
+
+**Status**: Stable - Essential configuration for Cloudflare Workers deployment
+**Recommendation**: Review and customize for every new TanStack Start + Cloudflare project
+**Last Updated**: 2026-02-28
+**Contributors**: Patrick Michaelsen