Route Handlers vs Server Actions — Why 3 Cached GET Routes Cost $0 and 3 Uncacheable Ones Cost $400/mo

// ============================================
// Cacheable GET Route
// ============================================

// app/api/users/[userId]/stats/route.ts
// ✅ CACHEABLE — only reads URL params, no headers/cookies

import { NextResponse } from 'next/server'

export async function GET(
  request: Request,
  { params }: { params: Promise<{ userId: string }> }
) {
  const { userId } = await params

  // This fetch is cacheable — depends only on userId
  const stats = await fetch(
    `https://api.internal.io/users/${userId}/stats`,
    { next: { revalidate: 300 } } // Cache for 5 minutes
  )

  if (!stats.ok) {
    return NextResponse.json(
      { error: 'Stats not found' },
      { status: 404 }
    )
  }

  const data = await stats.json()

  return NextResponse.json(data, {
    status: 200,
    headers: {
      'Cache-Control': 'public, max-age=300, s-maxage=300',
    }
  })
}

// ============================================
// UNCACHEABLE GET Route (reads auth header)
// ============================================

// app/api/dashboard/stats/route.ts
// ❌ UNCACHEABLE — reads authorization header

export async function GET(request: Request) {
  // Reading headers makes this route dynamic
  const authHeader = request.headers.get('authorization')

  if (!authHeader) {
    return NextResponse.json(
      { error: 'Unauthorized' },
      { status: 401 }
    )
  }

  const userId = await authenticate(authHeader)

  // Even though fetch is the same, the route is dynamic
  const stats = await fetch(
    `https://api.internal.io/users/${userId}/stats`,
    { next: { revalidate: 300 } }
  )

  return NextResponse.json(await stats.json())
}

// Cost difference:
// Cacheable: 1 compute unit for first request, $0 for next 999,999
// Uncacheable: 1 compute unit for EVERY request — 1M = ~$130 at Vercel pricing

// ============================================
// Time-Based Revalidation
// ============================================

// app/api/products/route.ts
export async function GET() {
  const products = await fetch('https://api.internal.io/products', {
    next: { revalidate: 3600 } // Refresh every hour
  })

  return NextResponse.json(await products.json())
}

// Alternative: segment-level revalidation
export const revalidate = 3600 // All fetch calls in this route use 3600

// ============================================
// Event-Driven Revalidation (Tags)
// ============================================

// app/api/orders/[userId]/route.ts
// Fetch with tags for targeted invalidation

export async function GET(
  request: Request,
  { params }: { params: Promise<{ userId: string }> }
) {
  const { userId } = await params

  const orders = await fetch(
    `https://api.internal.io/orders/${userId}`,
    {
      next: {
        tags: [`orders-${userId}`, 'orders-global'],
        revalidate: 86400, // Max cache 24h, but tags refresh sooner
      }
    }
  )

  return NextResponse.json(await orders.json())
}

// app/orders/actions.ts (Server Action)
// Invalidate tag when data changes
'use server'

import { revalidateTag } from 'next/cache'

export async function createOrder(formData: FormData) {
  const order = await fetch('https://api.internal.io/orders', {
    method: 'POST',
    body: formData,
  })

  if (order.ok) {
    // Immediately invalidate all order caches
    revalidateTag('orders-global')
  }

  return { success: order.ok }
}

// ============================================
// No Cache (Dynamic Data)
// ============================================

// app/api/live-prices/route.ts
export const dynamic = 'force-dynamic'
// OR
export const revalidate = 0

// Forces every request to run fresh
// Use for real-time data where cache is unacceptable

// ============================================
// Hybrid: Route Handler + Server Action
// ============================================

// app/api/orders/route.ts
// Route handler — accessible from mobile app AND internal Server Action

export async function POST(request: Request) {
  const body = await request.json()

  // Validate
  if (!body.userId || !body.items || body.items.length === 0) {
    return NextResponse.json(
      { error: 'Invalid order' },
      { status: 400 }
    )
  }

  // Create order in database
  const order = await createOrderInDb(body)

  // Invalidate cache
  revalidateTag(`orders-${body.userId}`)
  revalidateTag('orders-global')

  return NextResponse.json(order, { status: 201 })
}

// app/orders/actions.ts
// Server Action — called from form submission in the web app
'use server'

import { redirect } from 'next/navigation'

export async function submitOrder(formData: FormData) {
  const items = JSON.parse(formData.get('items') as string)

  // Call the same route handler internally
  const response = await fetch('https://internal.url/api/orders', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userId: formData.get('userId'),
      items,
    }),
  })

  if (!response.ok) {
    const error = await response.json()
    return { error: error.message }
  }

  redirect('/orders/confirmation')
}

