@replayio-app-building/netlify-recorder 0.44.0 → 0.46.0

package/README.md

@@ -169,6 +169,21 @@ const status = await fetch(
 | `not_found` | 404 | Request ID not found in `backend_requests` |
 | `error` | 4xx/5xx | Validation error, auth failure, or recording failure |
 
+#### Warm-start replay (preceding requests)
+
+Netlify Functions run on AWS Lambda, where module-level state persists across invocations on the same container instance (warm starts). For example, a module-level `Map` used as a cache will retain entries across requests handled by the same container. This means a recording of a warm-start request may behave differently than the original if module-level state is empty.
+
+The recorder handles this automatically. `createRecordingRequestHandler` maintains a module-level `originalRequestId` that captures the ID of the first request handled by each module instance. Every subsequent request on the same instance includes this reference in its blob data, linking all requests from the same warm-start chain.
+
+When a recording is triggered for a request that has an `originalRequestId`, the recording service:
+
+1. Looks up all preceding requests from the same module instance (same `original_request_id`, earlier `created_at`)
+2. Fetches the blob data for each preceding request
+3. Replays the preceding requests in order on the handler module before executing the target request — each preceding request runs with its own replay interceptors so recorded network responses are served without making real calls
+4. Executes the target request, now with module-level state populated exactly as it was in production
+
+This is fully automatic — no configuration or code changes are needed beyond wrapping your handlers with `createRecordingRequestHandler`. The `original_request_id` column is stored in the `backend_requests` table and the preceding blob URLs are resolved server-side.
+
 ### 5. Create recordings programmatically
 
 Use `ensureRequestRecording` to turn a captured request into a Replay recording. It checks the `backend_requests` table first — if a recording already exists, it returns the recording ID immediately without calling the service. Otherwise it passes the stored blob data URL to the Netlify Recorder service and updates the row status to `"queued"`.

package/dist/index.d.ts

@@ -121,6 +121,8 @@ interface FinishRequestCallbacks {
         handlerPath: string;
         /** Pre-generated request ID. Use as the row ID when provided. */
         requestId?: string;
+        /** ID of the first request handled by this module instance (warm-start linkage). */
+        originalRequestId?: string;
     }) => Promise<string>;
 }
 
