Next.js Redis 캐시 핸들러 직접 만들기

// cache-handler.mjs (사용자 코드)
import { LegacyCacheHandler } from "@mirunamu/next-redis-cache";
 
const buildId = process.env.BUILD_ID || "default";
 
LegacyCacheHandler.onCreation(async () => {
  if (process.env.NEXT_PHASE === "phase-production-build" || !process.env.REDIS_URL) {
    return null; // 빌드 타임이거나 Redis URL이 없으면 null → Redis 없이 동작
  }
  const { createClient } = await import("@redis/client");
  const client = createClient({ url: process.env.REDIS_URL });
  await client.connect();
  return { client, keyPrefix: `myapp:${buildId}:` };
});
 
export default LegacyCacheHandler;

// legacy-handler.ts
static async #ensureConfigured(): Promise<void> {
  if (LegacyCacheHandler.#configured) return;
 
  if (!LegacyCacheHandler.#configTask) {
    LegacyCacheHandler.#configTask = (async () => {
      try {
        await LegacyCacheHandler.#init();
      } finally {
        LegacyCacheHandler.#configTask = undefined;
      }
    })();
  }
 
  await LegacyCacheHandler.#configTask;
}

async get(cacheKey: string, _ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null> {
  await LegacyCacheHandler.#ensureConfigured();
  const client = LegacyCacheHandler.#client;
  const tm = LegacyCacheHandler.#tagManager;
  if (!client || !tm) return null;
 
  // 1단계: Redis에서 값 조회
  const raw = await withTimeout(
    client.get(LegacyCacheHandler.#keyPrefix + cacheKey),
    LegacyCacheHandler.#timeoutMs
  );
  if (!raw) return null;
 
  const stored: StoredCacheValue = JSON.parse(raw);
  if (stored.value) convertStringsToBuffers(stored.value); // base64 → Buffer 복원
 
  // 2단계: 태그 항목 존재 확인
  const hasEntry = await tm.hasTagEntry(cacheKey);
  if (!hasEntry) {
    await withTimeout(client.unlink(LegacyCacheHandler.#keyPrefix + cacheKey), LegacyCacheHandler.#timeoutMs);
    return null; // orphan 키 — 태그 정보가 없으면 무효
  }
 
  // 3단계: lifespan 만료 확인
  if (stored.lifespan && stored.lifespan.expireAt < Math.floor(Date.now() / 1000)) {
    return null;
  }
 
  // 4단계: 태그 revalidation 확인
  const softTags = (_ctx as Record<string, unknown>)?.softTags as string[] | undefined;
  const combinedTags = [...(stored.tags ?? []), ...(softTags ?? [])];
  if (await tm.isStale(combinedTags, stored.lastModified)) {
    await withTimeout(client.unlink(LegacyCacheHandler.#keyPrefix + cacheKey), LegacyCacheHandler.#timeoutMs);
    return null;
  }
 
  return stored; // 모든 검증 통과 → 캐시 히트
}

async set(cacheKey: string, data: unknown, ctx?: Record<string, unknown>): Promise<void> {
  // 태그 추출: ctx.tags가 있으면 사용, 없으면 headers에서 추출
  const tags: string[] =
    (ctx?.tags as string[]) ??
    getTagsFromHeaders((data as Record<string, unknown>)?.headers);
 
  // revalidate 값 결정
  const revalidate = resolveRevalidate(data, ctx ?? {});
  const lastModified = Math.round((ctx?.internal_lastModified as number) ?? Date.now());
  const lifespan = getLifespan(lastModified, revalidate, ...);
 
  // 이미 만료된 값은 저장하지 않음
  if (Date.now() > lifespan.expireAt * 1000) return;
 
  // Buffer → base64 변환 (Redis는 문자열만 저장 가능)
  const valueForStorage = data ? { ...(data as object) } : null;
  if (valueForStorage) parseBuffersToStrings(valueForStorage);
 
  // Redis 저장 + 태그 등록 + TTL 등록을 병렬 실행
  await Promise.all([
    client.set(fullKey, serialized, { EX: ttlSeconds }),
    tm.setTags(cacheKey, tags),
    tm.setTtl(cacheKey, lifespan.expireAt),
  ]);
}

async revalidateTag(tag: string): Promise<void> {
  // implicit tag만 타임스탬프 기록
  if (isImplicitTag(tag)) {
    await this.client.hSet(this.revalidatedTagsKey, tag, Date.now().toString());
  }
 
  // 모든 태그에 대해: sharedTags를 스캔하여 해당 태그를 포함한 캐시 키를 찾아 삭제
  const keysToDelete: string[] = [];
  const fieldsToDelete: string[] = [];
  let cursor = "0";
  do {
    const result = await this.client.hScan(this.sharedTagsKey, cursor, { COUNT: 10000 });
    for (const { field, value } of result.entries) {
      const tags = JSON.parse(value) as string[];
      if (tags.includes(tag)) {
        keysToDelete.push(this.keyPrefix + field);
        fieldsToDelete.push(field);
      }
    }
    cursor = result.cursor;
  } while (cursor !== "0");
 
  // 캐시 키 + 태그 항목 + TTL 항목을 일괄 삭제
  await Promise.all([
    this.client.unlink(keysToDelete),
    this.client.hDel(this.sharedTagsKey, fieldsToDelete),
    this.client.hDel(this.sharedTagsTtlKey, fieldsToDelete),
  ]);
}

// buffer-utils.ts
export function parseBuffersToStrings(value: any): void {
  if (value.kind === "APP_ROUTE") {
    // Route Handler의 응답 body
    if (Buffer.isBuffer(value.body)) {
      value.body = value.body.toString("base64");
    }
  } else if (value.kind === "APP_PAGE") {
    // App Page의 RSC payload
    if (Buffer.isBuffer(value.rscData)) {
      value.rscData = value.rscData.toString("base64");
    }
    // Segment별 RSC 데이터 (Map<string, Buffer> → Record<string, string>)
    if (value.segmentData instanceof Map) {
      const entries = value.segmentData as Map<string, Buffer>;
      value.segmentData = Object.fromEntries(
        [...entries.entries()].map(([key, val]) => [key, val.toString("base64")])
      );
    }
  }
}

// use-cache-handler.ts — set()
const entry = await pendingEntry;
 
// stream을 두 갈래로 분기: 하나는 저장용, 하나는 원본 보존
const [forStorage, preserved] = entry.value.tee();
entry.value = preserved; // Next.js가 이후에도 이 stream을 소비할 수 있도록 원본 교체
 
// 저장용 stream을 Buffer로 변환 → base64 인코딩
const buffer = await streamToBuffer(forStorage);
const data = buffer.toString("base64");

// stream-utils.ts
export function bufferToStream(buffer: Buffer): ReadableStream<Uint8Array> {
  return new ReadableStream<Uint8Array>({
    start(controller) {
      controller.enqueue(new Uint8Array(buffer));
      controller.close();
    },
  });
}

const pendingSets = new Map<string, Promise<void>>();
 
const handler: CacheHandler = {
  async get(cacheKey: string, softTags: string[]) {
    // 같은 키에 대한 set()이 진행 중이면 완료를 기다림
    const pending = pendingSets.get(cacheKey);
    if (pending) {
      await pending;
    }
    // set() 완료 후 Redis에서 읽기
    const raw = await exec(client.get(keyPrefix + cacheKey));
    // ...
  },
 
  async set(cacheKey: string, pendingEntry: Promise<CacheEntry>) {
    // set 시작을 pendingSets에 등록
    let resolvePending: () => void = () => {};
    const pendingPromise = new Promise<void>((resolve) => {
      resolvePending = resolve;
    });
    pendingSets.set(cacheKey, pendingPromise);
 
    try {
      const entry = await pendingEntry;
      // ... Redis에 저장
    } finally {
      resolvePending();  // 대기 중인 get()을 깨움
      pendingSets.delete(cacheKey);
    }
  },
};

async refreshTags(): Promise<void> {
  // Redis는 분산 저장소이므로 모든 인스턴스가 동일한 Hash를 읽습니다.
  // 별도의 동기화가 필요 없어 no-op으로 처리합니다.
}

// 사용자의 instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { registerInitialCache } = await import(
      "@mirunamu/next-redis-cache/instrumentation"
    );
    const CacheHandler = (await import("../cache-handler.mjs")).default;
    await registerInitialCache(CacheHandler, { setOnlyIfNotExists: true });
  }
}

// instrumentation.ts (라이브러리 내부)
const manifest: PrerenderManifest = JSON.parse(
  await fs.readFile(manifestPath, "utf-8")
);
 
for (const [route, routeInfo] of Object.entries(manifest.routes)) {
  if (route.startsWith("/_")) continue;  // 내부 라우트 스킵
  if (!routeInfo.dataRoute) continue;     // App Route(dataRoute=null)는 프리워밍 대상에서 제외
 
  const value = await readRouteFromDisk(appDir, route, routeInfo);
  if (!value) continue;
 
  await handler.set(route, value, {
    revalidate: routeInfo.initialRevalidateSeconds,
    setOnlyIfNotExists: true,  // Redis NX 플래그 — 기존 값 덮어쓰기 방지
  });
}

// .next/server/app/docs/architecture/feature-sliced-design.meta
{
  "headers": {
    "x-next-cache-tags": "_N_T_/layout,_N_T_/docs/layout,_N_T_/docs/[...slug]/layout,_N_T_/docs/[...slug]/page,_N_T_/docs/architecture/feature-sliced-design"
  }
}

export async function cleanupOldBuildKeys(options: CleanupOptions): Promise<{ deleted: number }> {
  const { redisUrl, patterns } = options;
  const client = createClient({ url: redisUrl });
  await client.connect();
 
  const allOldKeys: string[] = [];
 
  for (const { scan, keepExact, keepPrefix } of patterns) {
    for await (const key of client.scanIterator({ MATCH: scan, COUNT: 200 })) {
      const k = String(key);
      if (keepExact && k === keepExact) continue;   // 정확히 일치하는 키 보존
      if (keepPrefix && k.startsWith(keepPrefix)) continue;  // 현재 빌드 키 보존
      allOldKeys.push(k);
    }
  }
 
  if (allOldKeys.length > 0) {
    await client.del(allOldKeys);
  }
 
  await client.disconnect();
  return { deleted: allOldKeys.length };
}

// tsup.config.ts
export default defineConfig({
  entry: {
    index: "src/index.ts",           // LegacyCacheHandler
    "use-cache": "src/use-cache.ts", // createUseCacheHandler
    instrumentation: "src/instrumentation.ts", // registerInitialCache, cleanupOldBuildKeys
  },
  format: ["esm", "cjs"],
  dts: true,
  splitting: true,
  clean: true,
  target: "node18",
  external: ["next", "@redis/client"],
});

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}

npx changeset        # 변경 사항 기록
npx changeset version # 버전 범프 + CHANGELOG 생성
npm run release       # 빌드 + npm publish