// app/components/OrderForm.tsx
// Client component calling Server Action
'use client'

import { submitOrder } from '@/app/orders/actions'

export function OrderForm({ userId }: { userId: string }) {
  return (
    <form action={submitOrder}>
      <input type="hidden" name="userId" value={userId} />
      <input type="hidden" name="items" />
      <button type="submit">Place Order</button>
    </form>
  )
}

// ============================================
// Streaming Response Example (SSE)
// ============================================

// app/api/stream/events/route.ts

export async function GET() {
  const encoder = new TextEncoder()

  const stream = new ReadableStream({
    async start(controller) {
      // Send initial connection event
      controller.enqueue(
        encoder.encode('data: {"event": "connected"}\n\n')
      )

      // Simulate event stream
      const events = [
        { type: 'order_created', id: 'ORD-001' },
        { type: 'payment_received', id: 'PAY-001' },
        { type: 'inventory_updated', id: 'INV-001' },
      ]

      for (const event of events) {
        // Wait between events (simulate real-time)
        await new Promise(resolve => setTimeout(resolve, 1000))

        controller.enqueue(
          encoder.encode(`data: ${JSON.stringify(event)}\n\n`)
        )
      }

      // Close stream
      controller.close()
    },
  })

  return new Response(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
    },
  })
}

// ============================================
// Streaming JSON (Chunked)
// ============================================

// app/api/stream/large-dataset/route.ts

export async function GET() {
  const encoder = new TextEncoder()

  const stream = new ReadableStream({
    async start(controller) {
      // Stream header
      controller.enqueue(encoder.encode('{"data": ['))

      for (let i = 0; i < 10000; i++) {
        const item = JSON.stringify({ id: i, name: `Item ${i}` })
        controller.enqueue(encoder.encode(item))

        if (i < 9999) {
          controller.enqueue(encoder.encode(','))
        }

        // Yield every 100 items to avoid blocking
        if (i % 100 === 0) {
          await new Promise(resolve => setTimeout(resolve, 0))
        }
      }

      // Stream footer
      controller.enqueue(encoder.encode(']}'))
      controller.close()
    },
  })

  return new Response(stream, {
    headers: {
      'Content-Type': 'application/json',
    },
  })
}

// ============================================
// Route Handler Security Helpers
// ============================================

// lib/api-utils.ts
import { NextResponse } from 'next/server'
import { z } from 'zod'

export interface ApiResponse<T = unknown> {
  data?: T
  error?: string
}

// CORS headers helper
export function corsHeaders(origin?: string | null) {
  const allowedOrigins = [
    'https://example.com',
    'https://app.example.com',
  ]

  const origin_ = origin && allowedOrigins.includes(origin)
    ? origin
    : 'https://example.com'

  return {
    'Access-Control-Allow-Origin': origin_,
    'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    'Access-Control-Max-Age': '86400',
  }
}

// Auth helper — validate bearer token
export async function validateAuth(
  request: Request
): Promise<{ userId: string } | NextResponse> {
  const authHeader = request.headers.get('authorization')

  if (!authHeader?.startsWith('Bearer ')) {
    return NextResponse.json(
      { error: 'Missing or invalid authorization header' },
      { status: 401, headers: corsHeaders(request.headers.get('origin')) }
    ) as NextResponse<ApiResponse>
  }

  const token = authHeader.slice(7)

  try {
    const { payload } = await jwtVerify(
      token,
      new TextEncoder().encode(process.env.JWT_SECRET!)
    )

    return { userId: payload.sub as string }
  } catch {
    return NextResponse.json(
      { error: 'Invalid or expired token' },
      { status: 401, headers: corsHeaders(request.headers.get('origin')) }
    ) as NextResponse<ApiResponse>
  }
}

// Rate limiter helper (requires Upstash Redis or similar)
// import { Ratelimit } from '@upstash/ratelimit'
// import { Redis } from '@upstash/redis'
//
// const ratelimit = new Ratelimit({
//   redis: Redis.fromEnv(),
//   limiter: Ratelimit.slidingWindow(10, '10 s'),
// })
//
// export async function checkRateLimit(
//   identifier: string
// ): Promise<{ success: boolean }> {
//   const { success } = await ratelimit.limit(identifier)
//   return { success }
// }

// Response helpers
export function successResponse<T>(
  data: T,
  status = 200,
  origin?: string | null
) {
  return NextResponse.json(
    { data },
    { status, headers: corsHeaders(origin) }
  )
}

export function errorResponse(
  message: string,
  status = 400,
  origin?: string | null
) {
  return NextResponse.json(
    { error: message },
    { status, headers: corsHeaders(origin) }
  )
}

