@leejpsd/nextjs-cache-handler 0.1.0-rc.1

package/dist/cache-components/index.js

@@ -0,0 +1,1049 @@
+import { createHash } from 'crypto';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/shared/client/adapter-redis.ts
+var adapter_redis_exports = {};
+__export(adapter_redis_exports, {
+  adaptRedisV5: () => adaptRedisV5,
+  createRedisV5Client: () => createRedisV5Client
+});
+function adaptRedisV5(client) {
+  return client;
+}
+function createRedisV5Client(config) {
+  const { createClient } = __require("redis");
+  const useTls = config.tls ?? config.url.startsWith("rediss://");
+  const opts = {
+    url: config.url,
+    socket: {
+      connectTimeout: config.connectTimeout ?? 1500,
+      reconnectStrategy: false,
+      ...useTls ? { tls: true } : {}
+    }
+  };
+  if (config.password !== void 0) opts.password = config.password;
+  return createClient(opts);
+}
+var init_adapter_redis = __esm({
+  "src/shared/client/adapter-redis.ts"() {
+  }
+});
+
+// src/shared/client/adapter-ioredis.ts
+var adapter_ioredis_exports = {};
+__export(adapter_ioredis_exports, {
+  adaptCluster: () => adaptCluster,
+  adaptIoredis: () => adaptIoredis,
+  createIoredisClient: () => createIoredisClient,
+  createIoredisCluster: () => createIoredisCluster
+});
+function adapt(client, isClusterClient = false) {
+  return {
+    get isOpen() {
+      return client.status === "ready";
+    },
+    connect: async () => {
+      if (client.status !== "ready" && client.status !== "connecting") {
+        await client.connect();
+      }
+    },
+    get: (k) => client.get(k),
+    set: (k, v, opts) => opts?.EX !== void 0 ? client.set(k, v, "EX", opts.EX) : client.set(k, v),
+    del: async (keys) => {
+      const arr = Array.isArray(keys) ? keys : [keys];
+      if (arr.length === 0) return 0;
+      return client.del(...arr);
+    },
+    sAdd: async (k, m) => {
+      const arr = Array.isArray(m) ? m : [m];
+      if (arr.length === 0) return 0;
+      return client.sadd(k, ...arr);
+    },
+    sMembers: (k) => client.smembers(k),
+    expire: async (k, s) => {
+      const r = await client.expire(k, s);
+      return r;
+    },
+    mGet: async (keys) => {
+      if (keys.length === 0) return [];
+      return client.mget(...keys);
+    },
+    eval: (script, opts) => client.eval(
+      script,
+      opts.keys.length,
+      ...opts.keys,
+      ...opts.arguments
+    ),
+    evalSha: (sha, opts) => client.evalsha(
+      sha,
+      opts.keys.length,
+      ...opts.keys,
+      ...opts.arguments
+    ),
+    scriptLoad: async (script) => await client.script("LOAD", script),
+    scanIterator: async function* ({ MATCH, COUNT }) {
+      if (isClusterClient) {
+        const cluster = client;
+        for (const node of cluster.nodes("master")) {
+          let cursor = "0";
+          do {
+            const [next, batch] = await node.scan(
+              cursor,
+              "MATCH",
+              MATCH,
+              "COUNT",
+              COUNT ?? 100
+            );
+            cursor = next;
+            if (batch.length > 0) yield batch;
+          } while (cursor !== "0");
+        }
+      } else {
+        const redis = client;
+        let cursor = "0";
+        do {
+          const [next, batch] = await redis.scan(
+            cursor,
+            "MATCH",
+            MATCH,
+            "COUNT",
+            COUNT ?? 100
+          );
+          cursor = next;
+          if (batch.length > 0) yield batch;
+        } while (cursor !== "0");
+      }
+    },
+    ping: () => client.ping(),
+    on: (event, listener) => {
+      client.on(event, listener);
+      return client;
+    }
+  };
+}
+function adaptIoredis(client) {
+  return adapt(client, false);
+}
+function adaptCluster(cluster) {
+  return adapt(cluster, true);
+}
+function createIoredisClient(config) {
+  const IORedis = __require("ioredis");
+  const Ctor = IORedis.default ?? IORedis;
+  return new Ctor(config.url, {
+    password: config.password,
+    connectTimeout: config.connectTimeout ?? 1500,
+    tls: config.tls ? {} : void 0,
+    lazyConnect: true,
+    maxRetriesPerRequest: 1
+  });
+}
+function createIoredisCluster(config) {
+  const IORedis = __require("ioredis");
+  const ClusterCtor = IORedis.Cluster ?? IORedis.default.Cluster;
+  return new ClusterCtor(config.nodes, {
+    redisOptions: {
+      password: config.password,
+      tls: config.tls ? {} : void 0
+    },
+    enableReadyCheck: true,
+    lazyConnect: true
+  });
+}
+var init_adapter_ioredis = __esm({
+  "src/shared/client/adapter-ioredis.ts"() {
+  }
+});
+
+// src/shared/abort.ts
+var CacheTimeoutError = class extends Error {
+  constructor(opName, ms) {
+    super(`[@leejpsd/nextjs-cache-handler] ${opName} timed out after ${ms}ms`);
+    this.opName = opName;
+    this.ms = ms;
+  }
+  opName;
+  ms;
+  name = "CacheTimeoutError";
+};
+async function withAbortSignal(opName, ms, fn) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), ms);
+  if (typeof timer === "object" && "unref" in timer) {
+    timer.unref();
+  }
+  try {
+    const timeoutPromise = new Promise((_, reject) => {
+      const onAbort = () => {
+        ctrl.signal.removeEventListener("abort", onAbort);
+        reject(new CacheTimeoutError(opName, ms));
+      };
+      if (ctrl.signal.aborted) onAbort();
+      else ctrl.signal.addEventListener("abort", onAbort, { once: true });
+    });
+    return await Promise.race([fn(ctrl.signal), timeoutPromise]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// src/shared/client/index.ts
+async function buildClient(source) {
+  if (typeof source === "function") {
+    return await source();
+  }
+  switch (source.type) {
+    case "redis": {
+      const { adaptRedisV5: adaptRedisV52, createRedisV5Client: createRedisV5Client2 } = await Promise.resolve().then(() => (init_adapter_redis(), adapter_redis_exports));
+      return adaptRedisV52(createRedisV5Client2(source));
+    }
+    case "ioredis": {
+      const { adaptIoredis: adaptIoredis2, createIoredisClient: createIoredisClient2 } = await Promise.resolve().then(() => (init_adapter_ioredis(), adapter_ioredis_exports));
+      return adaptIoredis2(createIoredisClient2(source));
+    }
+    case "cluster": {
+      const { adaptCluster: adaptCluster2, createIoredisCluster: createIoredisCluster2 } = await Promise.resolve().then(() => (init_adapter_ioredis(), adapter_ioredis_exports));
+      return adaptCluster2(createIoredisCluster2(source));
+    }
+    default: {
+      const exhaustive = source;
+      throw new Error(
+        `[next-cache] unknown client config: ${JSON.stringify(exhaustive)}`
+      );
+    }
+  }
+}
+var ConnectionManager = class {
+  constructor(source, onError) {
+    this.source = source;
+    this.onError = onError;
+  }
+  source;
+  onError;
+  client = null;
+  connecting = null;
+  failed = false;
+  async getOrConnect() {
+    if (this.client?.isOpen) return this.client;
+    if (this.failed) return null;
+    if (this.connecting) return this.connecting;
+    this.connecting = (async () => {
+      try {
+        const c = await buildClient(this.source);
+        c.on("error", (err) => this.onError(err));
+        if (!c.isOpen) await c.connect();
+        this.client = c;
+        return c;
+      } catch (err) {
+        this.failed = true;
+        this.onError(err);
+        return null;
+      } finally {
+        this.connecting = null;
+      }
+    })();
+    return this.connecting;
+  }
+  reset() {
+    this.client = null;
+    this.connecting = null;
+    this.failed = false;
+  }
+};
+
+// src/shared/logger.ts
+var defaultLogger = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: (message, meta) => {
+    if (meta) console.warn(`[next-cache] ${message}`, meta);
+    else console.warn(`[next-cache] ${message}`);
+  },
+  error: (message, meta) => {
+    if (meta) console.error(`[next-cache] ${message}`, meta);
+    else console.error(`[next-cache] ${message}`);
+  }
+};
+
+// src/shared/lua/set-with-tags.lua
+var set_with_tags_default = `-- set-with-tags.lua
+--
+-- Atomically write a cache entry and update the tag indices that point at it.
+-- Replaces the non-atomic SET \u2192 SADD \u2192 EXPIRE sequence in the reference
+-- implementation, which had a race window where another instance's hard
+-- invalidate could leave dangling tag members.
+--
+-- KEYS[1]      : entry key (e.g. "next-cache:entry:abc123")
+-- KEYS[2..N]   : tag set keys (e.g. "next-cache:tag:posts")
+-- ARGV[1]      : serialized entry payload
+-- ARGV[2]      : entry TTL in seconds
+-- ARGV[3]      : tag TTL in seconds (typically same as entry TTL)
+-- ARGV[4]      : tag count (number of KEYS after KEYS[1])
+--
+-- Returns: 1 on success.
+
+local entryKey = KEYS[1]
+local payload = ARGV[1]
+local entryTtl = tonumber(ARGV[2])
+local tagTtl = tonumber(ARGV[3])
+local tagCount = tonumber(ARGV[4])
+
+redis.call('SET', entryKey, payload, 'EX', entryTtl)
+
+for i = 1, tagCount do
+  local tagKey = KEYS[i + 1]
+  redis.call('SADD', tagKey, entryKey)
+  -- EXPIRE on every SADD: ensures the tag set never outlives its entries
+  -- and survives at least as long as the longest associated entry.
+  redis.call('EXPIRE', tagKey, tagTtl)
+end
+
+return 1
+`;
+
+// src/shared/lua/revalidate-hard.lua
+var revalidate_hard_default = "-- revalidate-hard.lua\n--\n-- Atomically remove every entry referenced by a tag and stamp the tag's\n-- expiration marker. Used by `updateTags(tags, { expire: 0 })` \u2014 the hard\n-- invalidation path triggered by `updateTag()` server actions in Next.js 16.\n--\n-- KEYS[1]   : tag set key (e.g. \"next-cache:tag:posts\")\n-- KEYS[2]   : tag-expiration marker key (e.g. \"next-cache:tag-expiration:posts\")\n-- ARGV[1]   : current timestamp in milliseconds\n-- ARGV[2]   : marker TTL in seconds (default: 1 day so cross-deployment\n--             readers can still observe the invalidation)\n--\n-- Returns: number of entries that were deleted.\n\nlocal tagKey = KEYS[1]\nlocal markerKey = KEYS[2]\nlocal nowMs = ARGV[1]\nlocal markerTtl = tonumber(ARGV[2])\n\nlocal entries = redis.call('SMEMBERS', tagKey)\nlocal deleted = 0\n\nif #entries > 0 then\n  -- DEL accepts varargs; unpack the entry list.\n  redis.call('DEL', unpack(entries))\n  deleted = #entries\nend\n\n-- Drop the tag set itself; on next SET it'll be recreated by set-with-tags.\nredis.call('DEL', tagKey)\n\n-- Stamp the invalidation timestamp. Readers compare this against an entry's\n-- timestamp inside `getExpiration` to decide whether soft-tag-only entries\n-- should be considered stale.\nredis.call('SET', markerKey, nowMs, 'EX', markerTtl)\n\nreturn deleted\n";
+
+// src/shared/lua/refresh-tag-lock.lua
+var refresh_tag_lock_default = `-- refresh-tag-lock.lua
+--
+-- Single-flight lock acquisition for background refresh.
+-- Reserved for v0.2's stampede-protection feature. Currently unused by the
+-- handler runtime, but bundled so v0.2 can ship without a major bump.
+--
+-- KEYS[1]   : lock key (e.g. "next-cache:lock:abc123")
+-- ARGV[1]   : owner identifier (instance id; written for observability)
+-- ARGV[2]   : lock TTL in seconds (10s recommended \u2014 long enough for refresh
+--             to complete, short enough to recover from a crashed owner)
+--
+-- Returns: 1 if lock acquired, 0 if another owner already holds it.
+
+local lockKey = KEYS[1]
+local owner = ARGV[1]
+local ttl = tonumber(ARGV[2])
+
+if redis.call('GET', lockKey) then
+  return 0
+end
+
+redis.call('SET', lockKey, owner, 'EX', ttl)
+return 1
+`;
+
+// src/shared/lua/index.ts
+var SCRIPTS = {
+  setWithTags: set_with_tags_default,
+  revalidateHard: revalidate_hard_default,
+  refreshTagLock: refresh_tag_lock_default
+};
+var shaCache = /* @__PURE__ */ new Map();
+function sha1(body) {
+  return createHash("sha1").update(body).digest("hex");
+}
+function isNoScriptError(err) {
+  if (!err || typeof err !== "object") return false;
+  const msg = err.message ?? "";
+  return msg.includes("NOSCRIPT");
+}
+async function execLuaScript(client, name, keys, args) {
+  const body = SCRIPTS[name];
+  let cachedSha = shaCache.get(name);
+  if (cachedSha === void 0) {
+    cachedSha = sha1(body);
+    shaCache.set(name, cachedSha);
+  }
+  if (typeof client.evalSha === "function") {
+    try {
+      return await client.evalSha(cachedSha, {
+        keys,
+        arguments: args
+      });
+    } catch (err) {
+      if (!isNoScriptError(err)) {
+        throw err;
+      }
+    }
+  }
+  return await client.eval(body, { keys, arguments: args });
+}
+
+// src/shared/memory-fallback.ts
+var MAX_TIMER_MS = 2147483647;
+function clampTimerMs(ms) {
+  return Math.min(Math.max(0, ms), MAX_TIMER_MS);
+}
+var MemoryStore = class {
+  kv = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Map();
+  set(key, value, ttlSeconds) {
+    this.delete(key);
+    const expiresAt = Date.now() + ttlSeconds * 1e3;
+    this.kv.set(key, { value, expiresAt });
+    const timer = setTimeout(() => this.delete(key), clampTimerMs(ttlSeconds * 1e3));
+    if (typeof timer === "object" && "unref" in timer) {
+      timer.unref();
+    }
+    this.timers.set(key, timer);
+  }
+  get(key) {
+    const entry = this.kv.get(key);
+    if (!entry) return null;
+    if (Date.now() > entry.expiresAt) {
+      this.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+  delete(key) {
+    const timer = this.timers.get(key);
+    if (timer !== void 0) {
+      clearTimeout(timer);
+      this.timers.delete(key);
+    }
+    return this.kv.delete(key);
+  }
+  has(key) {
+    return this.get(key) !== null;
+  }
+  keys() {
+    const now = Date.now();
+    const live = [];
+    for (const [key, entry] of this.kv.entries()) {
+      if (entry.expiresAt >= now) live.push(key);
+    }
+    return live;
+  }
+  size() {
+    return this.keys().length;
+  }
+  clear() {
+    for (const timer of this.timers.values()) clearTimeout(timer);
+    this.timers.clear();
+    this.kv.clear();
+  }
+};
+var MemorySetStore = class {
+  sets = /* @__PURE__ */ new Map();
+  expiresAt = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Map();
+  sAdd(key, member) {
+    const members = Array.isArray(member) ? member : [member];
+    let set = this.sets.get(key);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.sets.set(key, set);
+    }
+    let added = 0;
+    for (const m of members) {
+      if (!set.has(m)) {
+        set.add(m);
+        added += 1;
+      }
+    }
+    return added;
+  }
+  sMembers(key) {
+    if (this.isExpired(key)) {
+      this.delete(key);
+      return [];
+    }
+    const set = this.sets.get(key);
+    return set ? Array.from(set) : [];
+  }
+  expire(key, ttlSeconds) {
+    if (!this.sets.has(key)) return false;
+    const prev = this.timers.get(key);
+    if (prev !== void 0) clearTimeout(prev);
+    const expiresAt = Date.now() + ttlSeconds * 1e3;
+    this.expiresAt.set(key, expiresAt);
+    const timer = setTimeout(() => this.delete(key), clampTimerMs(ttlSeconds * 1e3));
+    if (typeof timer === "object" && "unref" in timer) {
+      timer.unref();
+    }
+    this.timers.set(key, timer);
+    return true;
+  }
+  delete(key) {
+    const timer = this.timers.get(key);
+    if (timer !== void 0) {
+      clearTimeout(timer);
+      this.timers.delete(key);
+    }
+    this.expiresAt.delete(key);
+    return this.sets.delete(key);
+  }
+  keys() {
+    const live = [];
+    for (const key of this.sets.keys()) {
+      if (!this.isExpired(key)) live.push(key);
+    }
+    return live;
+  }
+  clear() {
+    for (const timer of this.timers.values()) clearTimeout(timer);
+    this.timers.clear();
+    this.expiresAt.clear();
+    this.sets.clear();
+  }
+  isExpired(key) {
+    const at = this.expiresAt.get(key);
+    return at !== void 0 && Date.now() > at;
+  }
+};
+
+// src/shared/metrics.ts
+var counters = /* @__PURE__ */ new Map();
+function bump(event) {
+  const existing = counters.get(event.type);
+  if (existing) {
+    existing.count += 1;
+    if (event.ms !== void 0) existing.totalMs += event.ms;
+    existing.lastTs = Date.now();
+    return;
+  }
+  counters.set(event.type, {
+    count: 1,
+    totalMs: event.ms ?? 0,
+    lastTs: Date.now()
+  });
+}
+function createEmitter(onMetric) {
+  return (event) => {
+    bump(event);
+    if (onMetric) {
+      try {
+        onMetric(event);
+      } catch {
+      }
+    }
+  };
+}
+
+// src/shared/namespace.ts
+var FALLBACK = "unversioned";
+function resolveBuildNamespace(override) {
+  if (override !== void 0) {
+    return typeof override === "function" ? override() : override;
+  }
+  return process.env.DEPLOYMENT_VERSION ?? process.env.GIT_HASH ?? process.env.NEXT_DEPLOYMENT_ID ?? FALLBACK;
+}
+function buildKey(prefix, namespace, rest, hashTag = false) {
+  const ns = hashTag ? `{${namespace}}` : namespace;
+  return `${prefix}${ns}:${rest}`;
+}
+
+// src/shared/build-phase.ts
+var PHASE_PRODUCTION_BUILD = "phase-production-build";
+function isBuildPhase() {
+  return process.env.NEXT_PHASE === PHASE_PRODUCTION_BUILD;
+}
+function shouldUseRedis(opts) {
+  if (opts.fallback === "always") return false;
+  const detector = opts.isBuildPhase ?? isBuildPhase;
+  if (detector()) return false;
+  return true;
+}
+
+// src/cache-components/serialize.ts
+async function readStreamFully(stream) {
+  const reader = stream.getReader();
+  const chunks = [];
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return Buffer.concat(chunks.map((c) => Buffer.from(c)));
+}
+function bufferToStream(buf) {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(new Uint8Array(buf));
+      controller.close();
+    }
+  });
+}
+function encodeEnvelope(buf, meta) {
+  const envelope = {
+    value: buf.toString("base64"),
+    ...meta
+  };
+  return JSON.stringify(envelope);
+}
+function decodeEnvelope(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || typeof parsed.value !== "string") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+// src/cache-components/swr.ts
+var SECOND_MS = 1e3;
+function partitionEntry(entry, now = Date.now()) {
+  const ageMs = now - entry.timestamp;
+  if (ageMs < 0) {
+    return { freshness: "fresh", ageMs };
+  }
+  const revalidateMs = Math.max(0, entry.revalidate) * SECOND_MS;
+  const rawExpireMs = entry.expire === 0 ? Number.POSITIVE_INFINITY : Math.max(0, entry.expire) * SECOND_MS;
+  const expireMs = Math.max(rawExpireMs, revalidateMs);
+  if (ageMs <= revalidateMs) {
+    return { freshness: "fresh", ageMs };
+  }
+  if (ageMs <= expireMs) {
+    return { freshness: "stale", ageMs };
+  }
+  return { freshness: "expired", ageMs };
+}
+function shouldServeStale(result, staleWhileRevalidate) {
+  return result.freshness === "fresh" || result.freshness === "stale" && staleWhileRevalidate;
+}
+
+// src/cache-components/handler.ts
+var DEFAULT_KEY_PREFIX = "next-cache:";
+var ENTRY_SUFFIX = "entry:";
+var TAG_SUFFIX = "tag:";
+var TAG_EXP_SUFFIX = "tag-expiration:";
+var DEFAULT_ABORT_MS = 1500;
+var ONE_YEAR_SEC = 60 * 60 * 24 * 365;
+var FALLBACK_TTL_SEC = 3600;
+var TAG_EXP_MARKER_TTL_SEC = 60 * 60 * 24 * 7;
+function gateRedis(state) {
+  const fb = state.opts.fallback;
+  const ibp = state.opts.rest.isBuildPhase;
+  return ibp ? shouldUseRedis({ fallback: fb, isBuildPhase: ibp }) : shouldUseRedis({ fallback: fb });
+}
+function init(opts) {
+  const logger = opts.logger ?? defaultLogger;
+  const emit = createEmitter(opts.onMetric);
+  const conn = new ConnectionManager(opts.client, (err) => {
+    logger.warn("Redis client error", { message: err.message });
+    emit({ type: "redis.connect.failed", meta: { message: err.message } });
+  });
+  return {
+    opts: {
+      abortTimeoutMs: opts.abortTimeoutMs ?? DEFAULT_ABORT_MS,
+      fallback: opts.fallback ?? "auto",
+      staleWhileRevalidate: opts.staleWhileRevalidate ?? true,
+      hashTag: opts.hashTag ?? false,
+      keyPrefix: opts.keyPrefix ?? DEFAULT_KEY_PREFIX,
+      rest: opts
+    },
+    logger,
+    emit,
+    conn,
+    memEntries: new MemoryStore(),
+    memTags: new MemorySetStore(),
+    memTagExp: /* @__PURE__ */ new Map(),
+    localTagTimestamps: /* @__PURE__ */ new Map(),
+    resolveNs: () => resolveBuildNamespace(opts.buildNamespace)
+  };
+}
+function entryKey(state, cacheKey) {
+  return buildKey(
+    `${state.opts.keyPrefix}${ENTRY_SUFFIX}`,
+    state.resolveNs(),
+    cacheKey,
+    state.opts.hashTag
+  );
+}
+function tagKey(state, tag) {
+  return buildKey(
+    `${state.opts.keyPrefix}${TAG_SUFFIX}`,
+    state.resolveNs(),
+    tag,
+    state.opts.hashTag
+  );
+}
+function tagExpKey(state, tag) {
+  return buildKey(
+    `${state.opts.keyPrefix}${TAG_EXP_SUFFIX}`,
+    state.resolveNs(),
+    tag,
+    state.opts.hashTag
+  );
+}
+function resolveTtlSeconds(entry) {
+  if (Number.isFinite(entry.expire) && entry.expire > 0) {
+    return Math.max(60, Math.ceil(entry.expire));
+  }
+  if (Number.isFinite(entry.revalidate) && entry.revalidate > 0) {
+    return Math.max(60, Math.ceil(entry.revalidate));
+  }
+  if (entry.expire === Number.POSITIVE_INFINITY) {
+    return ONE_YEAR_SEC;
+  }
+  return FALLBACK_TTL_SEC;
+}
+async function getImpl(state, cacheKey, softTags) {
+  const start = Date.now();
+  const useRedis = gateRedis(state);
+  if (!useRedis && state.opts.fallback === "never") {
+    state.emit({ type: "cache.miss", meta: { reason: "no-redis" } });
+    return void 0;
+  }
+  const eKey = entryKey(state, cacheKey);
+  let envelope = null;
+  let raw = null;
+  if (useRedis) {
+    try {
+      raw = await withAbortSignal(
+        "cacheHandlers.get",
+        state.opts.abortTimeoutMs,
+        async () => {
+          const client = await state.conn.getOrConnect();
+          if (!client) return null;
+          return await client.get(eKey);
+        }
+      );
+    } catch (err) {
+      if (err instanceof CacheTimeoutError) {
+        state.emit({ type: "redis.timeout", meta: { op: "get" } });
+      } else {
+        state.logger.warn("get() Redis error, falling back", {
+          message: err.message
+        });
+      }
+      raw = null;
+    }
+  }
+  if (raw === null && state.opts.fallback !== "never") {
+    raw = state.memEntries.get(eKey);
+    if (raw !== null) state.emit({ type: "fallback.activated", meta: { op: "get" } });
+  }
+  if (raw === null) {
+    state.emit({ type: "cache.miss", ms: Date.now() - start });
+    return void 0;
+  }
+  envelope = decodeEnvelope(raw);
+  if (!envelope) {
+    state.emit({ type: "cache.miss", meta: { reason: "decode-error" } });
+    return void 0;
+  }
+  const partition = partitionEntry(envelope, Date.now());
+  if (!shouldServeStale(partition, state.opts.staleWhileRevalidate)) {
+    if (useRedis) {
+      try {
+        await withAbortSignal(
+          "cacheHandlers.get.evict",
+          state.opts.abortTimeoutMs,
+          async () => {
+            const c = await state.conn.getOrConnect();
+            if (c) await c.del(eKey);
+          }
+        );
+      } catch {
+      }
+    } else {
+      state.memEntries.delete(eKey);
+    }
+    state.emit({
+      type: "cache.miss",
+      meta: { reason: "expired", freshness: partition.freshness }
+    });
+    return void 0;
+  }
+  if (softTags.length > 0) {
+    let mostRecent = 0;
+    for (const t of softTags) {
+      const ts = state.localTagTimestamps.get(t);
+      if (ts !== void 0 && ts > mostRecent) mostRecent = ts;
+    }
+    if (mostRecent > envelope.timestamp) {
+      state.emit({
+        type: "cache.miss",
+        meta: { reason: "soft-tag-invalidated" }
+      });
+      return void 0;
+    }
+  }
+  state.emit({
+    type: partition.freshness === "stale" ? "cache.stale" : "cache.hit",
+    ms: Date.now() - start,
+    meta: { freshness: partition.freshness }
+  });
+  return {
+    value: bufferToStream(Buffer.from(envelope.value, "base64")),
+    tags: envelope.tags,
+    stale: envelope.stale,
+    timestamp: envelope.timestamp,
+    expire: envelope.expire,
+    revalidate: envelope.revalidate
+  };
+}
+async function setImpl(state, cacheKey, pendingEntry) {
+  let entry;
+  try {
+    entry = await pendingEntry;
+  } catch (err) {
+    state.logger.warn("pendingEntry rejected, skipping set()", {
+      message: err.message
+    });
+    state.emit({ type: "cache.set.failed", meta: { reason: "pending-rejected" } });
+    return;
+  }
+  let buf;
+  try {
+    buf = await readStreamFully(entry.value);
+  } catch (err) {
+    state.logger.warn("stream errored mid-read, discarding entry", {
+      message: err.message
+    });
+    state.emit({ type: "cache.set.failed", meta: { reason: "partial-stream" } });
+    return;
+  }
+  const eKey = entryKey(state, cacheKey);
+  const ttl = resolveTtlSeconds(entry);
+  const payload = encodeEnvelope(buf, {
+    tags: entry.tags,
+    stale: entry.stale,
+    timestamp: entry.timestamp,
+    expire: entry.expire,
+    revalidate: entry.revalidate
+  });
+  const useRedis = gateRedis(state);
+  if (!useRedis) {
+    state.emit({ type: "build_phase.skip", meta: { op: "set" } });
+    if (state.opts.fallback !== "never") {
+      state.memEntries.set(eKey, payload, ttl);
+      for (const t of entry.tags) {
+        state.memTags.sAdd(tagKey(state, t), eKey);
+        state.memTags.expire(tagKey(state, t), ttl);
+      }
+    }
+    state.emit({ type: "cache.set", meta: { backend: "memory" } });
+    return;
+  }
+  try {
+    await withAbortSignal(
+      "cacheHandlers.set",
+      state.opts.abortTimeoutMs,
+      async () => {
+        const client = await state.conn.getOrConnect();
+        if (!client) {
+          if (state.opts.fallback !== "never") {
+            state.memEntries.set(eKey, payload, ttl);
+          }
+          return;
+        }
+        if (entry.tags.length === 0) {
+          await client.set(eKey, payload, { EX: ttl });
+        } else {
+          await luaSetWithTags(client, state, eKey, payload, ttl, entry.tags);
+        }
+      }
+    );
+    state.emit({ type: "cache.set", meta: { backend: "redis" } });
+  } catch (err) {
+    if (err instanceof CacheTimeoutError) {
+      state.emit({ type: "redis.timeout", meta: { op: "set" } });
+    } else {
+      state.logger.warn("set() failed (best-effort)", {
+        message: err.message
+      });
+    }
+    state.emit({ type: "cache.set.failed", meta: { reason: "redis-error" } });
+  }
+}
+async function luaSetWithTags(client, state, eKey, payload, ttl, tags) {
+  const tagKeys = tags.map((t) => tagKey(state, t));
+  await execLuaScript(
+    client,
+    "setWithTags",
+    [eKey, ...tagKeys],
+    [payload, String(ttl), String(ttl), String(tags.length)]
+  );
+}
+async function refreshTagsImpl(state) {
+  if (!gateRedis(state)) {
+    return;
+  }
+  try {
+    await withAbortSignal(
+      "cacheHandlers.refreshTags",
+      state.opts.abortTimeoutMs,
+      async () => {
+        const client = await state.conn.getOrConnect();
+        if (!client) return;
+        const pattern = `${state.opts.keyPrefix}${TAG_EXP_SUFFIX}*`;
+        const seen = [];
+        for await (const chunk of client.scanIterator({
+          MATCH: pattern,
+          COUNT: 100
+        })) {
+          const keys = Array.isArray(chunk) ? chunk.map(String) : [String(chunk)];
+          seen.push(...keys);
+          if (seen.length >= 500) break;
+        }
+        if (seen.length === 0) return;
+        const values = await client.mGet(seen);
+        for (let i = 0; i < seen.length; i += 1) {
+          const v = values[i];
+          if (!v) continue;
+          const ts = Number.parseInt(v, 10);
+          if (!Number.isFinite(ts)) continue;
+          const key = seen[i];
+          if (key === void 0) continue;
+          const tag = stripExpPrefix(state, key);
+          if (tag) state.localTagTimestamps.set(tag, ts);
+        }
+      }
+    );
+  } catch (err) {
+    state.logger.warn("refreshTags() error swallowed", {
+      message: err.message
+    });
+  }
+}
+function stripExpPrefix(state, fullKey) {
+  const ns = state.resolveNs();
+  const prefix = state.opts.hashTag ? `${state.opts.keyPrefix}${TAG_EXP_SUFFIX}{${ns}}:` : `${state.opts.keyPrefix}${TAG_EXP_SUFFIX}${ns}:`;
+  return fullKey.startsWith(prefix) ? fullKey.slice(prefix.length) : null;
+}
+async function getExpirationImpl(state, tags) {
+  if (tags.length === 0) return 0;
+  let max = 0;
+  for (const t of tags) {
+    const local = state.localTagTimestamps.get(t);
+    if (local !== void 0 && local > max) max = local;
+    const mem = state.memTagExp.get(t);
+    if (mem !== void 0 && mem > max) max = mem;
+  }
+  if (max > 0) {
+    state.emit({ type: "tag.expiration.read", meta: { source: "local", count: tags.length } });
+    return max;
+  }
+  if (!gateRedis(state)) {
+    return 0;
+  }
+  try {
+    return await withAbortSignal(
+      "cacheHandlers.getExpiration",
+      state.opts.abortTimeoutMs,
+      async () => {
+        const client = await state.conn.getOrConnect();
+        if (!client) return 0;
+        const keys = tags.map((t) => tagExpKey(state, t));
+        const values = await client.mGet(keys);
+        let m = 0;
+        for (const v of values) {
+          if (!v) continue;
+          const n = Number.parseInt(v, 10);
+          if (Number.isFinite(n) && n > m) m = n;
+        }
+        return m;
+      }
+    );
+  } catch {
+    return 0;
+  }
+}
+async function updateTagsImpl(state, tags, durations) {
+  if (tags.length === 0) return;
+  const isHardExpire = durations?.expire === 0;
+  const now = Date.now();
+  for (const t of tags) {
+    state.localTagTimestamps.set(t, now);
+    state.memTagExp.set(t, now);
+  }
+  if (!gateRedis(state)) {
+    if (isHardExpire) {
+      for (const t of tags) {
+        const tk = tagKey(state, t);
+        const members = state.memTags.sMembers(tk);
+        for (const m of members) state.memEntries.delete(m);
+        state.memTags.delete(tk);
+      }
+    }
+    state.emit({
+      type: isHardExpire ? "tag.invalidate.hard" : "tag.invalidate.soft",
+      meta: { count: tags.length, backend: "memory" }
+    });
+    return;
+  }
+  try {
+    await withAbortSignal(
+      "cacheHandlers.updateTags",
+      state.opts.abortTimeoutMs,
+      async () => {
+        const client = await state.conn.getOrConnect();
+        if (!client) {
+          if (isHardExpire) {
+            throw new Error(
+              "[next-cache] hard updateTags requested but Redis unavailable"
+            );
+          }
+          return;
+        }
+        for (const t of tags) {
+          if (isHardExpire) {
+            await execLuaScript(
+              client,
+              "revalidateHard",
+              [tagKey(state, t), tagExpKey(state, t)],
+              [String(now), String(TAG_EXP_MARKER_TTL_SEC)]
+            );
+          } else {
+            await client.set(tagExpKey(state, t), String(now), {
+              EX: TAG_EXP_MARKER_TTL_SEC
+            });
+          }
+        }
+      }
+    );
+    state.emit({
+      type: isHardExpire ? "tag.invalidate.hard" : "tag.invalidate.soft",
+      meta: { count: tags.length, backend: "redis" }
+    });
+  } catch (err) {
+    if (err instanceof CacheTimeoutError) {
+      state.emit({ type: "redis.timeout", meta: { op: "updateTags" } });
+    }
+    if (isHardExpire) {
+      throw err;
+    }
+    state.logger.warn("updateTags() soft path failed (best-effort)", {
+      message: err.message
+    });
+  }
+}
+function createCacheComponentsHandler(opts) {
+  const state = init(opts);
+  return {
+    get: (cacheKey, softTags) => getImpl(state, cacheKey, softTags),
+    set: (cacheKey, pendingEntry) => setImpl(state, cacheKey, pendingEntry),
+    refreshTags: () => refreshTagsImpl(state),
+    getExpiration: (tags) => getExpirationImpl(state, tags),
+    updateTags: (tags, durations) => updateTagsImpl(state, tags, durations)
+  };
+}
+
+export { createCacheComponentsHandler, partitionEntry, shouldServeStale };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map