cdk-nextjs 0.7.5 → 0.7.7

package/lib/adapter/use-cache-remote-handler.mjs

@@ -46261,12 +46261,70 @@ var require_dist_cjs20 = __commonJS({
 // src/adapter/use-cache-remote-handler.ts
 var import_client_s32 = __toESM(require_dist_cjs16());
 var import_debug6 = __toESM(require_src());
-import { createHash as createHash6 } from "node:crypto";
 
 // src/adapter/aws-cache-store.ts
 var import_client_dynamodb = __toESM(require_dist_cjs20());
 var import_client_s3 = __toESM(require_dist_cjs16());
+import { AsyncLocalStorage } from "node:async_hooks";
 import { join as join5 } from "node:path";
+
+// src/adapter/cache-utils.ts
+import { createHash as createHash6 } from "node:crypto";
+function preprocessValue(value) {
+  if (value == null) {
+    return value;
+  }
+  if (Buffer.isBuffer(value)) {
+    return {
+      __type: "Buffer",
+      base64: value.toString("base64")
+    };
+  }
+  if (value instanceof Map) {
+    const entries = {};
+    for (const [key, val] of value.entries()) {
+      entries[key] = preprocessValue(val);
+    }
+    return {
+      __type: "Map",
+      data: entries
+    };
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => preprocessValue(item));
+  }
+  if (typeof value === "object") {
+    const processed = {};
+    for (const [key, val] of Object.entries(value)) {
+      processed[key] = preprocessValue(val);
+    }
+    return processed;
+  }
+  return value;
+}
+function serializeCacheValue(value) {
+  const processed = preprocessValue(value);
+  return JSON.stringify(processed);
+}
+function parseCacheValue(jsonString) {
+  return JSON.parse(jsonString, (_key, val) => {
+    if (val && typeof val === "object" && val.__type === "Map") {
+      return new Map(Object.entries(val.data));
+    }
+    if (val && typeof val === "object" && val.__type === "Buffer") {
+      return typeof val.base64 === "string" ? Buffer.from(val.base64, "base64") : Buffer.from(val.data);
+    }
+    if (val && typeof val === "object" && val.type === "Buffer" && Array.isArray(val.data)) {
+      return Buffer.from(val.data);
+    }
+    return val;
+  });
+}
+function sha256Hex(value) {
+  return createHash6("sha256").update(value).digest("hex");
+}
+
+// src/adapter/aws-cache-store.ts
 function resolveAwsCacheConfig() {
   return {
     bucketName: process.env.CDK_NEXTJS_CACHE_BUCKET_NAME || "",
@@ -46333,6 +46391,14 @@ function markerOf(item) {
 }
 var BATCH_GET_MAX_KEYS = 100;
 var DEFAULT_TAG_REFRESH_MS = 1e3;
+var TAG_REFRESH_GRACE_MS = 1e3;
+function hashedTag(tag) {
+  return `#${sha256Hex(tag)}`;
+}
+var MAX_TAG_BYTES = 768;
+function sortKeyTag(tag) {
+  return Buffer.byteLength(tag) <= MAX_TAG_BYTES ? tag : hashedTag(tag);
+}
 var TagMarkerTable = class {
   constructor(client, tableName, buildId) {
     this.client = client;
@@ -46355,7 +46421,7 @@ var TagMarkerTable = class {
         TableName: this.tableName,
         Key: {
           pk: { S: this.buildId },
-          sk: { S: tag }
+          sk: { S: sortKeyTag(tag) }
         },
         ...markerUpdate(now, durations),
         ReturnValues: "ALL_NEW"
@@ -46375,7 +46441,13 @@ var TagMarkerTable = class {
     const unique = Array.from(new Set(tags));
     const markers = /* @__PURE__ */ new Map();
     for (let i5 = 0; i5 < unique.length; i5 += BATCH_GET_MAX_KEYS) {
-      let keys = unique.slice(i5, i5 + BATCH_GET_MAX_KEYS).map((tag) => ({ pk: { S: buildId }, sk: { S: tag } }));
+      const tagBySk = new Map(
+        unique.slice(i5, i5 + BATCH_GET_MAX_KEYS).map((tag) => [sortKeyTag(tag), tag])
+      );
+      let keys = Array.from(
+        tagBySk.keys(),
+        (sk) => ({ pk: { S: buildId }, sk: { S: sk } })
+      );
       for (let attempt = 0; keys?.length && attempt < 3; attempt++) {
         const response = await this.client.send(
           new import_client_dynamodb.BatchGetItemCommand({
@@ -46388,7 +46460,7 @@ var TagMarkerTable = class {
           })
         );
         for (const item of response.Responses?.[tableName] ?? []) {
-          const tag = item.sk?.S;
+          const tag = tagBySk.get(item.sk?.S ?? "");
           if (tag !== void 0) {
             markers.set(tag, markerOf(item));
           }
@@ -46426,11 +46498,13 @@ var RevalidationLog = class {
    * to {@link LOG_PUT_ATTEMPTS} times.
    */
   async put(tag, at, marker) {
+    const skTag = sortKeyTag(tag);
     for (let attempt = 1; ; attempt++) {
       const item = {
         pk: { S: this.pk },
-        sk: { S: `${logSkPrefix(at)}#${tag}` },
-        ttl: { N: String(Math.ceil((at + REVALIDATION_LOG_TTL_MS) / 1e3)) }
+        sk: { S: `${logSkPrefix(at)}#${skTag}` },
+        ttl: { N: String(Math.ceil((at + REVALIDATION_LOG_TTL_MS) / 1e3)) },
+        ...skTag !== tag && { longTag: { S: tag } }
       };
       for (const field of MARKER_FIELDS) {
         const value = marker[field];
@@ -46475,7 +46549,7 @@ var RevalidationLog = class {
             ":pk": { S: this.pk },
             ":since": { S: logSkPrefix(Math.max(0, since)) }
           },
-          ProjectionExpression: "sk, revalidatedAt, staleAt, expiredAt",
+          ProjectionExpression: "sk, longTag, revalidatedAt, staleAt, expiredAt",
           ExclusiveStartKey: startKey
         })
       );
@@ -46487,7 +46561,7 @@ var RevalidationLog = class {
         rows.push({
           sk,
           at: Number(sk.slice(0, LOG_SK_DIGITS)),
-          tag: sk.slice(LOG_SK_DIGITS + 1),
+          tag: item.longTag?.S ?? sk.slice(LOG_SK_DIGITS + 1),
           marker: markerOf(item)
         });
       }
@@ -46531,10 +46605,64 @@ var TrackedTagMarkers = class {
    * result rather than dropped.
    */
   pendingRows = /* @__PURE__ */ new Map();
+  /**
+   * Log rows for tags not tracked and not being read, merged by tag, oldest
+   * first: what the log has said about them since {@link completeSince}. Taken
+   * into a tag's marker when it is read or written.
+   */
+  logOnly = /* @__PURE__ */ new Map();
+  /** See {@link completeSince}. */
+  floor;
+  /**
+   * The future `expiredAt`s of markers dropped since, as `[from, to]`, in
+   * order: once `from` is past, {@link completeSince} moves to `to`, and not
+   * before, since only then does it expire anything. `from` and `to` are the
+   * same until spans are merged for space ({@link laterFloor}).
+   */
+  laterFloors = [];
+  /** The in-memory entry stores judged by {@link completeSince}. */
+  entryStores = [];
+  /** How many times {@link forget} ran: a read started before one is made again. */
+  forgotten = 0;
   /** Tracked tags whose read failed, for the next refresh to read again. */
   unread = /* @__PURE__ */ new Set();
+  /**
+   * Set inside a page render {@link catchUp} let go, for that render alone.
+   * See {@link behindInRender}.
+   */
+  caughtUpRender = new AsyncLocalStorage();
+  /** When `sync` last scanned the entry stores ({@link oldestEntry}). */
+  lastEntryScan = -Infinity;
+  /**
+   * No `logOnly` row is known by it or earlier, so a {@link pruneLogged}
+   * against it or earlier drops nothing: a marker is only ever known by later,
+   * as its `expiredAt` passes.
+   */
+  prunedAgainst = -Infinity;
+  /** When the last refresh started, or was skipped. */
   lastRefresh = -Infinity;
+  /**
+   * The refresh in flight. One left open across a freeze comes back after the
+   * thaw with what it read before, so {@link refresh} waits for it and then
+   * for a fresh one, rather than the runtime waiting for it before the freeze:
+   * that would bill every Lambda invocation for the query's tail.
+   */
   refreshing;
+  /**
+   * When {@link refreshing} last showed the process running: a timer ticks
+   * while it is in flight, and a tick that comes late, or none at all, means
+   * the process was paused - frozen - since it started.
+   */
+  lastTick = -Infinity;
+  /** Whether a tick came late since {@link refreshing} started. */
+  pausedWhileRefreshing = false;
+  ticker;
+  canFreeze;
+  /**
+   * When the last refresh settled, either way, unless it spanned a pause: what
+   * it knows is from then. See {@link behind}.
+   */
+  settledAt;
   /**
    * Where the next log query starts (`clock()`): the last successful one's
    * start, less {@link REVALIDATION_LOG_LOOKBACK_MS}.
@@ -46556,20 +46684,68 @@ var TrackedTagMarkers = class {
     this.random = options.random ?? Math.random;
     this.debug = options.debug ?? (() => {
     });
+    this.canFreeze = options.canFreeze ?? false;
     const at = this.clock();
     this.cursor = at - REVALIDATION_LOG_LOOKBACK_MS;
     this.lastLogRead = at;
+    this.settledAt = at;
+    this.floor = markerClock();
   }
   /** `tag`'s marker as this instance knows it, if it tracks `tag`. */
   get(tag) {
     return this.tags.get(tag);
   }
+  /**
+   * Since when (`markerClock()`) this instance knows of every revalidation of
+   * every tag, tracked or not: tracked ones from their markers and the log,
+   * the others from the log alone (`logOnly`). So an entry created at or after
+   * it can be judged by {@link state} and {@link expiration} without
+   * {@link ensure} reading anything - which matters inside a `'use cache'`
+   * lookup, where Next.js waits for the answer and a read pushes the entry out
+   * of the static stage of a staged render.
+   *
+   * Starts at construction: the log is followed from before it. Moves to now
+   * when the tracked markers are forgotten, and past the revalidations of
+   * whatever else it lets go of - a marker evicted for space, a log row
+   * pruned - which are no longer known: to its `expiredAt` only once that is
+   * past, since a profile's `expire` can be a year out, and moving there at
+   * once would turn the read-free path off for the instance's life.
+   *
+   * A row is pruned only once it is no later than every entry held, so that
+   * costs those entries nothing. An entry stored afterwards with an older
+   * `timestamp` - Next.js stamps the start of its generation, which can
+   * outlast a lookback - is older than this too, and is read first.
+   *
+   * It does not cover a revalidation older than the log's first lookback
+   * whose `expiredAt` is still to come, which would expire an entry created
+   * after it. So the `'use cache'` handler reads an entry's tags in the
+   * background as it stores it.
+   */
+  get completeSince() {
+    const at = markerClock();
+    while (this.laterFloors.length > 0 && this.laterFloors[0][0] <= at) {
+      this.floor = Math.max(this.floor, this.laterFloors.shift()[1]);
+    }
+    return this.floor;
+  }
+  /**
+   * Register an in-memory store whose entries are judged by
+   * {@link completeSince}, by the `timestamp` of the oldest entry it holds:
+   * `logOnly` keeps the rows that could still apply to one of them, and no
+   * others. With none registered it keeps nothing. Asked with `scan` false,
+   * `oldestTimestamp` may answer early, but never late, without a scan.
+   */
+  judgeEntriesOf(oldestTimestamp, holdsAny = () => oldestTimestamp(false) < Infinity) {
+    this.entryStores.push({ oldestTimestamp, holdsAny });
+  }
   /**
    * Track `tag` with `marker`: what this instance just wrote, which it knows
    * without reading it back.
    */
   set(tag, marker) {
-    this.remember(tag, marker);
+    const logged = this.logOnly.get(tag);
+    this.logOnly.delete(tag);
+    this.remember(tag, mergeMarkers(marker, logged));
     this.known(tag, this.clock());
   }
   /**
@@ -46622,27 +46798,103 @@ var TrackedTagMarkers = class {
     const unread = [];
     for (const tag of new Set(tags)) {
       const inFlight = this.reading.get(tag);
-      if (inFlight) {
-        waits.push(inFlight);
-      } else if (this.tags.has(tag)) {
+      if (this.tags.has(tag)) {
         this.touch(tag);
+      } else if (inFlight) {
+        waits.push(inFlight);
       } else {
         unread.push(tag);
       }
     }
     if (unread.length > 0) {
-      const read = this.readInto(unread).then(() => {
-        for (const tag of unread) {
-          this.reading.delete(tag);
-        }
-      });
-      for (const tag of unread) {
-        this.reading.set(tag, read);
-      }
-      waits.push(read);
+      waits.push(this.startRead(unread));
     }
     await Promise.all(waits);
   }
+  /**
+   * {@link readInto} `tags`, as the read of each that whoever needs one of
+   * them next waits on ({@link reading}). Never rejects: a failed read leaves
+   * the tags tracked.
+   */
+  startRead(tags) {
+    const read = this.readInto(tags).then(() => {
+      for (const tag of tags) {
+        this.reading.delete(tag);
+      }
+    });
+    for (const tag of tags) {
+      this.reading.set(tag, read);
+    }
+    return read;
+  }
+  /**
+   * Whether the last refresh settled more than `refreshIntervalMs` plus
+   * {@link TAG_REFRESH_GRACE_MS} ago - one that spanned a freeze counts from
+   * when it started: after the instance sat idle or frozen - or always, with
+   * a `refreshIntervalMs` of `0`. Answering from what it knows then could
+   * serve an entry revalidated elsewhere since, however long ago that was, so
+   * `refreshTags` waits for the refresh, and the runtime waits for it before
+   * a page render starts ({@link catchUp}).
+   *
+   * From when it settled, not when it started, so a slow query the runtime
+   * waited for before the render does not leave the instance behind inside
+   * it. A failed one counts too, so one request does not wait for two: the
+   * same "assume the entry is valid" a failed read answers with, until the
+   * next refresh, at most the interval and the grace later.
+   */
+  get behind() {
+    return this.log !== void 0 && // `0` asks before every check, so every check waits for the answer.
+    (this.refreshIntervalMs === 0 || this.overdue(this.settledAt));
+  }
+  /**
+   * {@link behind}, as `refreshTags` asks it: never inside a page's render
+   * {@link catchUp} caught up, since the runtime settled it for that request
+   * before the render started, and a wait inside a `'use cache'` lookup is
+   * what it settled it to avoid - a render crossing the line partway through
+   * would otherwise wait after all. So a revalidation elsewhere can go unseen
+   * for a render's duration on top of the usual window.
+   *
+   * A route handler, which no catch-up precedes, waits at the plain line.
+   */
+  get behindInRender() {
+    return this.refreshIntervalMs !== 0 && this.caughtUpRender.getStore() ? false : this.behind;
+  }
+  /**
+   * Whether a registered store ({@link judgeEntriesOf}) holds any entry: one
+   * a refresh could expire. With none there is nothing to wait for even when
+   * the instance is {@link behind}, since whatever is stored from here on is
+   * newer than what the log would say - which covers the first `'use cache'`
+   * call of a process, which creates the handler inside the render.
+   */
+  get holdsEntries() {
+    return this.entryStores.some((store) => store.holdsAny());
+  }
+  /**
+   * {@link refresh}, waited for when the instance is {@link behind}. The
+   * runtime calls it before handing a page request to Next.js, outside the
+   * staged render whose static stage a wait inside a `'use cache'` lookup
+   * would cut short. Only for the `'use cache'` handler's entries
+   * ({@link judgeEntriesOf}): the other caches wait for the refresh where they
+   * read anyway. Not with a `refreshIntervalMs` of `0` either, where
+   * `refreshTags` asks again regardless. Then `render`, marked as caught up
+   * for ({@link behindInRender}). Rejects only as `render` does.
+   */
+  async catchUp(render) {
+    const log = (error2) => console.error("Error refreshing cache tags:", error2);
+    if (this.refreshIntervalMs > 0 && this.behind) {
+      if (!this.holdsEntries) {
+        return render();
+      }
+      await this.refresh().catch(log);
+    } else if (this.refreshIntervalMs > 0) {
+      void this.refresh().catch(log);
+    }
+    return this.caughtUpRender.run(true, render);
+  }
+  /** Whether `at` is more than the interval and the grace ago. */
+  overdue(at) {
+    return this.clock() - at > this.refreshIntervalMs + TAG_REFRESH_GRACE_MS;
+  }
   /**
    * Catch up on revalidations other instances ran, at most once per
    * `refreshIntervalMs`. See {@link TrackedTagMarkers} for the cost.
@@ -46653,6 +46905,9 @@ var TrackedTagMarkers = class {
       return;
     }
     if (this.refreshing) {
+      if (this.behind && this.pausedSinceRefreshStarted()) {
+        return this.refreshing.then(() => this.refresh());
+      }
       return this.refreshing;
     }
     const at = this.clock();
@@ -46660,14 +46915,47 @@ var TrackedTagMarkers = class {
       return;
     }
     this.lastRefresh = at;
-    if (this.tags.size === 0) {
+    if (this.tags.size === 0 && this.entryStores.length === 0) {
       return;
     }
+    this.startTicking();
     this.refreshing = this.sync(at, log).finally(() => {
+      this.settledAt = Math.max(
+        this.settledAt,
+        this.pausedSinceRefreshStarted() ? this.lastRefresh : this.clock()
+      );
+      this.stopTicking();
       this.refreshing = void 0;
     });
     return this.refreshing;
   }
+  startTicking() {
+    if (!this.canFreeze) {
+      return;
+    }
+    this.lastTick = this.clock();
+    this.pausedWhileRefreshing = false;
+    this.ticker = setInterval(() => {
+      const at = this.clock();
+      if (at - this.lastTick > REFRESH_PAUSE_MS) {
+        this.pausedWhileRefreshing = true;
+      }
+      this.lastTick = at;
+    }, REFRESH_TICK_MS);
+    this.ticker.unref?.();
+  }
+  stopTicking() {
+    clearInterval(this.ticker);
+    this.ticker = void 0;
+  }
+  /**
+   * Whether the process was paused since {@link refreshing} started: a tick
+   * came late, or the next one is overdue (after a thaw, a request can run
+   * before the timer does).
+   */
+  pausedSinceRefreshStarted() {
+    return this.canFreeze && (this.pausedWhileRefreshing || this.clock() - this.lastTick > REFRESH_PAUSE_MS);
+  }
   /**
    * Record a revalidation of `tags`: here at once, and in the revalidation
    * table for every other instance - the marker row plus a log row per tag.
@@ -46700,7 +46988,7 @@ var TrackedTagMarkers = class {
     const at = markerClock();
     let state2 = "fresh";
     for (const tag of tags) {
-      const marker = this.get(tag);
+      const marker = this.knownMarker(tag);
       if (!marker) {
         continue;
       }
@@ -46724,7 +47012,7 @@ var TrackedTagMarkers = class {
     const at = markerClock();
     let latest = 0;
     for (const tag of tags) {
-      const marker = this.get(tag);
+      const marker = this.knownMarker(tag);
       if (!marker) {
         continue;
       }
@@ -46811,13 +47099,14 @@ var TrackedTagMarkers = class {
       );
       return;
     }
-    const [result] = await Promise.all([
-      log.query(this.cursor).catch((error2) => {
-        console.error("Error reading tag revalidation log:", error2);
-        return void 0;
-      }),
-      this.readInto(this.due(at))
-    ]);
+    const due = this.due(at);
+    if (due.length > 0) {
+      void this.startRead(due);
+    }
+    const result = await log.query(this.cursor).catch((error2) => {
+      console.error("Error reading tag revalidation log:", error2);
+      return void 0;
+    });
     if (!result) {
       return;
     }
@@ -46828,6 +47117,11 @@ var TrackedTagMarkers = class {
       );
       return;
     }
+    const scan = at - this.lastEntryScan > ENTRY_SCAN_INTERVAL_MS;
+    if (scan) {
+      this.lastEntryScan = at;
+    }
+    const oldest = this.oldestEntry(scan);
     let applied = 0;
     for (const row of result.rows) {
       if (this.applied.has(row.sk)) {
@@ -46842,11 +47136,20 @@ var TrackedTagMarkers = class {
           mergeMarkers(this.pendingRows.get(row.tag), row.marker)
         );
       } else {
+        this.rememberLogged(
+          row.tag,
+          mergeMarkers(this.logOnly.get(row.tag), row.marker),
+          oldest
+        );
         continue;
       }
       this.applied.set(row.sk, row.at);
       applied++;
     }
+    if (oldest > this.prunedAgainst) {
+      this.pruneLogged(oldest);
+    }
+    this.prunedAgainst = oldest;
     this.lastLogRead = at;
     this.advance(at - REVALIDATION_LOG_LOOKBACK_MS);
     this.debug(
@@ -46862,14 +47165,16 @@ var TrackedTagMarkers = class {
     const due = [];
     for (const tag of this.unread) {
       if (due.length >= BATCH_GET_MAX_KEYS) return due;
-      due.push(tag);
+      if (!this.reading.has(tag)) {
+        due.push(tag);
+      }
     }
     const jitter = this.resyncIntervalMs * TAG_RESYNC_JITTER;
     for (const [tag, dueAt] of this.dueAt) {
       if (due.length >= BATCH_GET_MAX_KEYS || dueAt - jitter > at) {
         break;
       }
-      if (dueAt <= at && !this.unread.has(tag)) {
+      if (dueAt <= at && !this.unread.has(tag) && !this.reading.has(tag)) {
         due.push(tag);
       }
     }
@@ -46882,10 +47187,19 @@ var TrackedTagMarkers = class {
    */
   forget(at, why) {
     this.debug(`forgetting ${this.tags.size} tracked tags: ${why}`);
+    this.forgotten++;
+    for (const marker of this.tags.values()) {
+      this.raiseFloor(marker);
+    }
+    for (const marker of this.logOnly.values()) {
+      this.raiseFloor(marker);
+    }
     this.tags.clear();
     this.dueAt.clear();
     this.unread.clear();
     this.applied.clear();
+    this.logOnly.clear();
+    this.floor = Math.max(this.floor, markerClock());
     this.cursor = at - REVALIDATION_LOG_LOOKBACK_MS;
     this.lastLogRead = at;
   }
@@ -46911,13 +47225,17 @@ var TrackedTagMarkers = class {
    * always answered with, rather than a read on every request while DynamoDB
    * is unavailable.
    */
-  async readInto(tags) {
+  async readInto(tags, again = false) {
     if (tags.length === 0) {
       return true;
     }
     const at = this.clock();
+    const forgotten = this.forgotten;
     try {
       const read = await this.markers.read(tags);
+      if (this.forgotten !== forgotten && !again) {
+        return await this.readInto(tags, true);
+      }
       for (const tag of tags) {
         this.unread.delete(tag);
         this.remember(
@@ -46933,6 +47251,9 @@ var TrackedTagMarkers = class {
       return true;
     } catch (error2) {
       console.error("Error reading tag markers:", error2);
+      if (this.forgotten !== forgotten && !again) {
+        return this.readInto(tags, true);
+      }
       this.trackUnread(tags);
       for (const tag of tags) {
         this.unread.add(tag);
@@ -46946,8 +47267,119 @@ var TrackedTagMarkers = class {
   }
   takePendingRows(tag) {
     const pending = this.pendingRows.get(tag);
+    const logged = this.logOnly.get(tag);
     this.pendingRows.delete(tag);
-    return pending;
+    this.logOnly.delete(tag);
+    return logged ? mergeMarkers(logged, pending) : pending;
+  }
+  /**
+   * What this instance knows of `tag`: tracked, or from the log alone -
+   * including rows that arrived while its first read is in flight.
+   */
+  knownMarker(tag) {
+    const tracked = this.tags.get(tag);
+    if (tracked) {
+      return tracked;
+    }
+    const logged = this.logOnly.get(tag);
+    const pending = this.pendingRows.get(tag);
+    return logged || pending ? mergeMarkers(logged, pending) : void 0;
+  }
+  /**
+   * Keep `tag`'s log rows in `logOnly`, unless they cannot apply to an entry
+   * held, `oldest` or newer (see {@link pruneLogged}), as bounded as the
+   * tracked tags. Either way a row let go of takes what it knew with it, so
+   * `completeSince` moves past it.
+   */
+  rememberLogged(tag, marker, oldest) {
+    this.logOnly.delete(tag);
+    if (knownBy(marker, markerClock()) <= oldest) {
+      this.raiseFloor(marker);
+      return;
+    }
+    this.logOnly.set(tag, marker);
+    for (const [first, dropped] of this.logOnly) {
+      if (this.logOnly.size <= this.maxTrackedTags) {
+        break;
+      }
+      this.logOnly.delete(first);
+      this.raiseFloor(dropped);
+    }
+  }
+  /**
+   * Drop the `logOnly` rows that cannot apply to an entry held, `oldest` or
+   * newer: every revalidation they name so far is no later than it. That
+   * moves `completeSince` no further than `oldest`, which costs the entries
+   * held nothing, and a profile's `expiredAt` still to come waits in
+   * `laterFloors`. Without this, a deployment revalidating many distinct tags
+   * filled `logOnly` with tags no entry here carries, and the evictions past
+   * its bound kept moving `completeSince` up to the present.
+   */
+  pruneLogged(oldest) {
+    const at = markerClock();
+    for (const [tag, marker] of this.logOnly) {
+      if (knownBy(marker, at) <= oldest) {
+        this.logOnly.delete(tag);
+        this.raiseFloor(marker);
+      }
+    }
+  }
+  /**
+   * The oldest entry timestamp of any registered store, `Infinity` with none:
+   * early, never late, unless `scan`.
+   */
+  oldestEntry(scan) {
+    let oldest = Infinity;
+    for (const { oldestTimestamp } of this.entryStores) {
+      oldest = Math.min(oldest, oldestTimestamp(scan));
+    }
+    return oldest;
+  }
+  /**
+   * Move `completeSince` past `marker`'s revalidations: what is no longer
+   * known about a tag once its marker is dropped. A future `expiredAt` waits
+   * in `laterFloors` until it is past.
+   */
+  raiseFloor(marker) {
+    const at = markerClock();
+    this.floor = Math.max(this.floor, knownBy(marker, at));
+    const { expiredAt } = marker;
+    if (expiredAt !== void 0 && expiredAt > Math.max(at, this.floor)) {
+      this.laterFloor(expiredAt);
+    }
+  }
+  /**
+   * Add `time` to `laterFloors`, in order. Past the tracked-tag bound the two
+   * spans closest together are merged: from the first's start,
+   * `completeSince` is the second's end, early - which only costs reads, and
+   * for as short a time as any merge allows. Never later than its time, which
+   * would let an entry expire unseen.
+   */
+  laterFloor(time2) {
+    const floors = this.laterFloors;
+    let low = 0;
+    let high = floors.length;
+    while (low < high) {
+      const mid = Math.floor((low + high) / 2);
+      if (floors[mid][0] < time2) {
+        low = mid + 1;
+      } else {
+        high = mid;
+      }
+    }
+    if (low > 0 && floors[low - 1][1] >= time2 || floors[low]?.[0] === time2) {
+      return;
+    }
+    floors.splice(low, 0, [time2, time2]);
+    if (floors.length > this.maxTrackedTags) {
+      let merge2 = 0;
+      for (let i5 = 1; i5 < floors.length - 1; i5++) {
+        if (floors[i5 + 1][1] - floors[i5][0] < floors[merge2 + 1][1] - floors[merge2][0]) {
+          merge2 = i5;
+        }
+      }
+      floors.splice(merge2, 2, [floors[merge2][0], floors[merge2 + 1][1]]);
+    }
   }
   /** Record that `tag`'s marker was known from the table at `at`. */
   known(tag, at) {
@@ -46964,6 +47396,7 @@ var TrackedTagMarkers = class {
       if (this.tags.size <= this.maxTrackedTags) {
         break;
       }
+      this.raiseFloor(this.tags.get(oldest));
       this.tags.delete(oldest);
       this.dueAt.delete(oldest);
       this.unread.delete(oldest);
@@ -46976,7 +47409,18 @@ var TrackedTagMarkers = class {
     }
   }
 };
+function knownBy(marker, at) {
+  const { revalidatedAt, staleAt, expiredAt } = marker;
+  return Math.max(
+    revalidatedAt ?? -Infinity,
+    staleAt ?? -Infinity,
+    expiredAt !== void 0 && expiredAt <= at ? expiredAt : -Infinity
+  );
+}
 var MAX_LOG_PUT_MS = REVALIDATION_LOG_LOOKBACK_MS / 2;
+var ENTRY_SCAN_INTERVAL_MS = 6e4;
+var REFRESH_TICK_MS = 250;
+var REFRESH_PAUSE_MS = 1e3;
 function mergeMarkers(local, remote) {
   if (!local) {
     return remote ?? {};
@@ -47036,61 +47480,16 @@ var CacheBucket = class {
   }
 };
 
-// src/adapter/cache-utils.ts
-function preprocessValue(value) {
-  if (value == null) {
-    return value;
-  }
-  if (Buffer.isBuffer(value)) {
-    return {
-      __type: "Buffer",
-      base64: value.toString("base64")
-    };
-  }
-  if (value instanceof Map) {
-    const entries = {};
-    for (const [key, val] of value.entries()) {
-      entries[key] = preprocessValue(val);
-    }
-    return {
-      __type: "Map",
-      data: entries
-    };
-  }
-  if (Array.isArray(value)) {
-    return value.map((item) => preprocessValue(item));
-  }
-  if (typeof value === "object") {
-    const processed = {};
-    for (const [key, val] of Object.entries(value)) {
-      processed[key] = preprocessValue(val);
-    }
-    return processed;
-  }
-  return value;
-}
-function serializeCacheValue(value) {
-  const processed = preprocessValue(value);
-  return JSON.stringify(processed);
-}
-function parseCacheValue(jsonString) {
-  return JSON.parse(jsonString, (_key, val) => {
-    if (val && typeof val === "object" && val.__type === "Map") {
-      return new Map(Object.entries(val.data));
-    }
-    if (val && typeof val === "object" && val.__type === "Buffer") {
-      return typeof val.base64 === "string" ? Buffer.from(val.base64, "base64") : Buffer.from(val.data);
-    }
-    if (val && typeof val === "object" && val.type === "Buffer" && Array.isArray(val.data)) {
-      return Buffer.from(val.data);
-    }
-    return val;
-  });
-}
-
 // src/adapter/use-cache-common.ts
 var import_client_dynamodb2 = __toESM(require_dist_cjs20());
 var import_debug5 = __toESM(require_src());
+
+// src/runtime/tag-manifest.ts
+var TAG_MANIFEST_SYMBOL = /* @__PURE__ */ Symbol.for(
+  "cdk-nextjs.use-cache.tag-manifest"
+);
+
+// src/adapter/use-cache-common.ts
 function isBuildPhase() {
   return process.env.NEXT_PHASE === "phase-production-build";
 }
@@ -47171,6 +47570,12 @@ var EntryLru = class {
   maxBytes;
   entries = /* @__PURE__ */ new Map();
   bytes = 0;
+  /**
+   * No later than the oldest entry's `timestamp`: the last scan's answer, less
+   * whatever was set since. Entries dropped since only make it early. See
+   * {@link oldestBound}.
+   */
+  lowest = Infinity;
   get(key) {
     const entry = this.entries.get(key);
     if (entry) {
@@ -47187,6 +47592,7 @@ var EntryLru = class {
     }
     this.entries.set(key, entry);
     this.bytes += size;
+    this.lowest = Math.min(this.lowest, entry.timestamp);
     for (const [oldestKey, oldest] of this.entries) {
       if (this.bytes <= this.maxBytes) {
         break;
@@ -47200,7 +47606,58 @@ var EntryLru = class {
     if (existing) {
       this.entries.delete(key);
       this.bytes -= sizeOf2(key, existing);
+      if (this.entries.size === 0) {
+        this.lowest = Infinity;
+      }
+    }
+  }
+  /**
+   * The `timestamp` of the oldest entry held, `Infinity` with none, dropping
+   * on the way the entries past `revalidate` at `at` (`now()`): a handler
+   * that drops them when next read would otherwise hold them until then, and
+   * they would count here meanwhile. A scan, so asked once in a while: in
+   * between, {@link oldestBound} answers.
+   */
+  oldestTimestamp(at = -Infinity) {
+    let oldest = Infinity;
+    for (const [key, entry] of this.entries) {
+      if (isPastRevalidate(entry, at)) {
+        this.delete(key);
+      } else {
+        oldest = Math.min(oldest, entry.timestamp);
+      }
+    }
+    this.lowest = oldest;
+    return oldest;
+  }
+  /**
+   * No later than {@link oldestTimestamp}, without its scan: as of the last
+   * one, less the entries set since. `Infinity` with none held. Drops the
+   * entries past `revalidate` at `at` from the least recently used end, up to
+   * the first that isn't, so {@link holdsLive} doesn't walk past them on every
+   * request until the next scan.
+   */
+  oldestBound(at = -Infinity) {
+    for (const [key, entry] of this.entries) {
+      if (!isPastRevalidate(entry, at)) {
+        break;
+      }
+      this.delete(key);
     }
+    return this.entries.size === 0 ? Infinity : this.lowest;
+  }
+  /**
+   * Whether an entry not past `revalidate` at `at` is held. Usually the first
+   * entry answers; the expired ones it passes are dropped by the scan
+   * {@link oldestTimestamp} makes, not here, so asking changes nothing.
+   */
+  holdsLive(at) {
+    for (const entry of this.entries.values()) {
+      if (!isPastRevalidate(entry, at)) {
+        return true;
+      }
+    }
+    return false;
   }
   get size() {
     return this.entries.size;
@@ -47209,14 +47666,39 @@ var EntryLru = class {
 function sizeOf2(key, entry) {
   return entry.value.byteLength + key.length;
 }
+function isPastRevalidate(stored, at) {
+  return at > stored.timestamp + stored.revalidate * 1e3;
+}
 var DEFAULT_MEMORY_BYTES = 50 * 1024 * 1024;
-function tagMethods(tags) {
+var TAG_TABLE_REQUEST_TIMEOUT_MS = 3e3;
+async function awaitIf(wait, work, failure) {
+  const logged = work.catch((error2) => {
+    console.error(failure, error2);
+  });
+  if (wait) {
+    await logged;
+  }
+}
+function tagMethods(tags, options = {}) {
   return {
-    refreshTags: () => tags.refresh(),
-    async getExpiration(implicitTags) {
-      await tags.ensure(implicitTags);
-      return tags.expiration(implicitTags);
-    },
+    // Started, not awaited, while the instance keeps up, unless `blocking`.
+    // Next.js awaits `refreshTags` inside the first `'use cache'` lookup of a
+    // request (`use-cache-wrapper`), and a staged render ends its static stage
+    // on a timer: a log `Query` there pushed the entry out of the static
+    // stage, so a cached navigation stored the page segment without it. What
+    // the query finds applies from the next request. Awaited once the instance
+    // is `behind`, which the runtime settles before a page render starts
+    // (`catchUp`): the first request after an idle or frozen spell would
+    // otherwise serve whatever was revalidated elsewhere meanwhile. A page's
+    // render just after `catchUp` gets a grace more (`behindInRender`), so a
+    // request that came in just short of the line doesn't cross it inside
+    // the render. Not even then while the instance holds no entry the query
+    // could expire (`holdsEntries`), with a `refreshIntervalMs` of `0` too.
+    refreshTags: () => awaitIf(
+      options.blocking === true || tags.behindInRender && tags.holdsEntries,
+      tags.refresh(),
+      "Error refreshing cache tags:"
+    ),
     async updateTags(revalidatedTags, durations) {
       await tags.update(revalidatedTags, durations);
     }
@@ -47233,7 +47715,6 @@ function lazyHandler(create) {
     updateTags: (tags, durations) => instance().updateTags(tags, durations)
   };
 }
-var TAG_MANIFEST_SYMBOL = /* @__PURE__ */ Symbol.for("cdk-nextjs.use-cache.tag-manifest");
 function sharedTagManifest() {
   const global = globalThis;
   if (!global[TAG_MANIFEST_SYMBOL]) {
@@ -47243,12 +47724,24 @@ function sharedTagManifest() {
       DEFAULT_TAG_REFRESH_MS
     );
     if (config.tableName && !isBuildPhase()) {
-      const client = new import_client_dynamodb2.DynamoDBClient({ region: config.region });
+      const client = new import_client_dynamodb2.DynamoDBClient({
+        region: config.region,
+        // Without `throwOnRequestTimeout` the timeout only logs a warning. It
+        // ends once the response headers arrive: `socketTimeout`, an
+        // inactivity timer kept until the request closes, covers the body.
+        requestHandler: {
+          requestTimeout: TAG_TABLE_REQUEST_TIMEOUT_MS,
+          throwOnRequestTimeout: true,
+          socketTimeout: TAG_TABLE_REQUEST_TIMEOUT_MS
+        }
+      });
       global[TAG_MANIFEST_SYMBOL] = new TrackedTagMarkers({
         markers: new TagMarkerTable(client, config.tableName, config.buildId),
         log: new RevalidationLog(client, config.tableName, config.buildId),
         refreshIntervalMs,
-        debug: (0, import_debug5.default)("cdk-nextjs:cache-handler:tags")
+        debug: (0, import_debug5.default)("cdk-nextjs:cache-handler:tags"),
+        // Set in every Lambda runtime; a container is never frozen.
+        canFreeze: process.env.AWS_LAMBDA_FUNCTION_NAME !== void 0
       });
     } else {
       if (!isBuildPhase()) {
@@ -47278,9 +47771,6 @@ function bucketFromEnv() {
   }
   return new CacheBucket(new import_client_s32.S3Client({ region }), bucketName);
 }
-function isPastRevalidate(stored, at) {
-  return at > stored.timestamp + stored.revalidate * 1e3;
-}
 function isPastExpire(stored, at) {
   return at > stored.timestamp + stored.expire * 1e3;
 }
@@ -47293,7 +47783,7 @@ function createRemoteUseCacheHandler(options = {}) {
   );
   const pending = new PendingSets();
   const debug = (0, import_debug6.default)("cdk-nextjs:cache-handler:use-cache:remote");
-  const s3Key = (cacheKey) => useCacheS3Key(buildId, createHash6("sha256").update(cacheKey).digest("hex"));
+  const s3Key = (cacheKey) => useCacheS3Key(buildId, sha256Hex(cacheKey));
   async function readFromS3(cacheKey) {
     if (!bucket) {
       return void 0;
@@ -47400,7 +47890,13 @@ function createRemoteUseCacheHandler(options = {}) {
       done();
       await writeToS3(cacheKey, stored);
     },
-    ...tagMethods(tags)
+    // Waits for the log query on every request: an entry read from S3 may
+    // predate this instance, so what the query says applies to it at once.
+    ...tagMethods(tags, { blocking: true }),
+    async getExpiration(implicitTags) {
+      await tags.ensure(implicitTags);
+      return tags.expiration(implicitTags);
+    }
   };
 }
 var use_cache_remote_handler_default = lazyHandler(() => createRemoteUseCacheHandler());