// Example route using helpers:
// app/api/orders/route.ts
// export async function POST(request: Request) {
//   const auth = await validateAuth(request)
//   if (auth instanceof NextResponse) return auth
//
//   const body = await request.json()
//   const schema = z.object({
//     items: z.array(z.object({
//       productId: z.string(),
//       quantity: z.number().min(1).max(100),
//     })).min(1).max(50),
//   })
//
//   const parsed = schema.safeParse(body)
//   if (!parsed.success) {
//     return errorResponse(parsed.error.message, 400)
//   }
//
//   const order = await createOrder(auth.userId, parsed.data)
//   return successResponse(order, 201)
// }

// ============================================
// Route Handler Complete Reference
// ============================================

// app/api/products/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server'

export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params

  // Read search params (makes route dynamic)
  const { searchParams } = request.nextUrl
  const includeReviews = searchParams.get('includeReviews')

  const product = await fetch(`https://api.internal.io/products/${id}`)

  if (!product.ok) {
    return NextResponse.json(
      { error: 'Product not found' },
      { status: 404 }
    )
  }

  return NextResponse.json(await product.json())
}

export async function POST(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params
  const body = await request.json()

  // POST is never cached — always runs
  const updated = await fetch(`https://api.internal.io/products/${id}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  })

  return NextResponse.json(await updated.json(), { status: 200 })
}

export async function DELETE(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params

  await fetch(`https://api.internal.io/products/${id}`, {
    method: 'DELETE',
  })

  return NextResponse.json(
    { success: true },
    { status: 200 }
  )
}

// Handle OPTIONS preflight for CORS
export async function OPTIONS(request: NextRequest) {
  return new Response(null, {
    status: 204,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  })
}

// Segment config options
export const dynamic = 'auto' // default — cache if possible
export const dynamic = 'force-dynamic' // never cache
export const dynamic = 'force-static' // force cache (even with dynamic APIs — error if used)
export const revalidate = 3600 // time-based revalidation for all fetches
export const runtime = 'nodejs' // 'nodejs' | 'edge'
export const preferredRegion = 'iad1' // deploy to specific region

// ============================================
// Route Handler Cost Calculator
// ============================================

// Using Vercel Pro pricing (approximate Q2 2026)
// Edge Functions: included 500K invocations, $2/M after
// Serverless: included 100GB-hours, $0.18/GB-hour after

interface RouteCost {
  type: 'cached-get' | 'uncached-get' | 'post'
  monthlyRequests: number
  avgExecutionMs: number
}

function calculateMonthlyCost(route: RouteCost): number {
  const { type, monthlyRequests, avgExecutionMs } = route

  if (type === 'cached-get') {
    // Only first request per cache miss pays
    const revalidationInterval = 3600 // 1 hour
    const cacheMissesPerMonth = (30 * 24 * 3600) / revalidationInterval
    const executions = cacheMissesPerMonth
    return (executions * avgExecutionMs * 0.000002) / 1000
  }

  if (type === 'uncached-get') {
    // Every request pays
    const computeCost = (monthlyRequests * avgExecutionMs * 0.000002) / 1000
    // Edge function cost: first 500K free, then $2/M
    const edgeCost = Math.max(0, (monthlyRequests - 500000) / 1000000) * 2
    return computeCost + edgeCost
  }

  // POST - every request pays + DB write
  const computeCost = (monthlyRequests * avgExecutionMs * 0.000002) / 1000
  const dbCost = monthlyRequests * 0.0001 // Approximate DB write cost
  return computeCost + dbCost
}

// Example: 3 uncacheable GET routes
const uncacheable: RouteCost[] = [
  { type: 'uncached-get', monthlyRequests: 1_000_000, avgExecutionMs: 120 },
  { type: 'uncached-get', monthlyRequests: 1_000_000, avgExecutionMs: 150 },
  { type: 'uncached-get', monthlyRequests: 1_000_000, avgExecutionMs: 100 },
]

const uncacheableTotal = uncacheable
  .map(calculateMonthlyCost)
  .reduce((a, b) => a + b, 0)

console.log(`3 uncacheable GET routes: $${uncacheableTotal.toFixed(2)}/month`)
// Output: ~$396.00

// Same data as cacheable (userId in URL path)
const cacheable: RouteCost[] = [
  { type: 'cached-get', monthlyRequests: 1_000_000, avgExecutionMs: 120 },
  { type: 'cached-get', monthlyRequests: 1_000_000, avgExecutionMs: 150 },
  { type: 'cached-get', monthlyRequests: 1_000_000, avgExecutionMs: 100 },
]

const cacheableTotal = cacheable
  .map(calculateMonthlyCost)
  .reduce((a, b) => a + b, 0)

console.log(`3 cached GET routes: $${cacheableTotal.toFixed(3)}/month`)
// Output: ~$0.006