cdk-nextjs 0.7.5 → 0.7.7

package/lib/adapter/aws-cache-store.d.ts

@@ -25,6 +25,8 @@ export declare function resolveAwsCacheConfig(): AwsCacheConfig;
  * which is what keeps it disjoint from {@link useCacheS3Key}.
  */
 export declare function buildS3Key(buildId: string, cacheKey: string): string;
+/** `{buildId}/` + {@link cacheObjectName}: the S3 object an entry is stored in. */
+export declare function s3ObjectKey(buildId: string, cacheKey: string): string;
 /**
  * The folder under the build prefix that `'use cache'` entries are stored in.
  * @see useCacheS3Key
@@ -36,8 +38,9 @@ export declare const USE_CACHE_KEY_PREFIX = "_use-cache";
  * Hashed because a `'use cache'` key is the serialized arguments of the call and
  * has no length limit, where an S3 key stops at 1024 bytes. The `.entry` suffix
  * rather than `.json` is what makes a collision with the incremental cache
- * impossible rather than unlikely: every key {@link buildS3Key} writes ends in
- * `.json`, including one for a route that happens to be named `/_use-cache/…`.
+ * impossible rather than unlikely: every object {@link s3ObjectKey} names ends
+ * in `.json` or `.long`, including one for a route that happens to be named
+ * `/_use-cache/…`.
  * Still under the build prefix, so post-deploy pruning drops them with the build.
  */
 export declare function useCacheS3Key(buildId: string, keyHash: string): string;
@@ -113,9 +116,36 @@ export declare const BATCH_GET_MAX_KEYS = 100;
  * revalidation log, the reads scale with instances instead of requests or tags.
  */
 export declare const DEFAULT_TAG_REFRESH_MS = 1000;
+/**
+ * How far past `refreshIntervalMs` the last refresh may have settled before a
+ * `'use cache'` request waits for the next one (see
+ * {@link TrackedTagMarkers.behind}). An instance serving steady traffic stays
+ * inside it; one that sat idle, or frozen between Lambda invocations, does not.
+ */
+export declare const TAG_REFRESH_GRACE_MS = 1000;
+/** DynamoDB's limit on a sort key, in UTF-8 bytes. */
+export declare const MAX_SORT_KEY_BYTES = 1024;
+/**
+ * `#<sha256(tag)>`, standing in for a tag in a sort key it would push past
+ * {@link MAX_SORT_KEY_BYTES}. Next.js caps the tags an app names, but not an
+ * implicit `_N_T_/…` tag, which is as long as its path, and a rejected write
+ * left `revalidatePath` on a long path recorded nowhere.
+ */
+export declare function hashedTag(tag: string): string;
+/**
+ * The longest tag a sort key spells out; past it, {@link sortKeyTag} hashes
+ * it. One cap for every row the tag is in, so a row's writer and reader agree
+ * without each working out what else shares its key. It leaves room for the
+ * most any row puts beside the tag: a mapping row's `#<buildId>/#<sha256>`,
+ * with the build ID capped at `MAX_BUILD_ID_BYTES`.
+ */
+export declare const MAX_TAG_BYTES = 768;
+/** `tag` as a sort key spells it: itself, or {@link hashedTag} past {@link MAX_TAG_BYTES}. */
+export declare function sortKeyTag(tag: string): string;
 /**
  * The bare-tag marker rows of the revalidation table (`pk = buildId`,
- * `sk = tag`), which record when a tag was last revalidated and how.
+ * `sk = tag`, or {@link hashedTag} past {@link MAX_TAG_BYTES}), which record when a tag
+ * was last revalidated and how.
  *
  * The table also holds the incremental cache's `tag#s3Key` mapping rows, which
  * are its own business and stay in `S3CacheHandler`: only the markers mean the
@@ -166,7 +196,8 @@ export interface RevalidationLogRow {
 /**
  * The revalidation log: one row per tag revalidation (`pk = <buildId>#log`,
  * `sk = <Date.now(), zero-padded>#<tag>`), which expires after
- * {@link REVALIDATION_LOG_TTL_MS}.
+ * {@link REVALIDATION_LOG_TTL_MS}. A tag past {@link MAX_TAG_BYTES} is
+ * {@link hashedTag} there, and spelled out in the row's `longTag` instead.
  *
  * The marker rows stay the source of truth. The log exists so an instance
  * can ask "what was revalidated since I last looked?" in one `Query`, instead
@@ -278,6 +309,14 @@ export type TrackedTagMarkersOptions = TagTable & {
     /** `Math.random`, for when each tag's re-read comes due. */
     random?: () => number;
     debug?: (message: string) => void;
