cdk-nextjs 0.7.6 → 0.7.8

package/lib/adapter/cache-handler.mjs

@@ -74119,6 +74119,22 @@ var INIT_CACHE_TAG_MANIFEST = "_cdk-nextjs-tag-manifest.json";
 function getTags(ctx) {
   return "tags" in ctx ? ctx.tags : void 0;
 }
+function getCacheControl(ctx) {
+  return "cacheControl" in ctx ? storedCacheControl(ctx.cacheControl) : void 0;
+}
+function storedCacheControl(value) {
+  if (typeof value !== "object" || value === null) {
+    return void 0;
+  }
+  const { revalidate, expire } = value;
+  if (revalidate !== false && !(typeof revalidate === "number" && Number.isFinite(revalidate) && revalidate > 0)) {
+    return void 0;
+  }
+  if (expire !== void 0 && !Number.isFinite(expire)) {
+    return void 0;
+  }
+  return { revalidate, expire };
+}
 
 // src/adapter/local-file-cache-handler.ts
 var import_debug = __toESM(require_src());
@@ -74226,7 +74242,23 @@ var import_debug7 = __toESM(require_src());
 // src/adapter/aws-cache-store.ts
 var import_client_dynamodb = __toESM(require_dist_cjs19());
 var import_client_s3 = __toESM(require_dist_cjs20());
+import { AsyncLocalStorage } from "node:async_hooks";
 import { join as join6 } from "node:path";
