@prmichaelsen/acp-visualizer 0.1.0 → 0.1.2

package/agent/patterns/tanstack-cloudflare.rate-limiting.md

@@ -1,323 +0,0 @@
-# Rate Limiting Pattern
-
-**Category**: Infrastructure
-**Applicable To**: TanStack Start + Cloudflare Workers applications requiring request throttling
-**Status**: Stable
-
----
-
-## Overview
-
-Cloudflare Workers provides a built-in Rate Limiting API via `unsafe.bindings` in `wrangler.toml`. This pattern documents how to configure rate limiting namespaces for different endpoint categories (auth, API, WebSocket), create a reusable rate limiting utility, and enforce limits in API route handlers.
-
-Rate limiters are configured per-namespace with distinct limits — strict limits for auth endpoints (prevent brute force), moderate limits for API endpoints, and connection-based limits for WebSocket upgrades.
-
----
-
-## When to Use This Pattern
-
-✅ **Use this pattern when:**
-- Need to protect auth endpoints from brute force attacks
-- Want to prevent API abuse
-- Need to limit WebSocket connection frequency
-- Building production applications exposed to the internet
-
-❌ **Don't use this pattern when:**
-- Building internal-only applications with trusted clients
-- Development/testing environments (rate limiting adds friction)
-- Using an external rate limiting service (Cloudflare WAF rules, etc.)
-
----
-
-## Core Principles
-
-1. **Namespace Separation**: Different rate limit tiers for different endpoint categories
-2. **Fail Open**: If the rate limiter errors, allow the request (don't block users due to infra issues)
-3. **User-Based Keys**: Authenticated requests are rate-limited by user ID, unauthenticated by IP
-4. **Standard Headers**: Return `Retry-After`, `X-RateLimit-Limit`, and `X-RateLimit-Remaining` headers
-5. **429 Response**: Consistently return HTTP 429 with JSON error body when rate limited
-
----
-
-## Implementation
-
-### Step 1: Configure Wrangler
-
-```toml
-# wrangler.toml
-
-# Rate Limiting (Cloudflare Workers Rate Limiting API)
-# 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 }  # 5 attempts per minute
-
-[[unsafe.bindings]]
-name = "API_RATE_LIMITER"
-type = "ratelimit"
-namespace_id = "1002"
-simple = { limit = 100, period = 60 }  # 100 requests per minute
-
-[[unsafe.bindings]]
-name = "WS_RATE_LIMITER"
-type = "ratelimit"
-namespace_id = "1003"
-simple = { limit = 10, period = 60 }  # 10 connections per minute
-```
-
-### Step 2: Rate Limiting Utility
-
-```typescript
-// src/lib/rate-limiter.ts
-
-export interface RateLimitConfig {
-  limit: number
-  period: number  // seconds
-  keyPrefix: string
-}
-
-export interface RateLimitResult {
-  success: boolean
-  limit: number
-  remaining: number
-  retryAfter?: number
-}
-
-/**
- * Check rate limit for a request
- */
-export async function checkRateLimit(
-  rateLimiter: any,  // Cloudflare Rate Limiter binding
-  identifier: string,
-  config: RateLimitConfig
-): Promise<RateLimitResult> {
-  const key = `${config.keyPrefix}:${identifier}`
-
-  try {
-    const { success, limit, remaining, retryAfter } = await rateLimiter.limit({ key })
-
-    return { success, limit, remaining, retryAfter }
-  } catch (error) {
-    console.error('[RateLimit] Error checking rate limit:', error)
-    // Fail open — allow request if rate limiter fails
-    return {
-      success: true,
-      limit: config.limit,
-      remaining: config.limit
-    }
-  }
-}
-
-/**
- * Create rate limit error response with standard headers
- */
-export function createRateLimitResponse(result: RateLimitResult): Response {
-  const retryAfter = result.retryAfter ?? 60
-  const limit = result.limit ?? 100
-  const remaining = result.remaining ?? 0
-
-  return new Response(
-    JSON.stringify({
-      error: 'Too many requests',
-      message: 'Rate limit exceeded. Please try again later.',
-      retryAfter
-    }),
-    {
-      status: 429,
-      headers: {
-        'Content-Type': 'application/json',
-        'Retry-After': retryAfter.toString(),
-        'X-RateLimit-Limit': limit.toString(),
-        'X-RateLimit-Remaining': remaining.toString()
-      }
-    }
-  )
-}
-
-/**
- * Get rate limit identifier from request.
- * Uses user ID if authenticated, IP address otherwise.
- */
-export function getRateLimitIdentifier(request: Request, userId?: string): string {
-  if (userId) return `user:${userId}`
-
-  const ip = request.headers.get('cf-connecting-ip') ||
-             request.headers.get('x-forwarded-for') ||
-             'unknown'
-
-  return `ip:${ip}`
-}
-```
-
-### Step 3: Use in API Route
-
-```typescript
-// src/routes/api/auth/session.tsx
-import { createFileRoute } from '@tanstack/react-router'
-import { checkRateLimit, createRateLimitResponse, getRateLimitIdentifier } from '@/lib/rate-limiter'
-
-export const Route = createFileRoute('/api/auth/session')({
-  server: {
-    handlers: {
-      POST: async ({ request, context }) => {
-        const env = context.cloudflare.env as Env
-
-        // Rate limit auth endpoints strictly
-        const identifier = getRateLimitIdentifier(request)
-        const rateLimitResult = await checkRateLimit(
-          env.AUTH_RATE_LIMITER,
-          identifier,
-          { limit: 5, period: 60, keyPrefix: 'auth:session' }
-        )
-
-        if (!rateLimitResult.success) {
-          return createRateLimitResponse(rateLimitResult)
-        }
-
-        // ... handle session creation
-      },
-    },
-  },
-})
-```
-
----
-
-## Rate Limit Tiers
-
-| Namespace | Binding | Limit | Use Case |
-|-----------|---------|-------|----------|
-| Auth | `AUTH_RATE_LIMITER` | 5/min | Login, register, password reset |
-| API | `API_RATE_LIMITER` | 100/min | CRUD operations, data queries |
-| WebSocket | `WS_RATE_LIMITER` | 10/min | WebSocket connection upgrades |
-
----
-
-## Examples
-
-### Example 1: Rate Limiting API Endpoints
-
-```typescript
-// src/routes/api/conversations/create.tsx
-POST: async ({ request, context }) => {
-  const env = context.cloudflare.env as Env
-  const user = await getAuthSession()
-  if (!user) return Response.json({ error: 'Unauthorized' }, { status: 401 })
-
-  const identifier = getRateLimitIdentifier(request, user.uid)
-  const result = await checkRateLimit(
-    env.API_RATE_LIMITER,
-    identifier,
-    { limit: 100, period: 60, keyPrefix: 'api:conversations' }
-  )
-
-  if (!result.success) return createRateLimitResponse(result)
-
-  // ... handle request
-}
-```
-
-### Example 2: Rate Limiting WebSocket Connections
-
-```typescript
-// src/routes/api/chat-ws.tsx
-GET: async ({ request, context }) => {
-  const env = context.cloudflare.env as Env
-  const user = await getAuthSession()
-  if (!user) return new Response('Unauthorized', { status: 401 })
-
-  const identifier = getRateLimitIdentifier(request, user.uid)
-  const result = await checkRateLimit(
-    env.WS_RATE_LIMITER,
-    identifier,
-    { limit: 10, period: 60, keyPrefix: 'ws:chat' }
-  )
-
-  if (!result.success) return createRateLimitResponse(result)
-
-  // Forward to Durable Object for WebSocket upgrade
-  const id = env.CHAT_ROOM.idFromName(user.uid)
-  return env.CHAT_ROOM.get(id).fetch(request)
-}
-```
-
----
-
-## Benefits
-
-### 1. Built-In Infrastructure
-No external services needed — rate limiting runs at Cloudflare's edge.
-
-### 2. Per-Namespace Isolation
-Different limits for different concerns (auth vs API vs WebSocket).
-
-### 3. Fail-Open Safety
-If the rate limiter errors, requests are allowed through — no service disruption.
-
-### 4. Standard HTTP Headers
-Clients can programmatically handle rate limits via `Retry-After` header.
-
----
-
-## Trade-offs
-
-### 1. `unsafe.bindings` Label
-**Downside**: Rate limiting uses Cloudflare's `unsafe.bindings`, which may change in future API versions.
-**Mitigation**: Abstract behind a utility module (as shown) for easy migration.
-
-### 2. Simple Counter Only
-**Downside**: Only supports simple fixed-window rate limiting (not sliding window or token bucket).
-**Mitigation**: Sufficient for most applications. Use external services for advanced algorithms.
-
----
-
-## Anti-Patterns
-
-### ❌ Anti-Pattern: Fail Closed on Rate Limiter Error
-
-```typescript
-// ❌ BAD: Blocks all requests if rate limiter fails
-const result = await rateLimiter.limit({ key })
-// If this throws, the entire request fails
-
-// ✅ GOOD: Fail open
-try {
-  const result = await rateLimiter.limit({ key })
-  if (!result.success) return createRateLimitResponse(result)
-} catch {
-  // Allow request through if rate limiter is unavailable
-}
-```
-
----
-
-## Related Patterns
-
-- **[API Route Handlers](./tanstack-cloudflare.api-route-handlers.md)**: Rate limiting applied in API routes
-- **[Auth Session Management](./tanstack-cloudflare.auth-session-management.md)**: Auth endpoints need strict rate limits
-- **[Durable Objects WebSocket](./tanstack-cloudflare.durable-objects-websocket.md)**: WebSocket connections rate limited
-- **[Wrangler Configuration](./tanstack-cloudflare.wrangler-configuration.md)**: Rate limiter bindings configured in wrangler.toml
-
----
-
-## Checklist for Implementation
-
-- [ ] Rate limiter bindings configured in `wrangler.toml`
-- [ ] Separate namespaces for auth, API, and WebSocket
-- [ ] Utility functions for check, response, and identifier extraction
-- [ ] Auth endpoints use strict limits (5/min)
-- [ ] API endpoints use moderate limits (100/min)
-- [ ] WebSocket connections use connection-based limits (10/min)
-- [ ] Rate limiter errors fail open (allow request)
-- [ ] 429 responses include `Retry-After` header
-- [ ] Rate limit identifier uses user ID when authenticated, IP otherwise
-
----
-
-**Status**: Stable - Production-ready rate limiting for Cloudflare Workers
-**Recommendation**: Use for all production applications exposed to the internet
-**Last Updated**: 2026-02-28
-**Contributors**: Patrick Michaelsen

package/agent/patterns/tanstack-cloudflare.scheduled-tasks.md

@@ -1,338 +0,0 @@
-# Scheduled Tasks Pattern
-
-**Category**: Infrastructure
-**Applicable To**: TanStack Start + Cloudflare Workers applications requiring cron jobs
-**Status**: Stable
-
----
-
-## Overview
-
-Cloudflare Workers supports Cron Triggers — scheduled tasks that run on a configurable schedule without requiring external cron services. This pattern replaces the common Next.js approach of exposing `/api/scheduled/*` endpoints that are hit by external cron services (Vercel Cron, Google Cloud Scheduler, etc.).
-
-With Cron Triggers, the schedule is defined in `wrangler.toml` and the handler is a `scheduled` event in your worker, eliminating the need for external schedulers, API keys for cron endpoints, or separate Cloud Run services.
-
----
-
-## When to Use This Pattern
-
-✅ **Use this pattern when:**
-- Need periodic background tasks (daily digests, reminders, token refresh)
-- Migrating from external cron-triggered API endpoints
-- Want scheduled tasks co-located with your application code
-- Need reliable execution without external scheduler dependencies
-
-❌ **Don't use this pattern when:**
-- Tasks need to run for more than the Workers CPU time limit (300s on paid plan)
-- Tasks require interactive user input
-- Need sub-minute scheduling precision
-
----
-
-## Core Principles
-
-1. **Declarative Schedules**: Cron schedules defined in `wrangler.toml`, not application code
-2. **Event-Based Handler**: Uses `scheduled` event, not HTTP endpoints
-3. **Routing by Cron Expression**: Use `event.cron` to dispatch to the right handler
-4. **Fail-Safe Execution**: Errors are logged but don't crash the worker
-5. **Debug Endpoint**: Keep an HTTP endpoint for manual testing/triggering
-
----
-
-## Implementation
-
-### Step 1: Configure Cron Triggers in wrangler.toml
-
-```toml
-# wrangler.toml
-
-[triggers]
-crons = [
-  "0 7 * * *",     # Daily at 7:00 AM UTC — daily digest
-  "*/15 * * * *",  # Every 15 minutes — clean reminders
-  "0 */6 * * *",   # Every 6 hours — token refresh
-]
-```
-
-### Step 2: Handle Scheduled Events in Server Entry
-
-```typescript
-// src/server.ts (or worker entry point)
-
-export default {
-  // Standard fetch handler for HTTP requests (TanStack Start handles this)
-  fetch: app.fetch,
-
-  // Scheduled handler for cron triggers
-  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
-    ctx.waitUntil(handleScheduledEvent(event, env))
-  },
-}
-
-async function handleScheduledEvent(event: ScheduledEvent, env: Env): Promise<void> {
-  console.log(`[Cron] Triggered: ${event.cron} at ${new Date(event.scheduledTime).toISOString()}`)
-
-  try {
-    switch (event.cron) {
-      case '0 7 * * *':
-        await handleDailyDigest(env)
-        break
-      case '*/15 * * * *':
-        await handleCleanReminders(env)
-        break
-      case '0 */6 * * *':
-        await handleTokenRefresh(env)
-        break
-      default:
-        console.warn(`[Cron] Unknown cron expression: ${event.cron}`)
-    }
-  } catch (error) {
-    console.error(`[Cron] Failed for ${event.cron}:`, error)
-    // Don't rethrow — cron failures should be logged, not crash the worker
-  }
-}
-```
-
-### Step 3: Implement Task Handlers
-
-```typescript
-// src/lib/scheduled/daily-digest.ts
-
-export async function handleDailyDigest(env: Env): Promise<void> {
-  console.log('[DailyDigest] Starting daily digest...')
-
-  // 1. Query data
-  const checkIns = await ReservationDatabaseService.getTodayCheckIns()
-  const checkOuts = await ReservationDatabaseService.getTodayCheckOuts()
-  const unclaimedCleans = await AppointmentDatabaseService.getUnclaimedNextWeek()
-
-  // 2. Build email content
-  const html = buildDigestEmail({
-    checkIns,
-    checkOuts,
-    unclaimedCleans,
-  })
-
-  // 3. Send email
-  await sendEmail({
-    to: env.MANAGER_EMAILS,
-    subject: `Daily Digest — ${new Date().toLocaleDateString()}`,
-    html,
-  })
-
-  console.log('[DailyDigest] Complete')
-}
-```
-
-```typescript
-// src/lib/scheduled/token-refresh.ts
-
-export async function handleTokenRefresh(env: Env): Promise<void> {
-  console.log('[TokenRefresh] Refreshing external API tokens...')
-
-  // Refresh Guesty OAuth token
-  try {
-    const guestyToken = await GuestyAuthService.refreshToken()
-    await GuestyTokenStorage.store(guestyToken)
-    console.log('[TokenRefresh] Guesty token refreshed')
-  } catch (error) {
-    console.error('[TokenRefresh] Guesty refresh failed:', error)
-    // Continue with other refreshes
-  }
-
-  // Refresh other tokens...
-}
-```
-
-### Step 4: Keep Debug HTTP Endpoint
-
-```typescript
-// routes/api/scheduled/daily-digest.tsx
-// Manual trigger for testing — protected by admin auth
-
-import { createFileRoute } from '@tanstack/react-router'
-import { getAuthSession } from '@/lib/auth/server-fn'
-import { handleDailyDigest } from '@/lib/scheduled/daily-digest'
-
-export const Route = createFileRoute('/api/scheduled/daily-digest')({
-  server: {
-    handlers: {
-      POST: async ({ request, context }) => {
-        const user = await getAuthSession()
-        if (!user?.isAdmin) {
-          return new Response(JSON.stringify({ error: 'Forbidden' }), {
-            status: 403,
-            headers: { 'Content-Type': 'application/json' },
-          })
-        }
-
-        const env = context.cloudflare.env as Env
-        const body = await request.json()
-        const { debug = false } = body
-
-        if (debug) {
-          // Return preview data without sending
-          const data = await buildDigestPreview()
-          return new Response(JSON.stringify({ success: true, preview: data }), {
-            headers: { 'Content-Type': 'application/json' },
-          })
-        }
-
-        await handleDailyDigest(env)
-        return new Response(JSON.stringify({ success: true }), {
-          headers: { 'Content-Type': 'application/json' },
-        })
-      },
-    },
-  },
-})
-```
-
----
-
-## Migrating from Next.js Scheduled Endpoints
-
-### Before (Next.js + External Cron)
-
-```
-External Cron (Vercel/GCP)
-  → POST /api/scheduled/daily-digest (with API key auth)
-    → Next.js route handler
-      → Business logic
-```
-
-### After (Cloudflare Cron Triggers)
-
-```
-Cloudflare Cron Trigger (built-in)
-  → scheduled event handler
-    → Business logic
-
-Manual trigger (admin-only):
-  → POST /api/scheduled/daily-digest (with session auth)
-    → Same business logic
-```
-
-### Migration Steps
-
-1. **Extract logic**: Move business logic from Next.js route handler into a standalone function
-2. **Add wrangler cron**: Define the schedule in `wrangler.toml`
-3. **Add scheduled handler**: Wire up the `scheduled` event in your server entry
-4. **Keep HTTP endpoint**: Add an admin-protected manual trigger for testing
-5. **Remove external cron**: Delete external scheduler configuration
-
----
-
-## Cron Expression Reference
-
-| Expression | Schedule |
-|-----------|----------|
-| `* * * * *` | Every minute |
-| `*/15 * * * *` | Every 15 minutes |
-| `0 * * * *` | Every hour |
-| `0 */6 * * *` | Every 6 hours |
-| `0 7 * * *` | Daily at 7:00 AM UTC |
-| `0 7 * * 1-5` | Weekdays at 7:00 AM UTC |
-| `0 0 * * 0` | Weekly on Sunday at midnight |
-| `0 0 1 * *` | Monthly on the 1st at midnight |
-
----
-
-## Benefits
-
-### 1. No External Dependencies
-Schedule lives in `wrangler.toml` — no external cron service to configure or maintain.
-
-### 2. Co-Located Code
-Scheduled tasks and application code deploy together — no version drift.
-
-### 3. Automatic Retries
-Cloudflare retries failed cron triggers automatically.
-
-### 4. Free on All Plans
-Cron Triggers are included in all Cloudflare Workers plans at no additional cost.
-
----
-
-## Trade-offs
-
-### 1. CPU Time Limits
-**Downside**: Tasks are subject to Workers CPU limits (10ms free, 300s paid).
-**Mitigation**: Break long tasks into smaller chunks. Use Durable Objects for long-running work.
-
-### 2. No Sub-Minute Precision
-**Downside**: Minimum interval is 1 minute.
-**Mitigation**: Use Durable Objects `alarm()` for sub-minute scheduling.
-
-### 3. UTC Only
-**Downside**: Cron expressions use UTC, not local time.
-**Mitigation**: Calculate UTC offset for your target timezone.
-
----
-
-## Anti-Patterns
-
-### ❌ Anti-Pattern: Unprotected HTTP Cron Endpoints
-
-```typescript
-// ❌ BAD: No auth on cron endpoint (anyone can trigger it)
-POST: async ({ request }) => {
-  await handleDailyDigest()  // No auth check!
-  return Response.json({ success: true })
-}
-
-// ✅ GOOD: Admin-only access
-POST: async ({ request }) => {
-  const user = await getAuthSession()
-  if (!user?.isAdmin) return Response.json({ error: 'Forbidden' }, { status: 403 })
-  await handleDailyDigest()
-  return Response.json({ success: true })
-}
-```
-
-### ❌ Anti-Pattern: Rethrowing Cron Errors
-
-```typescript
-// ❌ BAD: Rethrowing crashes the worker
-async scheduled(event, env, ctx) {
-  await handleDailyDigest(env)  // If this throws, worker crashes
-}
-
-// ✅ GOOD: Catch and log
-async scheduled(event, env, ctx) {
-  try {
-    await handleDailyDigest(env)
-  } catch (error) {
-    console.error('[Cron] Failed:', error)
-  }
-}
-```
-
----
-
-## Related Patterns
-
-- **[Wrangler Configuration](./tanstack-cloudflare.wrangler-configuration.md)**: Cron triggers configured in wrangler.toml
-- **[Email Service](./tanstack-cloudflare.email-service.md)**: Scheduled tasks commonly send emails
-- **[Third-Party API Integration](./tanstack-cloudflare.third-party-api-integration.md)**: Token refresh as scheduled task
-- **[API Route Handlers](./tanstack-cloudflare.api-route-handlers.md)**: Debug endpoints for manual triggers
-
----
-
-## Checklist for Implementation
-
-- [ ] Cron expressions defined in `wrangler.toml` under `[triggers]`
-- [ ] `scheduled` event handler in server entry point
-- [ ] Dispatch logic based on `event.cron` string
-- [ ] All errors caught and logged (never rethrow)
-- [ ] Business logic in standalone functions (not in handler)
-- [ ] Admin-protected HTTP endpoint for manual testing
-- [ ] Debug mode returns preview without executing
-- [ ] `ctx.waitUntil()` used for async work
-
----
-
-**Status**: Stable - Production-ready scheduled task pattern
-**Recommendation**: Use for all periodic background tasks
-**Last Updated**: 2026-02-28
-**Contributors**: Patrick Michaelsen