@@ -250,8 +252,13 @@ interface RecordingResult {
  *
  * Accepts either a blob URL (fetched at runtime) or pre-parsed BlobData (avoids needing
  * globalThis.fetch, which is missing in replay-node's Node v16 environment).
+ *
+ * When `precedingBlobs` is provided, the handler is executed once for each preceding
+ * blob (in order) before the target request. This replays prior requests on the same
+ * module instance to populate module-level state (e.g. in-memory caches) that would
+ * have existed on a warm Lambda container in production.
  */
-declare function createRequestRecording(blobUrlOrData: string | BlobData, handlerPath: string, requestInfo: RequestInfo): Promise<RecordingResult>;
+declare function createRequestRecording(blobUrlOrData: string | BlobData, handlerPath: string, requestInfo: RequestInfo, precedingBlobs?: BlobData[]): Promise<RecordingResult>;
 
 type SqlFunction$2 = (...args: any[]) => Promise<any[]>;
 interface BackendRequest {
@@ -261,6 +268,7 @@ interface BackendRequest {
     commit_sha: string;
     branch_name: string;
     repository_url: string | null;
+    original_request_id: string | null;
     status: string;
     recording_id: string | null;
     error_message: string | null;
@@ -282,6 +290,7 @@ declare function backendRequestsInsert(sql: SqlFunction$2, data: {
     commitSha: string;
     branchName: string;
     repositoryUrl?: string | null;
+    originalRequestId?: string | null;
 }): Promise<string>;
 declare function backendRequestsGet(sql: SqlFunction$2, id: string): Promise<BackendRequest | null>;
 declare function backendRequestsGetBlobUrl(sql: SqlFunction$2, id: string): Promise<string | null>;

package/dist/index.js

@@ -742,7 +742,8 @@ async function finishRequest(requestContext, callbacks, response, options) {
     branchName,
     repositoryUrl,
     handlerPath,
-    requestId: options?.requestId
+    requestId: options?.requestId,
+    originalRequestId: options?.originalRequestId
   });
   const storeDuration = Date.now() - storeStart;
   const totalDuration = Date.now() - finishStart;
@@ -859,7 +860,7 @@ function createRecordingRequestHandler(handler, options) {
 }
 
 // src/createRequestRecording.ts
-async function createRequestRecording(blobUrlOrData, handlerPath, requestInfo) {
+async function createRequestRecording(blobUrlOrData, handlerPath, requestInfo, precedingBlobs) {
   let blobData;
   if (typeof blobUrlOrData === "string") {
     const response = await fetch(blobUrlOrData);
@@ -1032,56 +1033,98 @@ async function createRequestRecording(blobUrlOrData, handlerPath, requestInfo) {
     g.Response = ResponseShim;
   }
   const result = { responseMismatch: false, unconsumedNetworkCalls: false };
-  try {
-    const handlerModule = await import(handlerPath);
-    let handler;
-    let isV2 = false;
-    let current = handlerModule;
-    for (let depth = 0; depth < 6 && current && typeof current === "object"; depth++) {
-      const obj = current;
-      if (typeof obj.handler === "function") {
-        handler = obj.handler;
-        isV2 = false;
-        break;
-      }
-      if (typeof obj.default === "function") {
-        handler = obj.default;
+  const handlerModule = await import(handlerPath);
+  let handler;
+  let isV2 = false;
+  let current = handlerModule;
+  for (let depth = 0; depth < 6 && current && typeof current === "object"; depth++) {
+    const obj = current;
+    if (typeof obj.handler === "function") {
+      handler = obj.handler;
+      isV2 = false;
+      break;
+    }
+    if (typeof obj.default === "function") {
+      handler = obj.default;
+      isV2 = true;
+      break;
+    }
+    if (obj.default && typeof obj.default === "object") {
+      current = obj.default;
+      continue;
+    }
+    break;
+  }
+  if (!handler && typeof handlerModule === "function") {
+    handler = handlerModule;
+    isV2 = true;
+  }
+  if (!handler && requestInfo.method) {
+    const httpMethodNames = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"];
+    let target = handlerModule;
+    for (let depth = 0; depth < 6 && target && typeof target === "object"; depth++) {
+      const obj = target;
+      const method = requestInfo.method.toUpperCase();
+      if (httpMethodNames.includes(method) && typeof obj[method] === "function") {
+        handler = obj[method];
         isV2 = true;
         break;
       }
       if (obj.default && typeof obj.default === "object") {
-        current = obj.default;
+        target = obj.default;
         continue;
       }
       break;
     }
-    if (!handler && typeof handlerModule === "function") {
-      handler = handlerModule;
-      isV2 = true;
-    }
-    if (!handler && requestInfo.method) {
-      const httpMethodNames = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"];
-      let target = handlerModule;
-      for (let depth = 0; depth < 6 && target && typeof target === "object"; depth++) {
-        const obj = target;
-        const method = requestInfo.method.toUpperCase();
-        if (httpMethodNames.includes(method) && typeof obj[method] === "function") {
-          handler = obj[method];
-          isV2 = true;
-          break;
-        }
-        if (obj.default && typeof obj.default === "object") {
-          target = obj.default;
-          continue;
+  }
+  if (!handler) {
+    throw new Error(
+      `Could not resolve handler from ${handlerPath}. Module exports: [${Object.keys(handlerModule).join(", ")}]`
+    );
+  }
+  if (precedingBlobs && precedingBlobs.length > 0) {
+    console.log(`  [warm-up] Replaying ${precedingBlobs.length} preceding request(s) to populate module-level state\u2026`);
+    for (let i = 0; i < precedingBlobs.length; i++) {
+      const pb = precedingBlobs[i];
+      console.log(`  [warm-up ${i + 1}/${precedingBlobs.length}] ${pb.requestInfo.method} ${pb.requestInfo.url}`);
+      const netH = installNetworkInterceptor("replay", pb.capturedData.networkCalls);
+      const envH = installEnvironmentInterceptor("replay", pb.capturedData.envReads);
+      try {
+        if (isV2) {
+          const url = pb.requestInfo.rawUrl ?? `https://localhost${pb.requestInfo.url}`;
+          const reqInit = { method: pb.requestInfo.method, headers: pb.requestInfo.headers };
+          if (pb.requestInfo.body && pb.requestInfo.method !== "GET" && pb.requestInfo.method !== "HEAD") {
+            reqInit.body = pb.requestInfo.body;
+          }
+          const RequestCtor = g.Request;
+          if (RequestCtor) {
+            const req = new RequestCtor(url, reqInit);
+            const ctx = { geo: {}, ip: "127.0.0.1", requestId: "replay-warmup", server: { region: "local" } };
+            g.__REPLAY_REQUEST_COOKIES__ = Object.keys(pb.requestInfo.headers).find((k) => k.toLowerCase() === "cookie") ? pb.requestInfo.headers[Object.keys(pb.requestInfo.headers).find((k) => k.toLowerCase() === "cookie")] : "";
+            g.__REPLAY_REQUEST_HEADERS__ = pb.requestInfo.headers;
+            await handler(req, ctx);
+          }
+        } else {
+          await handler({
+            httpMethod: pb.requestInfo.method,
+            path: pb.requestInfo.url,
+            headers: pb.requestInfo.headers,
+            body: pb.requestInfo.body ?? null,
+            queryStringParameters: pb.requestInfo.queryStringParameters ?? null,
+            multiValueQueryStringParameters: pb.requestInfo.multiValueQueryStringParameters ?? null,
+            rawUrl: pb.requestInfo.rawUrl ?? pb.requestInfo.url,
+            rawQuery: pb.requestInfo.rawQuery ?? "",
+            isBase64Encoded: pb.requestInfo.isBase64Encoded ?? false
+          });
         }
-        break;
+      } catch {
       }
+      netH.restore();
+      envH.restore();
     }
-    if (!handler) {
-      throw new Error(
-        `Could not resolve handler from ${handlerPath}. Module exports: [${Object.keys(handlerModule).join(", ")}]`
-      );
-    }
+    console.log(`  [warm-up] Done.`);
+  }
+  try {
     let rawResult;
     try {
       if (isV2) {
@@ -1225,30 +1268,38 @@ async function backendRequestsEnsureTable(sql) {
   await sql`
     CREATE INDEX IF NOT EXISTS idx_backend_requests_created_at ON backend_requests (created_at DESC)
   `;
+  await sql`
+    ALTER TABLE backend_requests ADD COLUMN IF NOT EXISTS original_request_id TEXT
+  `;
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_backend_requests_original_request_id ON backend_requests (original_request_id)
+  `;
 }
 async function backendRequestsInsert(sql, data) {
   if (data.id) {
     await sql`
-      INSERT INTO backend_requests (id, blob_data_url, handler_path, commit_sha, branch_name, repository_url)
+      INSERT INTO backend_requests (id, blob_data_url, handler_path, commit_sha, branch_name, repository_url, original_request_id)
       VALUES (
         ${data.id}::uuid,
         ${data.blobDataUrl},
         ${data.handlerPath},
         ${data.commitSha},
         ${data.branchName},
-        ${data.repositoryUrl ?? null}
+        ${data.repositoryUrl ?? null},
+        ${data.originalRequestId ?? null}
       )
     `;
     return data.id;
   }
   const rows = await sql`
-    INSERT INTO backend_requests (blob_data_url, handler_path, commit_sha, branch_name, repository_url)
+    INSERT INTO backend_requests (blob_data_url, handler_path, commit_sha, branch_name, repository_url, original_request_id)
     VALUES (
       ${data.blobDataUrl},
       ${data.handlerPath},
       ${data.commitSha},
       ${data.branchName},
-      ${data.repositoryUrl ?? null}
+      ${data.repositoryUrl ?? null},
+      ${data.originalRequestId ?? null}
     )
     RETURNING id
   `;
@@ -1339,7 +1390,8 @@ function databaseCallbacks(sql) {
         handlerPath: data.handlerPath,
         commitSha: data.commitSha,
         branchName: data.branchName,
-        repositoryUrl: data.repositoryUrl
+        repositoryUrl: data.repositoryUrl,
+        originalRequestId: data.originalRequestId
       });
     }
   };
@@ -1357,7 +1409,8 @@ function remoteCallbacks(recorderUrl) {
           branchName: data.branchName,
           repositoryUrl: data.repositoryUrl,
           handlerPath: data.handlerPath,
-          requestId: data.requestId
+          requestId: data.requestId,
+          originalRequestId: data.originalRequestId
         })
       });
       if (!res.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@replayio-app-building/netlify-recorder",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "description": "Capture and replay Netlify function executions as Replay recordings",
   "type": "module",
   "exports": {