+
+// src/runtime/tag-manifest.ts
+var OUTSIDE_REQUEST_SYMBOL = /* @__PURE__ */ Symbol.for(
+  "cdk-nextjs.outside-request-context"
+);
+function outsideRequest(fn) {
+  const global = globalThis;
+  const run = global[OUTSIDE_REQUEST_SYMBOL];
+  return run ? run(fn) : fn();
+}
+var TAG_MANIFEST_SYMBOL = /* @__PURE__ */ Symbol.for(
+  "cdk-nextjs.use-cache.tag-manifest"
+);
+
+// src/adapter/aws-cache-store.ts
 function resolveAwsCacheConfig() {
   return {
     bucketName: process.env.CDK_NEXTJS_CACHE_BUCKET_NAME || "",
@@ -74295,6 +74327,7 @@ function markerOf(item) {
 }
 var BATCH_GET_MAX_KEYS = 100;
 var DEFAULT_TAG_REFRESH_MS = 1e3;
+var TAG_REFRESH_GRACE_MS = 1e3;
 var MAX_SORT_KEY_BYTES = 1024;
 function hashedTag(tag) {
   return `#${sha256Hex(tag)}`;
@@ -74509,10 +74542,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}.
@@ -74534,20 +74621,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());
   }
   /**
@@ -74600,27 +74735,115 @@ 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);
+  }
+  /**
+   * Run `fn` outside the request's context (`outsideRequest`), keeping only
+   * whether the render was {@link catchUp caught up}: a cache handler method
+   * called from inside a staged render, whose clock reads and AWS SDK calls
+   * would otherwise end its static stage.
+   */
+  outsideRender(fn) {
+    const caughtUp = this.caughtUpRender.getStore();
+    return outsideRequest(
+      () => caughtUp ? this.caughtUpRender.run(caughtUp, fn) : fn()
+    );
+  }
+  /** 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.
@@ -74631,6 +74854,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();
@@ -74638,14 +74864,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.
@@ -74678,7 +74937,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;
       }
@@ -74702,7 +74961,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;
       }
@@ -74789,13 +75048,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;
     }
@@ -74806,6 +75066,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)) {
@@ -74820,11 +75085,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(
@@ -74840,14 +75114,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);
       }
     }
@@ -74860,10 +75136,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;
   }
@@ -74889,13 +75174,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(
@@ -74911,6 +75200,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);
@@ -74924,8 +75216,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) {
@@ -74942,6 +75345,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);
@@ -74954,7 +75358,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 ?? {};
@@ -75026,7 +75441,10 @@ function numberFromEnv(name, fallback2) {
   return Number.isFinite(value) && value >= 0 ? value : fallback2;
 }
 var DEFAULT_MEMORY_BYTES = 50 * 1024 * 1024;
-var TAG_MANIFEST_SYMBOL = /* @__PURE__ */ Symbol.for("cdk-nextjs.use-cache.tag-manifest");
+var TAG_TABLE_REQUEST_TIMEOUT_MS = 3e3;
+function outsideRender(fn) {
+  return outsideRequest(sharedTagManifest).outsideRender(fn);
+}
 function sharedTagManifest() {
   const global = globalThis;
   if (!global[TAG_MANIFEST_SYMBOL]) {
@@ -75036,12 +75454,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_debug6.default)("cdk-nextjs:cache-handler:tags")
+        debug: (0, import_debug6.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()) {
@@ -75152,8 +75582,11 @@ var MemoryCacheHandler = class {
    * `Date.now()` drifts from it for as long as the process lives: an entry
    * stamped ahead of it looked newer than a `revalidateTag` run within the
    * drift, and was served for the whole memory TTL.
+   *
+   * `cacheControl` is the lifetime the entry was rendered with, handed back
+   * from {@link get} as the S3 layer does; see `getCacheControl`.
    */
-  async set(cacheKey, data, lastModified) {
+  async set(cacheKey, data, lastModified, cacheControl) {
     if (!data) {
       this.debug(`MEMORY CACHE DELETE: ${cacheKey}`);
       this.inMemoryCache.delete(cacheKey);
@@ -75162,7 +75595,8 @@ var MemoryCacheHandler = class {
     this.debug(`MEMORY CACHE SET: ${cacheKey} (${data.kind})`);
     const cacheHandlerValue = {
       lastModified: lastModified ?? markerClock(),
-      value: data
+      value: data,
+      cacheControl
     };
     const entry = {
       value: cacheHandlerValue,
@@ -75338,15 +75772,26 @@ var S3CacheHandler = class {
    * request is answered from the stale entry - stale-while-revalidate - and that
    * response carries the entry's original `s-maxage`, so the edge caches the
    * stale body again. The background render that replaces it runs in this same
-   * process, so `set` checks this set and invalidates the key's paths a second
+   * process, so `set` checks for the key here and invalidates the key's paths a second
    * time once the fresh entry is in S3. Without that, the edge kept serving the
    * pre-revalidation page for the whole `s-maxage`.
    *
    * Expiring soft-revalidated entries outright instead would also keep the edge
    * right, but it turns every `revalidateTag(tag, "max")` into a blocking render
    * at the origin, which is the thing a profile asks not to happen.
+   *
+   * When the re-render fails, next 16.4's `retainPreviousCacheEntry` writes the
+   * stale value back with a short lifetime: that is no regeneration, so the key
+   * keeps waiting rather than invalidating the edge for a page that has not
+   * changed. {@link servedStale} is how `set` recognises it.
    */
   softRevalidatedKeys = /* @__PURE__ */ new Set();
+  /**
+   * Every value handed out stale, by identity: the object `get` returned is the
+   * one `retainPreviousCacheEntry` writes back. Weak, so a page body is held no
+   * longer than the memory layer or the request holds it.
+   */
+  servedStale = /* @__PURE__ */ new WeakSet();
   /** @see buildTagManifest */
   buildTags;
   constructor(options) {
@@ -75406,12 +75851,17 @@ var S3CacheHandler = class {
       const parsedValue = parseCacheValue(response);
       if (await this.isRevalidated(parsedValue, ctx, cacheKey)) {
         this.debug(`S3 CACHE INVALIDATED BY TAG: ${cacheKey}`);
-        return isFetchCacheGet(ctx) ? null : { lastModified: EXPIRED_LAST_MODIFIED, value: parsedValue.value };
+        return isFetchCacheGet(ctx) ? null : {
+          lastModified: EXPIRED_LAST_MODIFIED,
+          value: parsedValue.value,
+          cacheControl: storedCacheControl(parsedValue.cacheControl)
+        };
       }
       this.debug(`S3 CACHE HIT: ${cacheKey} (${objectKey})`);
       return {
         lastModified: parsedValue.lastModified,
-        value: parsedValue.value
+        value: parsedValue.value,
+        cacheControl: storedCacheControl(parsedValue.cacheControl)
       };
     } catch (error2) {
       console.error(`Error retrieving cache from S3:`, error2);
@@ -75457,7 +75907,7 @@ var S3CacheHandler = class {
       checkTags
     );
     if (state2 === "stale" && !isFetchCacheGet(ctx)) {
-      this.noteSoftRevalidated(cacheKey);
+      this.noteSoftRevalidated(cacheKey, entry.value);
     }
     return state2 === "expired";
   }
@@ -75466,13 +75916,16 @@ var S3CacheHandler = class {
    * whose copy of it will need invalidating again. See
    * {@link softRevalidatedKeys}.
    */
-  noteSoftRevalidated(cacheKey) {
+  noteSoftRevalidated(cacheKey, value) {
     if (!this.invalidatesCdn) {
       return;
     }
+    if (typeof value === "object" && value !== null) {
+      this.servedStale.add(value);
+    }
     this.softRevalidatedKeys.delete(cacheKey);
     if (this.softRevalidatedKeys.size >= MAX_SOFT_REVALIDATED_KEYS) {
-      const oldest = this.softRevalidatedKeys.values().next().value;
+      const oldest = this.softRevalidatedKeys.keys().next().value;
       if (oldest !== void 0) {
         this.softRevalidatedKeys.delete(oldest);
       }
@@ -75510,7 +75963,8 @@ var S3CacheHandler = class {
       const cacheHandlerValue = {
         // On the marker clock, since that is what it is compared with.
         lastModified: markerClock(),
-        value: data
+        value: data,
+        cacheControl: getCacheControl(ctx)
       };
       const cacheEntryWithTags = {
         ...cacheHandlerValue,
@@ -75519,7 +75973,7 @@ var S3CacheHandler = class {
       const body = serializeCacheValue(cacheEntryWithTags);
       await this.bucket.putJson(objectKey, body);
       this.debug(`S3 CACHE STORED: ${cacheKey} (${data.kind})`);
-      if (this.softRevalidatedKeys.delete(cacheKey)) {
+      if (!this.servedStale.has(data) && this.softRevalidatedKeys.delete(cacheKey)) {
         const route = this.s3KeyToInvalidationPath(s3Key);
         if (route !== void 0) {
           this.debug(`SOFT REVALIDATION REGENERATED: ${cacheKey}`);
@@ -75987,19 +76441,22 @@ var CdkNextjsCacheHandler = class _CdkNextjsCacheHandler {
         `Build-time cache directory: ${this.localFileHandler.getCacheDir()}`
       );
     } else {
-      this.s3DynamoHandler = _CdkNextjsCacheHandler.sharedS3DynamoHandler ??= new S3CacheHandler({ context: options });
+      this.s3DynamoHandler = _CdkNextjsCacheHandler.sharedS3DynamoHandler ??= outsideRender(() => new S3CacheHandler({ context: options }));
       this.memoryHandler = _CdkNextjsCacheHandler.sharedMemoryHandler ??= new MemoryCacheHandler();
     }
   }
   /**
    * Get cache entry
    * - Build time: Not implemented (build doesn't read cache)
-   * - Runtime: Try memory first, then S3/DynamoDB
+   * - Runtime: Try memory first, then S3/DynamoDB, {@link outsideRender}
    */
   async get(cacheKey, ctx) {
     if (this.isBuildTime) {
       return this.localFileHandler.get(cacheKey);
     }
+    return outsideRender(() => this.getAtRuntime(cacheKey, ctx));
+  }
+  async getAtRuntime(cacheKey, ctx) {
     const memoryResult = await this.memoryHandler.get(cacheKey);
     if (memoryResult && await this.s3DynamoHandler.isRevalidated(
       {
@@ -76022,7 +76479,8 @@ var CdkNextjsCacheHandler = class _CdkNextjsCacheHandler {
         await this.memoryHandler.set(
           cacheKey,
           s3Result.value,
-          s3Result.lastModified
+          s3Result.lastModified,
+          s3Result.cacheControl
         );
       }
       return s3Result;
@@ -76033,7 +76491,8 @@ var CdkNextjsCacheHandler = class _CdkNextjsCacheHandler {
   /**
    * Set cache entry
    * - Build time: Write to local file cache only (or delete if data is null)
-   * - Runtime: Write to both memory and S3/DynamoDB (or delete if data is null)
+   * - Runtime: Write to both memory and S3/DynamoDB (or delete if data is null),
+   *   {@link outsideRender}
    */
   async set(cacheKey, data, ctx) {
     if (this.isBuildTime) {
@@ -76045,20 +76504,29 @@ var CdkNextjsCacheHandler = class _CdkNextjsCacheHandler {
       }
       return;
     }
-    this.debug(`Cache ${data ? "write" : "delete"}: ${cacheKey}`);
-    await this.memoryHandler.set(cacheKey, data);
-    await this.s3DynamoHandler.set(cacheKey, data, ctx);
+    await outsideRender(async () => {
+      this.debug(`Cache ${data ? "write" : "delete"}: ${cacheKey}`);
+      await this.memoryHandler.set(
+        cacheKey,
+        data,
+        void 0,
+        getCacheControl(ctx)
+      );
+      await this.s3DynamoHandler.set(cacheKey, data, ctx);
+    });
   }
   /**
    * Revalidate tags
    * - Build time: Not implemented
-   * - Runtime: Delegate to S3/DynamoDB handler
+   * - Runtime: Delegate to S3/DynamoDB handler, {@link outsideRender}
    */
   async revalidateTag(tag, durations) {
     if (this.isBuildTime) {
       return;
     }
-    await this.s3DynamoHandler.revalidateTag(tag, durations);
+    await outsideRender(
+      () => this.s3DynamoHandler.revalidateTag(tag, durations)
+    );
   }
   /**
    * Deliberately a no-op. Next.js calls `resetRequestCache` at the start of