Next.js 15+ `use cache: remote`와 Upstash Redis로 서버리스 인스턴스 간 캐시 공유 구현하기 — 커스텀 캐시 핸들러 완성 코드 포함

interface CacheHandler {
  get(cacheKey: string, softTags: string[]): Promise<CacheEntry | undefined>
  set(cacheKey: string, pendingEntry: Promise<CacheEntry>): Promise<void>
}
 
interface CacheEntry {
  value: ReadableStream<Uint8Array>  // 직렬화가 필요한 스트림
  tags: string[]
  stale: number
  timestamp: number
  expire: number    // Unix 밀리초 타임스탬프
  revalidate: number
}

// next.config.js
const nextConfig = {
  experimental: {
    dynamicIO: true,
  },
  cacheHandlers: {
    // require.resolve()는 Node.js 모듈 해석 시 실행 환경 기준의 절대 경로를
    // 보장하기 위해 사용합니다. 상대 경로 문자열을 직접 써도 되지만,
    // 모노레포나 빌드 환경에 따라 경로 오류가 발생할 수 있습니다
    default: require.resolve('./cache-handlers/in-memory-handler.js'),
    remote: require.resolve('./cache-handlers/upstash-handler.js'),
  },
}
 
module.exports = nextConfig

// cache-handlers/upstash-handler.js
const { Redis } = require('@upstash/redis')
 
const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL,
  token: process.env.UPSTASH_REDIS_REST_TOKEN,
})
 
// 같은 Redis 인스턴스를 스테이징/프로덕션 또는 여러 프로젝트에서 공유한다면
// 환경 변수로 프리픽스를 분리하여 키 충돌을 방지하는 것을 권장합니다
const CACHE_PREFIX = process.env.CACHE_PREFIX ?? 'nextjs:cache:'
const DEFAULT_TTL = 60 * 60 * 24 // 24시간
 
module.exports = class UpstashCacheHandler {
  // 캐시 조회: Redis에서 가져와 ReadableStream으로 복원
  async get(cacheKey, softTags) {
    const stored = await redis.get(CACHE_PREFIX + cacheKey)
    if (!stored) return undefined
 
    const entry = typeof stored === 'string' ? JSON.parse(stored) : stored
 
    // expire가 0이면 만료 없음, 양수이면 현재 시각과 비교
    const now = Date.now()
    if (entry.expire !== 0 && now > entry.expire) return undefined
 
    // TODO: softTags 무효화 검증 미구현
    // softTags에 포함된 태그가 revalidateTag로 무효화된 경우
    // 이 캐시를 반환하면 안 됩니다. 이 로직이 없으면
    // 무효화된 데이터가 계속 반환될 수 있습니다.
    // 구현 방법(무효화된 태그를 Redis에 저장하고 교차 검증)은 다음 글에서 다룹니다.
 
    // Base64 인코딩된 청크를 Uint8Array로 복원 후 ReadableStream 생성
    const chunks = entry.valueChunks.map(
      (chunk) => new Uint8Array(Buffer.from(chunk, 'base64'))
    )
    const value = new ReadableStream({
      start(controller) {
        for (const chunk of chunks) controller.enqueue(chunk)
        controller.close()
      },
    })
 
    return {
      value,
      tags: entry.tags,
      stale: entry.stale,
      timestamp: entry.timestamp,
      expire: entry.expire,
      revalidate: entry.revalidate,
    }
  }
 
  // 캐시 저장: ReadableStream을 직렬화하여 Redis에 저장
  async set(cacheKey, pendingEntry) {
    try {
      // pendingEntry는 Promise이므로 반드시 await
      const entry = await pendingEntry
 
      // Next.js는 응답 스트림이 소비된 후 비동기(fire-and-forget)로
      // 핸들러를 호출합니다. entry.value를 직접 읽어도 안전합니다
      const chunks = []
      const reader = entry.value.getReader()
      while (true) {
        const { done, value } = await reader.read()
        if (done) break
        chunks.push(Buffer.from(value).toString('base64'))
      }
 
      const serialized = {
        valueChunks: chunks,
        tags: entry.tags,
        stale: entry.stale,
        timestamp: entry.timestamp,
        expire: entry.expire,
        revalidate: entry.revalidate,
      }
 
      // expire는 Unix ms 타임스탬프이므로 Redis EX(초 단위)로 변환
      const now = Date.now()
      const ttl = entry.expire
        ? Math.ceil((entry.expire - now) / 1000)
        : DEFAULT_TTL
 
      // expire가 이미 지난 항목은 저장하지 않음
      if (ttl <= 0) return
 
      await redis.set(
        CACHE_PREFIX + cacheKey,
        JSON.stringify(serialized),
        { ex: ttl }
      )
    } catch (err) {
      // Redis 저장 실패는 응답에 영향을 주지 않도록 조용히 처리
      console.error('[UpstashCacheHandler] set 실패:', err)
    }
  }
}

// app/products/page.tsx
import { cacheLife, cacheTag } from 'next/cache'
 
// 이 함수의 결과는 Upstash Redis에 저장됩니다
async function getProducts() {
  'use cache: remote'
  cacheLife('hours')     // stale: 0, revalidate: 3600, expire: 86400
  cacheTag('products')   // revalidateTag('products')로 무효화 가능
 
  const res = await fetch('https://api.example.com/products')
  return res.json()
}
 
export default async function ProductsPage() {
  const products = await getProducts()
  return <ProductList items={products} />
}

// app/actions/products.ts
'use server'
import { revalidateTag } from 'next/cache'
 
// 상품 데이터 변경 시 모든 인스턴스의 원격 캐시를 일괄 무효화
export async function refreshProducts() {
  revalidateTag('products')
}