sailfork / t3code-github / .repos/ alchemy-effect/ packages/ frontend-frameworks/ src/ nextjs/ cache-handler.ts

/**
 * `@alchemy.run/frontend-frameworks/nextjs/cache-handler` — Next.js
 * `cacheHandler` backed by S3, for Next's standalone server on AWS Lambda
 * Web Functions.
 *
 * A Web Function runs Next as a long-lived server, so revalidation and image
 * optimization happen in-process the way they do under `next start`. What
 * the server can't do is keep its cache on disk: the code directory is
 * read-only, and every environment has its own `/tmp`. This handler keeps
 * Next's own semantics by extending its `FileSystemCache`, and moves the
 * shared state to S3:
 *
 * - entries (ISR pages, route handlers, the fetch cache, optimized images)
 *   are S3 objects; a miss falls back to Next's read of the prerendered
 *   build output
 * - `revalidateTag` writes one tag manifest object (conditional writes),
 *   which every environment reads into Next's in-process tags manifest
 *   before checking an entry
 *
 * The file is copied next to the standalone `server.js` and loaded by Next
 * at runtime, so it imports only Node built-ins (and Next itself, from the
 * standalone `node_modules`). Requests are signed with the function's own
 * credentials from the environment. Configuration:
 *
 * - `CACHE_BUCKET_NAME` — the bucket
 * - `CACHE_BUCKET_KEY_PREFIX` — key prefix (default `_cache`)
 */
import { createHash, createHmac } from "node:crypto";
import { createRequire } from "node:module";

const require = createRequire(import.meta.url);

interface TagEntry {
  stale?: number;
  expired?: number;
}

interface FileSystemCacheLike {
  get(key: string, ctx: Record<string, any>): Promise<CacheEntry | null>;
  set(key: string, data: any, ctx: Record<string, any>): Promise<void>;
  revalidateTag(tags: string | string[], durations?: { expire?: number }): Promise<void>;
  resetRequestCache(): void;
}

interface CacheEntry {
  lastModified: number;
  value: any;
}

const FileSystemCache: new (ctx: Record<string, any>) => FileSystemCacheLike =
  require("next/dist/server/lib/incremental-cache/file-system-cache").default;
const { tagsManifest } =
  require("next/dist/server/lib/incremental-cache/tags-manifest.external") as {
    tagsManifest: Map<string, TagEntry>;
  };

const NEXT_CACHE_TAGS_HEADER = "x-next-cache-tags";
/** How long one environment trusts its copy of the tag manifest. */
const TAG_MANIFEST_TTL_MS = 1_000;

// ---------------------------------------------------------------------------
// S3 over fetch, signed with SigV4
// ---------------------------------------------------------------------------

const sha256Hex = (data: string | Uint8Array) => createHash("sha256").update(data).digest("hex");
const hmac = (key: string | Uint8Array, data: string) =>
  createHmac("sha256", key).update(data).digest();