+    /**
+     * Whether the process can be frozen with a refresh in flight, as a Lambda
+     * sandbox is between invocations: then a timer checks it kept running, and
+     * one that spanned a freeze does not count. A container is never frozen,
+     * so it skips the timer and waits for the refresh in flight, however slow.
+     * @default false
+     */
+    canFreeze?: boolean;
 };
 /**
  * One instance's copy of the marker rows of the tags it has needed, kept
@@ -298,15 +337,19 @@ export type TrackedTagMarkersOptions = TagTable & {
  * The cost is bounded per instance, not per request:
  * - {@link ensure} reads a tag's marker the first time it is needed and not
  *   again until it is evicted, so a tag costs one read per instance, not one
- *   per request.
+ *   per request. An entry created since {@link completeSince} needs no read
+ *   at all.
  * - {@link refresh}, at most once per `refreshIntervalMs`, sends one `Query`
  *   for the log rows written since the last one, and applies those of tags
  *   this instance tracks. Concurrent callers share it. Alongside, it re-reads
  *   the markers of up to {@link BATCH_GET_MAX_KEYS} tags not read for
  *   {@link DEFAULT_TAG_RESYNC_MS}, in one `BatchGetItem`.
  * A revalidation on another instance is therefore seen within
- * `refreshIntervalMs` (plus the query itself). The instance that ran it applies
- * it itself, at once, with {@link set}.
+ * `refreshIntervalMs` (plus the query itself) - by `'use cache'`, from the
+ * first request after the query returns, since its `refreshTags` does not wait
+ * for it (see `tagMethods`) unless the instance is {@link behind}, which the
+ * runtime settles before a page render starts ({@link catchUp}). The instance
+ * that ran it applies it itself, at once, with {@link set}.
  */
 export declare class TrackedTagMarkers {
     private readonly markers;
@@ -332,10 +375,64 @@ export declare class TrackedTagMarkers {
      * result rather than dropped.
      */
     private readonly pendingRows;
+    /**
+     * 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.
+     */
+    private readonly logOnly;
+    /** See {@link completeSince}. */
+    private 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}).
+     */
+    private readonly laterFloors;
+    /** The in-memory entry stores judged by {@link completeSince}. */
+    private readonly entryStores;
+    /** How many times {@link forget} ran: a read started before one is made again. */
+    private forgotten;
     /** Tracked tags whose read failed, for the next refresh to read again. */
     private readonly unread;
+    /**
+     * Set inside a page render {@link catchUp} let go, for that render alone.
+     * See {@link behindInRender}.
+     */
+    private readonly caughtUpRender;
+    /** When `sync` last scanned the entry stores ({@link oldestEntry}). */
+    private lastEntryScan;
+    /**
+     * 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.
+     */
+    private prunedAgainst;
+    /** When the last refresh started, or was skipped. */
     private lastRefresh;
+    /**
+     * 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.
+     */
     private 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.
+     */
+    private lastTick;
+    /** Whether a tick came late since {@link refreshing} started. */
+    private pausedWhileRefreshing;
+    private ticker;
+    private readonly canFreeze;
+    /**
+     * When the last refresh settled, either way, unless it spanned a pause: what
+     * it knows is from then. See {@link behind}.
+     */
+    private settledAt;
     /**
      * Where the next log query starts (`clock()`): the last successful one's
      * start, less {@link REVALIDATION_LOG_LOOKBACK_MS}.
@@ -350,6 +447,41 @@ export declare class TrackedTagMarkers {
     constructor(options: TrackedTagMarkersOptions);
     /** `tag`'s marker as this instance knows it, if it tracks `tag`. */
     get(tag: string): TagMarker | undefined;
+    /**
+     * 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(): number;
+    /**
+     * 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: (scan: boolean) => number, holdsAny?: () => boolean): void;
     /**
      * Track `tag` with `marker`: what this instance just wrote, which it knows
      * without reading it back.
@@ -381,11 +513,73 @@ export declare class TrackedTagMarkers {
      * tags may have been revalidated at any time before.
      */
     ensure(tags: readonly string[]): Promise<void>;
+    /**
+     * {@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.
+     */
+    private startRead;
+    /**
+     * 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(): boolean;
+    /**
+     * {@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(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * {@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.
+     */
+    catchUp<T>(render: () => Promise<T>): Promise<T>;
+    /** Whether `at` is more than the interval and the grace ago. */
+    private overdue;
     /**
      * Catch up on revalidations other instances ran, at most once per
      * `refreshIntervalMs`. See {@link TrackedTagMarkers} for the cost.
      */
     refresh(): Promise<void>;
+    private startTicking;
+    private stopTicking;
+    /**
+     * 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).
+     */
+    private pausedSinceRefreshStarted;
     /**
      * 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.
@@ -458,6 +652,47 @@ export declare class TrackedTagMarkers {
      */
     private readInto;
     private takePendingRows;
+    /**
+     * What this instance knows of `tag`: tracked, or from the log alone -
+     * including rows that arrived while its first read is in flight.
+     */
+    private knownMarker;
+    /**
+     * 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.
+     */
+    private rememberLogged;
+    /**
+     * 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.
+     */
+    private pruneLogged;
+    /**
+     * The oldest entry timestamp of any registered store, `Infinity` with none:
+     * early, never late, unless `scan`.
+     */
+    private oldestEntry;
+    /**
+     * 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.
+     */
+    private raiseFloor;
+    /**
+     * 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.
+     */
+    private laterFloor;
     /** Record that `tag`'s marker was known from the table at `at`. */
     private known;
     private remember;