cdk-nextjs 0.6.1 → 0.7.0

package/lib/adapter/s3-cache-handler.d.ts

@@ -1,68 +1,207 @@
 import { CacheHandler, CacheHandlerValue, CacheHandlerContext } from "next/dist/server/lib/incremental-cache";
 import { IncrementalCacheValue, GetIncrementalFetchCacheContext, GetIncrementalResponseCacheContext, SetIncrementalFetchCacheContext, SetIncrementalResponseCacheContext } from "next/dist/server/response-cache";
-interface S3CacheConfig {
-    bucketName: string;
-    region: string;
-    buildId: string;
-}
-interface DynamoDBRevalidationConfig {
-    tableName: string;
-    region: string;
-    buildId: string;
-}
-interface CloudFrontInvalidationConfig {
-    /**
-     * Name (not value) of the SSM Parameter holding the distribution ID.
-     *
-     * The distribution ID itself can't be passed as a plain env var: CDK
-     * constructs the Lambda/Fargate task before the distribution exists (the
-     * distribution's origin references the compute's function URL/ALB), so
-     * embedding the distribution's physical ID directly in the compute's
-     * environment or IAM policy would create a circular CloudFormation
-     * dependency. The parameter *name* is static and known at synth time, so
-     * it can be safely embedded; only its *value* depends on the distribution.
-     */
-    distributionIdParameterName: string;
-    region: string;
-}
+import { RevalidateDurations } from "./aws-cache-store";
 export interface S3CacheHandlerOptions {
     context: CacheHandlerContext;
-    s3Config?: Partial<S3CacheConfig>;
-    dynamoConfig?: Partial<DynamoDBRevalidationConfig>;
-    cloudFrontConfig?: Partial<CloudFrontInvalidationConfig>;
+    /**
+     * The app's `basePath`, for tests: read from `required-server-files.json`
+     * otherwise.
+     */
+    basePath?: string;
 }
 export declare class S3CacheHandler implements CacheHandler {
     private s3Client;
     private dynamoClient;
     private cloudFrontClient;
     private ssmClient;
-    private s3Config;
-    private dynamoConfig;
+    private bucket;
+    private tags;
+    private config;
     private cloudFrontConfig;
     private debug;
     private cachedDistributionId;
+    /**
+     * Cache keys this instance served stale because of a soft `revalidateTag`,
+     * whose regenerated entry `set` has yet to write.
+     *
+     * `revalidateTag(tag, profile)` invalidates CloudFront at once, but the next
+     * 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
+     * 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.
+     */
+    private softRevalidatedKeys;
+    /** @see buildTagManifest */
+    private buildTags;
     constructor(options: S3CacheHandlerOptions);
     get(cacheKey: string, ctx: GetIncrementalFetchCacheContext | GetIncrementalResponseCacheContext): Promise<CacheHandlerValue | null>;
+    /**
+     * Whether a tag revalidation has expired `entry`, for a `get` with `ctx`.
+     *
+     * Public because the in-memory layer in front of this handler has to ask too:
+     * a memory hit never reaches {@link get}, and without this check an instance
+     * other than the one that ran `revalidateTag` kept answering from memory for
+     * the whole memory TTL - long enough for CloudFront to cache the stale page
+     * again after the invalidation.
+     *
+     * Which tags to check depends on the kind, and Next.js's own
+     * `FileSystemCache.get` splits the same two ways: a response entry is checked
+     * against the tags *it* was stored with, but a `fetch` entry is checked
+     * against `[...ctx.tags, ...ctx.softTags]` — the tags of the request asking
+     * for it. That distinction is load-bearing, because a `fetch` entry is only
+     * ever stored with its *explicit* `cache: { tags }` and never with the
+     * implicit `_N_T_/<path>` chain, which arrives only as `ctx.softTags`.
+     * Reading the stored tags for a `fetch` too meant an untagged `force-cache`
+     * fetch had `[]`, skipped the check entirely, and no `revalidatePath` could
+     * ever evict it: a `force-dynamic` page whose data comes from such a fetch
+     * re-rendered on every request and still served the same body forever.
+     * Measured against next.js's `test/e2e/app-dir/revalidate-path-with-rewrites`.
+     *
+     * `cacheKey` is the key the entry was read under. A response entry found
+     * stale is remembered by it, for `set` to invalidate CloudFront again once
+     * its regeneration lands: see {@link softRevalidatedKeys}.
+     */
+    isRevalidated(entry: {
+        lastModified?: number;
+        tags?: string[];
+        value?: unknown;
+    }, ctx: GetIncrementalFetchCacheContext | GetIncrementalResponseCacheContext, cacheKey: string): Promise<boolean>;
+    /**
+     * Remember that `cacheKey` was served stale, when there is a distribution
+     * whose copy of it will need invalidating again. See
+     * {@link softRevalidatedKeys}.
+     */
+    private noteSoftRevalidated;
     set(cacheKey: string, data: IncrementalCacheValue | null, ctx: SetIncrementalFetchCacheContext | SetIncrementalResponseCacheContext): Promise<void>;
-    revalidateTag(tag: string | string[]): Promise<void>;
-    private revalidateSingleTag;
+    revalidateTag(tag: string | string[], durations?: RevalidateDurations): Promise<void>;
     /**
-     * Reverses `buildS3Key` to recover the request path CloudFront cached the
-     * response under. Fetch-cache entries (opaque hash keys, not page routes)
-     * translate to a path that won't match anything cached, which is harmless.
+     * The routes CloudFront could be holding a response for `tag` under -
+     * `truncated` when they could not all be named: more mapping rows than
+     * {@link MAX_TAG_QUERY_PAGES}, or no build tag manifest to read.
+     */
+    private tagRoutes;
+    /**
+     * The build-time prerenders' cache keys by tag ({@link INIT_CACHE_TAG_MANIFEST}),
+     * read from the cache bucket once per instance, or `undefined` when that
+     * failed, to be read again next time. A prerender is written by the adapter,
+     * never through `set`, so this is the only record of which tags name its
+     * CloudFront paths, and it is served with a year-long `s-maxage`.
+     */
+    private buildTagManifest;
+    /**
+     * Every mapping row for `tag`, following `LastEvaluatedKey`, and whether
+     * {@link MAX_TAG_QUERY_PAGES} cut the walk short.
+     *
+     * DynamoDB caps a Query at 1 MB of items regardless of how many match, and
+     * there is one row per tagged entry a runtime `set` wrote, so a large site
+     * passes 1 MB on a common tag. Stopping at the
+     * first page invalidates only that page's entries while still reporting
+     * success, which is indistinguishable from revalidation having worked.
+     */
+    private queryTagMappings;
+    /**
+     * Reverses `buildS3Key` to recover the route the response was cached for, for
+     * {@link cdnInvalidationPaths} to turn into the URIs CloudFront holds it under, or
+     * `undefined` for a key that names no cached URI.
+     *
+     * Two kinds of mapping row do not: a dynamic route template (`blog/[slug].json`,
+     * which the adapter's seeded entries include), and a fetch-cache entry, whose
+     * key is an opaque hash rather than a route. Both would invalidate a URI that
+     * cannot exist, and each one costs one of the fifteen wildcard paths an
+     * invalidation may carry — so they are dropped here rather than crowding out
+     * the real ones.
      */
     private s3KeyToInvalidationPath;
+    /**
+     * Invalidate `paths` in a single request, or the whole app
+     * ({@link wholeAppInvalidationPaths}) when they would not fit in one. See
+     * {@link MAX_WILDCARD_PATHS_PER_INVALIDATION}.
+     */
     private invalidateCloudFrontPaths;
     /**
-     * Resolves the distribution's physical ID via SSM Parameter Store, caching
-     * it for the lifetime of this instance. See `CloudFrontInvalidationConfig`
-     * for why this indirection (rather than a plain env var) is necessary.
+     * The distribution's physical ID, from the environment or else SSM Parameter
+     * Store, cached for the lifetime of this instance. See
+     * `CloudFrontInvalidationConfig` for why Functions need the indirection.
      */
     private getDistributionId;
     resetRequestCache(): Promise<void>;
+    /**
+     * Whether this deployment keeps `tag#s3Key` mapping rows at all.
+     *
+     * Their one reader is `revalidateTag`'s CloudFront invalidation, which needs
+     * the entries' paths - tag revalidation itself runs on the bare-tag marker
+     * rows. A deployment with no distribution (the Regional constructs) would pay
+     * a DynamoDB write per tag on every `set`, a Query per `revalidateTag`, and an
+     * extra S3 read before every delete, for rows nothing ever reads.
+     */
+    private get mapsTagsToPaths();
+    /** Whether there is a distribution to invalidate. */
+    private get invalidatesCdn();
+    /** `{buildId}/{cacheKey}.json`; see {@link buildS3Key}. */
     private buildS3Key;
     private storeDynamoDBTagMappings;
+    /**
+     * Drop the `tag#s3Key` mapping rows for an entry that no longer exists.
+     *
+     * The counterpart of {@link storeDynamoDBTagMappings}, and the reason its
+     * caller has to know the entry's tags: a mapping row's sort key starts with
+     * the tag, so the rows belonging to one cache key cannot be queried for - only
+     * a full scan of the build's partition would find them.
+     *
+     * Left behind, a row still resolves to a cache key on the next
+     * `revalidateTag`, which spends one of CloudFront's fifteen wildcard paths
+     * invalidating a URI whose entry was deleted - crowding out the paths that do
+     * need it, and past {@link MAX_WILDCARD_PATHS_PER_INVALIDATION} collapsing the
+     * whole app into one wildcard. The rows also count against the 1 MB a tag's Query returns, so
+     * enough of them push live entries onto a page
+     * {@link MAX_TAG_QUERY_PAGES} may not reach.
+     *
+     * Only the mapping rows: the bare-`tag` marker row `revalidateTag`
+     * writes belongs to the tag rather than to any entry, and `checkIfRevalidated`
+     * reads it for every *other* entry carrying that tag.
+     *
+     * Deliberately no CloudFront invalidation for the deleted path. The edge copy
+     * does outlive the object, but this runs on every revalidated `fetch` entry as
+     * well, where the key names no URI, and an invalidation request per deleted
+     * entry is a cost the TTL already bounds.
+     */
+    private deleteDynamoDBTagMappings;
+    /**
+     * The tags an entry about to be deleted was stored with.
+     *
+     * `ctx` carries them for a `fetch` delete, but a response delete arrives as
+     * `{ cacheControl, isRoutePPREnabled, isFallback }` - `ResponseCache.set`
+     * builds it that way - so the entry itself is the only source, and it has to
+     * be read before it is removed. That is one extra GET on a path that runs when
+     * a cached route starts answering `notFound()`: `IncrementalCache.set`
+     * forwards `ResponseCache`'s null value through to here.
+     *
+     * A page is also the case worth paying it for, since it carries the whole
+     * implicit `_N_T_/…` chain and therefore the most rows.
+     */
+    private storedEntryTags;
+    /**
+     * Whether any of `tags` was revalidated after this entry was stored, and how.
+     *
+     * Reads the per-tag marker rows `revalidateTag` writes, as this instance
+     * tracks them: see `TrackedTagMarkers` for when they are read.
+     * Scanning the tag's mapping rows instead would answer the wrong question:
+     * those rows exist per cache *key*, so which one a `Limit: 1` query returned
+     * depended on sort order, and an entry could be judged against another
+     * entry's timestamp.
+     *
+     * A tag revalidated with a profile only makes the entry *stale*: that is
+     * reported to Next.js through its tag manifest (see {@link nextTagsManifest})
+     * and answered `"stale"` here, so the entry is served while a background
+     * render replaces it. When the manifest cannot be reached a stale entry is
+     * reported expired instead - a blocking render, never a stale page presented
+     * as fresh.
+     */
     private checkIfRevalidated;
-    private deleteS3Entry;
 }
-export {};