const encodeKey = (key: string) =>
  key
    .split("/")
    .map((segment) =>
      encodeURIComponent(segment).replace(
        /[!'()*]/g,
        (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
      ),
    )
    .join("/");

interface S3Response {
  status: number;
  etag: string | undefined;
  body: string;
}

const s3 = async (
  method: "GET" | "PUT",
  key: string,
  options: { body?: string; headers?: Record<string, string> } = {},
): Promise<S3Response> => {
  const bucket = process.env.CACHE_BUCKET_NAME!;
  const region = process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION ?? "us-east-1";
  const host = `${bucket}.s3.${region}.amazonaws.com`;
  const path = `/${encodeKey(key)}`;
  const body = options.body ?? "";
  const now = new Date();
  const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");
  const date = amzDate.slice(0, 8);
  const headers: Record<string, string> = {
    host,
    "x-amz-content-sha256": sha256Hex(body),
    "x-amz-date": amzDate,
    ...(process.env.AWS_SESSION_TOKEN
      ? { "x-amz-security-token": process.env.AWS_SESSION_TOKEN }
      : {}),
    ...Object.fromEntries(
      Object.entries(options.headers ?? {}).map(([k, v]) => [k.toLowerCase(), v]),
    ),
  };
  const signedHeaders = Object.keys(headers).sort();
  const canonicalRequest = [
    method,
    path,
    "",
    ...signedHeaders.map((name) => `${name}:${headers[name]!.trim()}`),
    "",
    signedHeaders.join(";"),
    headers["x-amz-content-sha256"],
  ].join("\n");
  const scope = `${date}/${region}/s3/aws4_request`;
  const stringToSign = ["AWS4-HMAC-SHA256", amzDate, scope, sha256Hex(canonicalRequest)].join("\n");
  const signingKey = hmac(
    hmac(hmac(hmac(`AWS4${process.env.AWS_SECRET_ACCESS_KEY}`, date), region), "s3"),
    "aws4_request",
  );
  const signature = createHmac("sha256", signingKey).update(stringToSign).digest("hex");
  const { host: _host, ...sent } = headers;
  const response = await fetch(`https://${host}${path}`, {
    method,
    headers: {
      ...sent,
      authorization: `AWS4-HMAC-SHA256 Credential=${process.env.AWS_ACCESS_KEY_ID}/${scope}, SignedHeaders=${signedHeaders.join(";")}, Signature=${signature}`,
    },
    ...(method === "PUT" ? { body } : {}),
  });
  return {
    status: response.status,
    etag: response.headers.get("etag") ?? undefined,
    body: await response.text(),
  };
};

const prefix = () => (process.env.CACHE_BUCKET_KEY_PREFIX ?? "_cache").replace(/\/+$/, "");

// ---------------------------------------------------------------------------
// Values: Buffers and Maps survive the round trip through JSON
// ---------------------------------------------------------------------------

const encode = (value: unknown) =>
  JSON.stringify(value, function (this: Record<string, unknown>, key, current) {
    const original = this[key];
    if (Buffer.isBuffer(original) || original instanceof Uint8Array) {
      return { __alchemy: "bytes", data: Buffer.from(original).toString("base64") };
    }
    if (original instanceof Map) {
      return { __alchemy: "map", data: [...original.entries()] };
    }
    return current;
  });

const decode = (text: string) =>
  JSON.parse(text, (_key, value) => {
    if (value && typeof value === "object" && "__alchemy" in value) {
      if (value.__alchemy === "bytes") return Buffer.from(value.data, "base64");
      if (value.__alchemy === "map") return new Map(value.data);
    }
    return value;
  });

// ---------------------------------------------------------------------------
// The shared tag manifest
// ---------------------------------------------------------------------------

let manifest: { tags: Record<string, TagEntry>; etag: string | undefined; fetchedAt: number } = {
  tags: {},
  etag: undefined,
  fetchedAt: 0,
};

const manifestKey = () => `${prefix()}/tags.json`;

const readManifest = async () => {
  const response = await s3("GET", manifestKey());
  if (response.status === 404) return { tags: {}, etag: undefined };
  if (response.status !== 200) {
    throw new Error(`Reading the Next.js tag manifest failed: ${response.status}`);
  }
  return { tags: JSON.parse(response.body) as Record<string, TagEntry>, etag: response.etag };
};

/** Copy the shared manifest into Next's in-process one. */
const applyManifest = (tags: Record<string, TagEntry>) => {
  for (const [tag, entry] of Object.entries(tags)) tagsManifest.set(tag, entry);
};

const refreshManifest = async () => {
  if (Date.now() - manifest.fetchedAt < TAG_MANIFEST_TTL_MS) return;
  const { tags, etag } = await readManifest();
  manifest = { tags, etag, fetchedAt: Date.now() };
  applyManifest(tags);
};

/** Read-modify-write the manifest, retrying when another writer won. */
const updateManifest = async (update: (tags: Record<string, TagEntry>) => void) => {
  for (let attempt = 0; attempt < 10; attempt++) {
    const { tags, etag } = await readManifest();
    update(tags);
    const response = await s3("PUT", manifestKey(), {
      body: JSON.stringify(tags),
      headers: {
        "content-type": "application/json",
        ...(etag ? { "if-match": etag } : { "if-none-match": "*" }),
      },
    });
    if (response.status === 200) {
      manifest = { tags, etag: response.etag, fetchedAt: Date.now() };
      applyManifest(tags);
      return;
    }
    if (response.status !== 412 && response.status !== 409) {
      throw new Error(`Writing the Next.js tag manifest failed: ${response.status}`);
    }
  }
  throw new Error("Writing the Next.js tag manifest kept conflicting");
};

// ---------------------------------------------------------------------------
// The handler
// ---------------------------------------------------------------------------

const entryKey = (key: string) => `${prefix()}/entries/${sha256Hex(key)}.json`;

/** Same expiry rules as Next's FileSystemCache, against the synced manifest. */
const isExpired = (entry: CacheEntry, ctx: Record<string, any>) => {
  const expired = (tags: string[]) =>
    tags.some((tag) => {
      const at = tagsManifest.get(tag)?.expired;
      return typeof at === "number" && at <= Date.now() && at > entry.lastModified;
    });
  const kind = entry.value?.kind;
  if (kind === "APP_PAGE" || kind === "APP_ROUTE" || kind === "PAGES") {
    const header = entry.value.headers?.[NEXT_CACHE_TAGS_HEADER];
    return typeof header === "string" && expired(header.split(","));
  }
  if (kind === "FETCH" && ctx.kind === "FETCH") {
    return expired([...(ctx.tags ?? []), ...(ctx.softTags ?? [])]);
  }
  return false;
};

export default class AlchemyS3CacheHandler extends FileSystemCache {
  constructor(ctx: Record<string, any>) {
    // Reads of the prerendered build output stay Next's. Nothing is written
    // to the read-only code directory, and there is no in-process memory
    // layer: another environment's revalidation must show up here.
    super({ ...ctx, flushToDisk: false, maxMemoryCacheSize: 0 });
  }

  override async get(key: string, ctx: Record<string, any>): Promise<CacheEntry | null> {
    await refreshManifest();
    const response = await s3("GET", entryKey(key));
    let entry: CacheEntry | null = null;
    if (response.status === 200) {
      entry = decode(response.body) as CacheEntry;
    } else if (response.status === 404) {
      // Not written since the build: Next's prerendered output, if any.
      // Next dates it by file time, which the deploy archive normalizes, so
      // date it by the build: otherwise every prerendered page looks stale
      // on its first request and renders again.
      entry = await super.get(key, ctx);
      const buildTime = Number(process.env.ALCHEMY_NEXT_BUILD_TIME);
      if (entry !== null && Number.isFinite(buildTime) && buildTime > 0) {
        entry = { ...entry, lastModified: buildTime };
      }
    } else {
      throw new Error(`Reading the Next.js cache failed: ${response.status}`);
    }
    if (entry === null || isExpired(entry, ctx)) return null;
    return entry;
  }

  override async set(key: string, data: any, ctx: Record<string, any>): Promise<void> {
    await super.set(key, data, ctx);
    if (!data) return;
    const response = await s3("PUT", entryKey(key), {
      body: encode({ lastModified: Date.now(), value: data }),
      headers: { "content-type": "application/json" },
    });
    if (response.status !== 200) {
      throw new Error(`Writing the Next.js cache failed: ${response.status}`);
    }
  }

  override async revalidateTag(
    tags: string | string[],
    durations?: { expire?: number },
  ): Promise<void> {
    const list = typeof tags === "string" ? [tags] : tags;
    if (list.length === 0) return;
    await updateManifest((manifestTags) => {
      const now = Date.now();
      for (const tag of list) {
        const existing = manifestTags[tag] ?? {};
        manifestTags[tag] = durations
          ? {
              ...existing,
              stale: now,
              ...(durations.expire !== undefined ? { expired: now + durations.expire * 1000 } : {}),
            }
          : { ...existing, expired: now };
      }
    });
  }
}