The best way to control Claude Code, Codex and more from any computer or phone

main
ts 314 lines 11.6 KB
Raw
1 /**
2 * `@alchemy.run/frontend-frameworks/nextjs/cache-handler` — Next.js
3 * `cacheHandler` backed by S3, for Next's standalone server on AWS Lambda
4 * Web Functions.
5 *
6 * A Web Function runs Next as a long-lived server, so revalidation and image
7 * optimization happen in-process the way they do under `next start`. What
8 * the server can't do is keep its cache on disk: the code directory is
9 * read-only, and every environment has its own `/tmp`. This handler keeps
10 * Next's own semantics by extending its `FileSystemCache`, and moves the
11 * shared state to S3:
12 *
13 * - entries (ISR pages, route handlers, the fetch cache, optimized images)
14 * are S3 objects; a miss falls back to Next's read of the prerendered
15 * build output
16 * - `revalidateTag` writes one tag manifest object (conditional writes),
17 * which every environment reads into Next's in-process tags manifest
18 * before checking an entry
19 *
20 * The file is copied next to the standalone `server.js` and loaded by Next
21 * at runtime, so it imports only Node built-ins (and Next itself, from the
22 * standalone `node_modules`). Requests are signed with the function's own
23 * credentials from the environment. Configuration:
24 *
25 * - `CACHE_BUCKET_NAME` — the bucket
26 * - `CACHE_BUCKET_KEY_PREFIX` — key prefix (default `_cache`)
27 */
28 import { createHash, createHmac } from "node:crypto";
29 import { createRequire } from "node:module";
30
31 const require = createRequire(import.meta.url);
32
33 interface TagEntry {
34 stale?: number;
35 expired?: number;
36 }
37
38 interface FileSystemCacheLike {
39 get(key: string, ctx: Record<string, any>): Promise<CacheEntry | null>;
40 set(key: string, data: any, ctx: Record<string, any>): Promise<void>;
41 revalidateTag(tags: string | string[], durations?: { expire?: number }): Promise<void>;
42 resetRequestCache(): void;
43 }
44
45 interface CacheEntry {
46 lastModified: number;
47 value: any;
48 }
49
50 const FileSystemCache: new (ctx: Record<string, any>) => FileSystemCacheLike =
51 require("next/dist/server/lib/incremental-cache/file-system-cache").default;
52 const { tagsManifest } =
53 require("next/dist/server/lib/incremental-cache/tags-manifest.external") as {
54 tagsManifest: Map<string, TagEntry>;
55 };
56
57 const NEXT_CACHE_TAGS_HEADER = "x-next-cache-tags";
58 /** How long one environment trusts its copy of the tag manifest. */
59 const TAG_MANIFEST_TTL_MS = 1_000;
60
61 // ---------------------------------------------------------------------------
62 // S3 over fetch, signed with SigV4
63 // ---------------------------------------------------------------------------
64
65 const sha256Hex = (data: string | Uint8Array) => createHash("sha256").update(data).digest("hex");
66 const hmac = (key: string | Uint8Array, data: string) =>
67 createHmac("sha256", key).update(data).digest();
68
69 const encodeKey = (key: string) =>
70 key
71 .split("/")
72 .map((segment) =>
73 encodeURIComponent(segment).replace(
74 /[!'()*]/g,
75 (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
76 ),
77 )
78 .join("/");
79
80 interface S3Response {
81 status: number;
82 etag: string | undefined;
83 body: string;
84 }
85
86 const s3 = async (
87 method: "GET" | "PUT",
88 key: string,
89 options: { body?: string; headers?: Record<string, string> } = {},
90 ): Promise<S3Response> => {
91 const bucket = process.env.CACHE_BUCKET_NAME!;
92 const region = process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION ?? "us-east-1";
93 const host = `${bucket}.s3.${region}.amazonaws.com`;
94 const path = `/${encodeKey(key)}`;
95 const body = options.body ?? "";
96 const now = new Date();
97 const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");
98 const date = amzDate.slice(0, 8);
99 const headers: Record<string, string> = {
100 host,
101 "x-amz-content-sha256": sha256Hex(body),
102 "x-amz-date": amzDate,
103 ...(process.env.AWS_SESSION_TOKEN
104 ? { "x-amz-security-token": process.env.AWS_SESSION_TOKEN }
105 : {}),
106 ...Object.fromEntries(
107 Object.entries(options.headers ?? {}).map(([k, v]) => [k.toLowerCase(), v]),
108 ),
109 };
110 const signedHeaders = Object.keys(headers).sort();
111 const canonicalRequest = [
112 method,
113 path,
114 "",
115 ...signedHeaders.map((name) => `${name}:${headers[name]!.trim()}`),
116 "",
117 signedHeaders.join(";"),
118 headers["x-amz-content-sha256"],
119 ].join("\n");
120 const scope = `${date}/${region}/s3/aws4_request`;
121 const stringToSign = ["AWS4-HMAC-SHA256", amzDate, scope, sha256Hex(canonicalRequest)].join("\n");
122 const signingKey = hmac(
123 hmac(hmac(hmac(`AWS4${process.env.AWS_SECRET_ACCESS_KEY}`, date), region), "s3"),
124 "aws4_request",
125 );
126 const signature = createHmac("sha256", signingKey).update(stringToSign).digest("hex");
127 const { host: _host, ...sent } = headers;
128 const response = await fetch(`https://${host}${path}`, {
129 method,
130 headers: {
131 ...sent,
132 authorization: `AWS4-HMAC-SHA256 Credential=${process.env.AWS_ACCESS_KEY_ID}/${scope}, SignedHeaders=${signedHeaders.join(";")}, Signature=${signature}`,
133 },
134 ...(method === "PUT" ? { body } : {}),
135 });
136 return {
137 status: response.status,
138 etag: response.headers.get("etag") ?? undefined,
139 body: await response.text(),
140 };
141 };
142
143 const prefix = () => (process.env.CACHE_BUCKET_KEY_PREFIX ?? "_cache").replace(/\/+$/, "");
144
145 // ---------------------------------------------------------------------------
146 // Values: Buffers and Maps survive the round trip through JSON
147 // ---------------------------------------------------------------------------
148
149 const encode = (value: unknown) =>
150 JSON.stringify(value, function (this: Record<string, unknown>, key, current) {
151 const original = this[key];
152 if (Buffer.isBuffer(original) || original instanceof Uint8Array) {
153 return { __alchemy: "bytes", data: Buffer.from(original).toString("base64") };
154 }
155 if (original instanceof Map) {
156 return { __alchemy: "map", data: [...original.entries()] };
157 }
158 return current;
159 });
160
161 const decode = (text: string) =>
162 JSON.parse(text, (_key, value) => {
163 if (value && typeof value === "object" && "__alchemy" in value) {
164 if (value.__alchemy === "bytes") return Buffer.from(value.data, "base64");
165 if (value.__alchemy === "map") return new Map(value.data);
166 }
167 return value;
168 });
169
170 // ---------------------------------------------------------------------------
171 // The shared tag manifest
172 // ---------------------------------------------------------------------------
173
174 let manifest: { tags: Record<string, TagEntry>; etag: string | undefined; fetchedAt: number } = {
175 tags: {},
176 etag: undefined,
177 fetchedAt: 0,
178 };
179
180 const manifestKey = () => `${prefix()}/tags.json`;
181
182 const readManifest = async () => {
183 const response = await s3("GET", manifestKey());
184 if (response.status === 404) return { tags: {}, etag: undefined };
185 if (response.status !== 200) {
186 throw new Error(`Reading the Next.js tag manifest failed: ${response.status}`);
187 }
188 return { tags: JSON.parse(response.body) as Record<string, TagEntry>, etag: response.etag };
189 };
190
191 /** Copy the shared manifest into Next's in-process one. */
192 const applyManifest = (tags: Record<string, TagEntry>) => {
193 for (const [tag, entry] of Object.entries(tags)) tagsManifest.set(tag, entry);
194 };
195
196 const refreshManifest = async () => {
197 if (Date.now() - manifest.fetchedAt < TAG_MANIFEST_TTL_MS) return;
198 const { tags, etag } = await readManifest();
199 manifest = { tags, etag, fetchedAt: Date.now() };
200 applyManifest(tags);
201 };
202
203 /** Read-modify-write the manifest, retrying when another writer won. */
204 const updateManifest = async (update: (tags: Record<string, TagEntry>) => void) => {
205 for (let attempt = 0; attempt < 10; attempt++) {
206 const { tags, etag } = await readManifest();
207 update(tags);
208 const response = await s3("PUT", manifestKey(), {
209 body: JSON.stringify(tags),
210 headers: {
211 "content-type": "application/json",
212 ...(etag ? { "if-match": etag } : { "if-none-match": "*" }),
213 },
214 });
215 if (response.status === 200) {
216 manifest = { tags, etag: response.etag, fetchedAt: Date.now() };
217 applyManifest(tags);
218 return;
219 }
220 if (response.status !== 412 && response.status !== 409) {
221 throw new Error(`Writing the Next.js tag manifest failed: ${response.status}`);
222 }
223 }
224 throw new Error("Writing the Next.js tag manifest kept conflicting");
225 };
226
227 // ---------------------------------------------------------------------------
228 // The handler
229 // ---------------------------------------------------------------------------
230
231 const entryKey = (key: string) => `${prefix()}/entries/${sha256Hex(key)}.json`;
232
233 /** Same expiry rules as Next's FileSystemCache, against the synced manifest. */
234 const isExpired = (entry: CacheEntry, ctx: Record<string, any>) => {
235 const expired = (tags: string[]) =>
236 tags.some((tag) => {
237 const at = tagsManifest.get(tag)?.expired;
238 return typeof at === "number" && at <= Date.now() && at > entry.lastModified;
239 });
240 const kind = entry.value?.kind;
241 if (kind === "APP_PAGE" || kind === "APP_ROUTE" || kind === "PAGES") {
242 const header = entry.value.headers?.[NEXT_CACHE_TAGS_HEADER];
243 return typeof header === "string" && expired(header.split(","));
244 }
245 if (kind === "FETCH" && ctx.kind === "FETCH") {
246 return expired([...(ctx.tags ?? []), ...(ctx.softTags ?? [])]);
247 }
248 return false;
249 };
250
251 export default class AlchemyS3CacheHandler extends FileSystemCache {
252 constructor(ctx: Record<string, any>) {
253 // Reads of the prerendered build output stay Next's. Nothing is written
254 // to the read-only code directory, and there is no in-process memory
255 // layer: another environment's revalidation must show up here.
256 super({ ...ctx, flushToDisk: false, maxMemoryCacheSize: 0 });
257 }
258
259 override async get(key: string, ctx: Record<string, any>): Promise<CacheEntry | null> {
260 await refreshManifest();
261 const response = await s3("GET", entryKey(key));
262 let entry: CacheEntry | null = null;
263 if (response.status === 200) {
264 entry = decode(response.body) as CacheEntry;
265 } else if (response.status === 404) {
266 // Not written since the build: Next's prerendered output, if any.
267 // Next dates it by file time, which the deploy archive normalizes, so
268 // date it by the build: otherwise every prerendered page looks stale
269 // on its first request and renders again.
270 entry = await super.get(key, ctx);
271 const buildTime = Number(process.env.ALCHEMY_NEXT_BUILD_TIME);
272 if (entry !== null && Number.isFinite(buildTime) && buildTime > 0) {
273 entry = { ...entry, lastModified: buildTime };
274 }
275 } else {
276 throw new Error(`Reading the Next.js cache failed: ${response.status}`);
277 }
278 if (entry === null || isExpired(entry, ctx)) return null;
279 return entry;
280 }
281
282 override async set(key: string, data: any, ctx: Record<string, any>): Promise<void> {
283 await super.set(key, data, ctx);
284 if (!data) return;
285 const response = await s3("PUT", entryKey(key), {
286 body: encode({ lastModified: Date.now(), value: data }),
287 headers: { "content-type": "application/json" },
288 });
289 if (response.status !== 200) {
290 throw new Error(`Writing the Next.js cache failed: ${response.status}`);
291 }
292 }
293
294 override async revalidateTag(
295 tags: string | string[],
296 durations?: { expire?: number },
297 ): Promise<void> {
298 const list = typeof tags === "string" ? [tags] : tags;
299 if (list.length === 0) return;
300 await updateManifest((manifestTags) => {
301 const now = Date.now();
302 for (const tag of list) {
303 const existing = manifestTags[tag] ?? {};
304 manifestTags[tag] = durations
305 ? {
306 ...existing,
307 stale: now,
308 ...(durations.expire !== undefined ? { expired: now + durations.expire * 1000 } : {}),
309 }
310 : { ...existing, expired: now };
311 }
312 });
313 }
314 }