cdk-nextjs 0.7.6 → 0.7.7

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

@@ -46265,6 +46265,7 @@ var import_debug6 = __toESM(require_src());
 // 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
@@ -46390,6 +46391,7 @@ 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)}`;
 }
@@ -46603,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}.
@@ -46628,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());
   }
   /**
@@ -46694,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.
@@ -46725,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();
@@ -46732,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.
@@ -46772,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;
       }
@@ -46796,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;
       }
@@ -46883,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;
     }
@@ -46900,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)) {
@@ -46914,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(
@@ -46934,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);
       }
     }
@@ -46954,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;
   }
@@ -46983,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(
@@ -47005,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);
@@ -47018,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) {
@@ -47036,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);
@@ -47048,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 ?? {};
@@ -47111,6 +47483,13 @@ var CacheBucket = class {
 // 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";
 }
@@ -47191,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) {
@@ -47207,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;
@@ -47220,8 +47606,59 @@ 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;
   }
@@ -47229,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);
     }
@@ -47253,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]) {
@@ -47263,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()) {
@@ -47298,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;
 }
@@ -47420,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());