분산 배포에서 revalidateTag가 전파되지 않을 때 — Next.js 커스텀 캐시 핸들러로 softTags 무효화 완성하기

_N_T_/layout
_N_T_/blog/layout
_N_T_/blog/hello/layout
_N_T_/blog/hello

// ⚠️ updateTags, refreshTags, getExpiration은 현재(2025년 기준) Next.js 내부 API입니다.
// 공식 문서에 stable로 표기되기 전까지는 내부 훅으로 취급하고,
// Next.js 버전 업그레이드 시 changelog에서 시그니처 변경 여부를 반드시 확인하세요.
interface CacheHandler {
  get(cacheKey: string, softTags: string[]): Promise<CacheEntry | undefined>;
  set(cacheKey: string, value: ReadableStream, options: CacheOptions): Promise<void>;
  // 분산 환경 원격 핸들러 전용 훅
  getExpiration(tags: string[]): Promise<number>;       // 태그 중 최신 무효화 timestamp 반환
  updateTags(tags: string[], expireAt: number): Promise<void>; // revalidateTag 호출 시 실행
  refreshTags(): Promise<void>;                         // 각 요청 전 공유 저장소와 동기화
}

// cache-handler.ts
// ⚠️ 아래 경로는 Next.js 내부 경로 import입니다.
// 버전 업그레이드 시 경로가 변경될 수 있으므로, 공식 export 경로가 생기면 교체하세요.
import type { CacheHandler, CacheEntry } from 'next/dist/server/lib/cache-handlers/types';
 
// storage는 캐시 엔트리를 실제로 저장하는 저장소입니다.
// 메모리 Map, Redis, 파일시스템 등 어떤 구현체든 사용할 수 있습니다.
// 예시: const storage = new Map<string, CacheEntry>();
declare const storage: { get(key: string): Promise<CacheEntry | undefined> };
 
export class MyCacheHandler implements CacheHandler {
  private tagTimestamps = new Map<string, number>();
 
  async get(cacheKey: string, softTags: string[]): Promise<CacheEntry | undefined> {
    const entry = await storage.get(cacheKey);
    if (!entry) return undefined;
 
    const softTagExpiration = await this.getExpiration(softTags);
 
    // ⚠️ softTagExpiration과 entry.timestamp의 단위(밀리초 vs 초)가 반드시 일치해야 합니다.
    // 단위가 다르면 항상 stale 처리되거나 절대 stale 처리되지 않는 조용한 버그가 발생합니다.
    if (softTagExpiration > entry.timestamp) {
      // softTag가 더 최근에 무효화됨 → 엔트리를 stale 처리
      return undefined;
    }
 
    return entry;
  }
 
  async getExpiration(tags: string[]): Promise<number> {
    return Math.max(0, ...tags.map(t => this.tagTimestamps.get(t) ?? 0));
  }
 
  async updateTags(tags: string[], expireAt: number): Promise<void> {
    // revalidateTag() 호출 시 Next.js가 내부적으로 이 메서드를 실행합니다.
    for (const tag of tags) {
      this.tagTimestamps.set(tag, expireAt);
    }
  }
 
  async refreshTags(): Promise<void> {
    // 각 요청 시작 전 호출됩니다.
    // 단일 인스턴스에서는 구현이 필요 없고, 분산 환경에서 공유 저장소와 동기화합니다.
  }
}

// redis-cache-handler.ts
import { createClient } from 'redis';
 
// Redis 클라이언트는 모듈 수준에서 초기화하고,
// 애플리케이션 시작 시 await redis.connect()를 호출해야 합니다.
// 연결 오류는 redis.on('error', handler)로 별도 처리하는 것을 권장합니다.
const redis = createClient({ url: process.env.REDIS_URL });
 
const TAG_PREFIX = 'tag:';
 
export class RedisCacheHandler implements CacheHandler {
  private localTagCache = new Map<string, number>();
 
  async updateTags(tags: string[], expireAt: number): Promise<void> {
    // revalidateTag() 호출 시 Redis에 무효화 시각을 기록합니다.
    // pipeline(multi)으로 묶어 네트워크 왕복을 최소화합니다.
    const pipeline = redis.multi();
    for (const tag of tags) {
      pipeline.set(`${TAG_PREFIX}${tag}`, String(expireAt));
    }
    await pipeline.exec();
  }
 
  async refreshTags(): Promise<void> {
    // 매 요청 전 Redis에서 전체 태그 상태를 로컬 캐시에 동기화합니다.
    // ⚠️ 이 메서드가 throw하면 요청 자체가 실패하므로 반드시 try/catch 처리해야 합니다.
    try {
      // ⚠️ redis.keys()는 O(N) blocking 명령으로 프로덕션에서 절대 사용하면 안 됩니다.
      //    SCAN을 사용해 비blocking 방식으로 키를 순회해야 합니다.
      const tagKeys: string[] = [];
      let cursor = 0;
      do {
        const result = await redis.scan(cursor, {
          MATCH: `${TAG_PREFIX}*`,
          COUNT: 100,
        });
        cursor = result.cursor;
        tagKeys.push(...result.keys);
      } while (cursor !== 0);
 
      for (const key of tagKeys) {
        const value = await redis.get(key);
        if (value) {
          const tag = key.slice(TAG_PREFIX.length);
          this.localTagCache.set(tag, Number(value));
        }
      }
    } catch (err) {
      console.error('refreshTags failed, using stale local state:', err);
      // Redis 장애 시 마지막으로 알려진 로컬 태그 상태로 서비스를 계속 유지합니다.
    }
  }
 
  async getExpiration(tags: string[]): Promise<number> {
    return Math.max(0, ...tags.map(t => this.localTagCache.get(t) ?? 0));
  }
}

// next.config.ts
import type { NextConfig } from 'next';
 
const config: NextConfig = {
  cacheHandlers: {
    default: require.resolve('./cache-handler'),       // 'use cache' 대상
    remote: require.resolve('./redis-cache-handler'),  // 'use cache: remote' 대상
  },
};
 
export default config;

// app/actions.ts
'use server';
 
import { cacheTag } from 'next/cache';
import { revalidateTag, updateTag } from 'next/cache';
 
// 태그 선언 — 'use cache' 디렉티브가 있는 함수 내부에서만 유효합니다.
// categoryId처럼 동적 값을 태그에 포함하면 특정 카테고리만 선택적으로 무효화할 수 있습니다.
async function getProducts(categoryId: string) {
  'use cache';
  cacheTag('products', `products:category:${categoryId}`);
  return await db.products.findAll({ where: { categoryId } });
}
 
// 즉시 반영이 필요한 경우 (Server Action 전용)
export async function deleteProduct(id: string) {
  await db.products.delete(id);
  // 다음 요청은 캐시 없이 데이터 소스를 직접 조회합니다.
  updateTag('products');
}
 
// 백그라운드 갱신으로 충분한 경우
export async function triggerRevalidate() {
  // 현재 사용자에게는 구 데이터를 즉시 반환하고, 다음 요청부터 신규 데이터를 제공합니다.
  revalidateTag('products');
}