@replayio-app-building/netlify-recorder 0.5.0 → 0.7.0

package/README.md

@@ -59,12 +59,7 @@ import type { Handler } from "@netlify/functions";
 const RECORDER_URL = "https://netlify-recorder-bm4wmw.netlify.app";
 
 const handler: Handler = async (event) => {
-  const reqContext = startRequest({
-    method: event.httpMethod,
-    url: event.path,
-    headers: event.headers as Record<string, string>,
-    body: event.body ?? undefined,
-  });
+  const reqContext = startRequest(event);
 
   try {
     const result = await myBusinessLogic();
@@ -154,12 +149,7 @@ import { startRequest, finishRequest } from "@replayio-app-building/netlify-reco
 import type { Handler } from "@netlify/functions";
 
 const handler: Handler = async (event) => {
-  const reqContext = startRequest({
-    method: event.httpMethod,
-    url: event.path,
-    headers: event.headers as Record<string, string>,
-    body: event.body ?? undefined,
-  });
+  const reqContext = startRequest(event);
 
   try {
     const result = await myBusinessLogic();
@@ -300,15 +290,12 @@ Self-hosted recording requires these environment variables:
 
 ## API Reference
 
-### `startRequest(requestInfo): RequestContext`
+### `startRequest(event): RequestContext`
 
-Begins capturing a Netlify handler execution. Patches `globalThis.fetch` and `process.env` to record all outbound network calls and environment variable reads.
+Begins capturing a Netlify handler execution. Accepts the raw Netlify event object and extracts all request metadata internally (method, path, headers, body, query string parameters, etc.). Patches `globalThis.fetch` and `process.env` to record all outbound network calls and environment variable reads.
 
 **Parameters:**
-- `requestInfo.method` — HTTP method of the incoming request
-- `requestInfo.url` — Request URL/path
-- `requestInfo.headers` — Request headers
-- `requestInfo.body` — Optional request body
+- `event` — The Netlify handler event object (passed directly)
 
 **Returns:** A `RequestContext` object to pass to `finishRequest`.
 

package/dist/index.d.ts

@@ -1,8 +1,32 @@
+/**
+ * Normalized request metadata stored in the blob.
+ * Populated internally by startRequest from the Netlify event.
+ */
 interface RequestInfo {
     method: string;
     url: string;
     headers: Record<string, string>;
     body?: string;
+    queryStringParameters?: Record<string, string | undefined> | null;
+    multiValueQueryStringParameters?: Record<string, string[] | undefined> | null;
+    rawUrl?: string;
+    rawQuery?: string;
+    isBase64Encoded?: boolean;
+}
+/**
+ * Input type for startRequest. Mirrors the Netlify HandlerEvent shape so
+ * handlers can simply pass the event object directly.
+ */
+interface NetlifyEvent {
+    httpMethod: string;
+    path: string;
+    headers: Record<string, string | undefined>;
+    body?: string | null;
+    queryStringParameters?: Record<string, string | undefined> | null;
+    multiValueQueryStringParameters?: Record<string, string[] | undefined> | null;
+    rawUrl?: string;
+    rawQuery?: string;
+    isBase64Encoded?: boolean;
 }
 interface RequestContext {
     requestInfo: RequestInfo;
@@ -10,6 +34,9 @@ interface RequestContext {
     startTime: number;
     /** Restores original globals (fetch, process.env). Called automatically by finishRequest. */
     cleanup: () => void;
+    /** For v2 Request inputs, a promise that resolves to the request body text.
+     *  finishRequest awaits this before building the blob so POST bodies are captured. */
+    _v2BodyPromise?: Promise<string | undefined>;
 }
 interface CapturedData {
     networkCalls: NetworkCall[];
@@ -30,6 +57,10 @@ interface EnvRead {
     value: string | undefined;
     timestamp: number;
 }
+interface HandlerResponse {
+    statusCode: number;
+    body?: string;
+}
 interface BlobData {
     requestInfo: RequestInfo;
     capturedData: CapturedData;
@@ -37,6 +68,8 @@ interface BlobData {
     commitSha: string;
     startTime: number;
     endTime: number;
+    /** The response returned to the client, used to detect replay mismatches. */
+    handlerResponse?: HandlerResponse;
 }
 interface FinishRequestCallbacks {
     /** Uploads serialized captured data and returns the blob URL. */
@@ -92,18 +125,20 @@ interface EnsureRecordingOptions {
 
 /**
  * Called at the beginning of a Netlify handler execution.
- * Installs interceptors on globalThis.fetch and process.env to capture
- * outbound network calls and environment variable reads made by the handler.
- * Returns a request context used by finishRequest.
+ * Accepts either a Netlify Functions v1 event (HandlerEvent with httpMethod,
+ * path, etc.) or a v2 Web API Request.  Extracts all request metadata
+ * internally, installs interceptors on globalThis.fetch and process.env to
+ * capture outbound network calls and environment variable reads, and returns
+ * a request context used by finishRequest.
  *
  * When running inside createRequestRecording (replay mode), the replay
  * interceptors are already installed.  In that case we skip installing
  * capture interceptors to avoid overwriting the replay layer (which would
  * also crash on Node v16 where Headers/Response don't exist).
  */
-declare function startRequest(requestInfo: RequestInfo): RequestContext;
+declare function startRequest(event: NetlifyEvent | /* v2 Request */ Record<string, unknown>): RequestContext;
 
-interface HandlerResponse {
+interface FullHandlerResponse {
     statusCode: number;
     headers?: Record<string, string>;
     body?: string;
@@ -123,7 +158,7 @@ interface FinishRequestOptions {
  * uploads it as a JSON blob via the provided callback,
  * stores the request metadata, and sets the X-Replay-Request-Id header.
  */
-declare function finishRequest(requestContext: RequestContext, callbacks: FinishRequestCallbacks, response: HandlerResponse, options?: FinishRequestOptions): Promise<HandlerResponse>;
+declare function finishRequest(requestContext: RequestContext, callbacks: FinishRequestCallbacks, response: FullHandlerResponse, options?: FinishRequestOptions): Promise<FullHandlerResponse>;
 
 /**
  * Creates `FinishRequestCallbacks` that send captured data to a remote
@@ -181,6 +216,20 @@ declare function ensureRequestRecording(requestId: string, options: EnsureRecord
  */
 declare function readInfraConfigFromEnv(): ContainerInfraConfig | undefined;
 
+interface RecordingResult {
+    /** Whether a response mismatch was detected between capture and replay. */
+    responseMismatch: boolean;
+    /** Details about the mismatch, if any. */
+    mismatchDetails?: string;
+    /** The response produced during replay. */
+    replayResponse?: HandlerResponse;
+    /** The original response captured in the blob. */
+    capturedResponse?: HandlerResponse;
+    /** Whether some recorded network calls were not consumed during replay. */
+    unconsumedNetworkCalls: boolean;
+    /** Details about unconsumed network calls, if any. */
+    unconsumedNetworkDetails?: string;
+}
 /**
  * Called from within a container (running under replay-node) to create a Replay recording.
  * Installs replay-mode interceptors that return pre-recorded responses, then executes
@@ -189,7 +238,7 @@ declare function readInfraConfigFromEnv(): ContainerInfraConfig | undefined;
  * 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).
  */
-declare function createRequestRecording(blobUrlOrData: string | BlobData, handlerPath: string, requestInfo: RequestInfo): Promise<void>;
+declare function createRequestRecording(blobUrlOrData: string | BlobData, handlerPath: string, requestInfo: RequestInfo): Promise<RecordingResult>;
 
 /**
  * Options for spawning a recording container from a blob URL.
@@ -227,4 +276,4 @@ interface SpawnRecordingContainerOptions {
  */
 declare function spawnRecordingContainer(options: SpawnRecordingContainerOptions): Promise<string>;
 
-export { type BlobData, type CapturedData, type ContainerInfraConfig, type EnsureRecordingOptions, type EnvRead, type FinishRequestCallbacks, type FinishRequestOptions, type NetworkCall, type RequestContext, type RequestInfo, type SpawnRecordingContainerOptions, createRequestRecording, ensureRequestRecording, finishRequest, readInfraConfigFromEnv, redactBlobData, remoteCallbacks, spawnRecordingContainer, startRequest };
+export { type BlobData, type CapturedData, type ContainerInfraConfig, type EnsureRecordingOptions, type EnvRead, type FinishRequestCallbacks, type FinishRequestOptions, type HandlerResponse, type NetlifyEvent, type NetworkCall, type RecordingResult, type RequestContext, type RequestInfo, type SpawnRecordingContainerOptions, createRequestRecording, ensureRequestRecording, finishRequest, readInfraConfigFromEnv, redactBlobData, remoteCallbacks, spawnRecordingContainer, startRequest };

package/dist/index.js

@@ -8,6 +8,7 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 // src/interceptors/network.ts
 function installNetworkInterceptor(mode, calls) {
   const originalFetch = globalThis.fetch;
+  let replayCallIndex = 0;
   if (mode === "capture") {
     const captureFetch = async (input, init) => {
       const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
@@ -39,14 +40,17 @@ function installNetworkInterceptor(mode, calls) {
     };
     globalThis.fetch = captureFetch;
   } else {
-    let callIndex = 0;
     const replayFetch = async () => {
-      const call = calls[callIndex++];
+      const idx = replayCallIndex++;
+      const call = calls[idx];
       if (!call) {
         throw new Error(
           `No more recorded network calls to replay (exhausted ${calls.length} calls)`
         );
       }
+      console.log(
+        `  [network-replay] Consumed call ${idx + 1}/${calls.length}: ${call.method} ${call.url} => ${call.responseStatus}`
+      );
       const body = call.responseBody ?? "";
       const status = call.responseStatus;
       return {
@@ -82,6 +86,12 @@ function installNetworkInterceptor(mode, calls) {
   return {
     restore() {
       globalThis.fetch = originalFetch;
+    },
+    consumedCount() {
+      return replayCallIndex;
+    },
+    totalCount() {
+      return calls.length;
     }
   };
 }
@@ -121,7 +131,92 @@ function installEnvironmentInterceptor(mode, reads) {
 }
 
 // src/startRequest.ts
-function startRequest(requestInfo) {
+function isWebApiRequest(event) {
+  if (!event || typeof event !== "object") return false;
+  const obj = event;
+  return typeof obj.httpMethod === "undefined" && typeof obj.method === "string" && typeof obj.url === "string";
+}
+function extractFromWebRequest(req) {
+  const r = req;
+  const headers = {};
+  if (r.headers && typeof r.headers.forEach === "function") {
+    r.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+  }
+  let pathname = "/";
+  let rawQuery = "";
+  let queryStringParameters = null;
+  try {
+    const parsed = new URL(r.url);
+    pathname = parsed.pathname;
+    rawQuery = parsed.search ? parsed.search.slice(1) : "";
+    if (parsed.searchParams) {
+      const params = {};
+      parsed.searchParams.forEach((v, k) => {
+        params[k] = v;
+      });
+      if (Object.keys(params).length > 0) queryStringParameters = params;
+    }
+  } catch {
+    pathname = r.url;
+  }
+  const requestInfo = {
+    method: r.method,
+    url: pathname,
+    headers,
+    body: void 0,
+    // filled asynchronously below
+    queryStringParameters,
+    multiValueQueryStringParameters: null,
+    rawUrl: r.url,
+    rawQuery,
+    isBase64Encoded: false
+  };
+  let bodyPromise = Promise.resolve(void 0);
+  if (r.body !== null && r.body !== void 0 && typeof r.clone === "function") {
+    try {
+      const clone = r.clone();
+      if (typeof clone.text === "function") {
+        bodyPromise = clone.text().then(
+          (text) => text || void 0,
+          () => void 0
+        );
+      }
+    } catch {
+    }
+  }
+  return { requestInfo, bodyPromise };
+}
+function extractFromV1Event(event) {
+  const headers = {};
+  for (const [key, value] of Object.entries(event.headers)) {
+    if (value !== void 0) {
+      headers[key] = value;
+    }
+  }
+  return {
+    method: event.httpMethod,
+    url: event.path,
+    headers,
+    body: event.body ?? void 0,
+    queryStringParameters: event.queryStringParameters ?? null,
+    multiValueQueryStringParameters: event.multiValueQueryStringParameters ?? null,
+    rawUrl: event.rawUrl,
+    rawQuery: event.rawQuery,
+    isBase64Encoded: event.isBase64Encoded
+  };
+}
+function startRequest(event) {
+  let requestInfo;
+  let bodyPromise;
+  if (isWebApiRequest(event)) {
+    const extracted = extractFromWebRequest(event);
+    requestInfo = extracted.requestInfo;
+    bodyPromise = extracted.bodyPromise;
+  } else {
+    requestInfo = extractFromV1Event(event);
+  }
   const capturedData = { networkCalls: [], envReads: [] };
   const isReplay = globalThis.__REPLAY_RECORDING_MODE__ === true;
   let cleanup;
@@ -140,7 +235,8 @@ function startRequest(requestInfo) {
     requestInfo,
     capturedData,
     startTime: Date.now(),
-    cleanup
+    cleanup,
+    _v2BodyPromise: bodyPromise
   };
 }
 
@@ -291,12 +387,25 @@ async function finishRequest(requestContext, callbacks, response, options) {
   const commitSha = rawCommitSha;
   const branchName = rawBranchName;
   const repositoryUrl = rawRepositoryUrl;
+  if (requestContext._v2BodyPromise && !requestContext.requestInfo.body) {
+    try {
+      const bodyText = await requestContext._v2BodyPromise;
+      if (bodyText) {
+        requestContext.requestInfo.body = bodyText;
+      }
+    } catch {
+    }
+  }
   const rawBlobData = {
     requestInfo: requestContext.requestInfo,
     capturedData: requestContext.capturedData,
     commitSha,
     startTime: requestContext.startTime,
-    endTime: Date.now()
+    endTime: Date.now(),
+    handlerResponse: {
+      statusCode: response.statusCode,
+      body: response.body
+    }
   };
   const blobData = redactBlobData(rawBlobData);
   const blobContent = JSON.stringify(blobData);
@@ -648,19 +757,241 @@ async function createRequestRecording(blobUrlOrData, handlerPath, requestInfo) {
     };
     g.File = FileShim;
   }
+  if (typeof g.Headers === "undefined") {
+    const HeadersShim = class Headers {
+      _map;
+      constructor(init) {
+        this._map = /* @__PURE__ */ new Map();
+        if (init) {
+          const entries = Array.isArray(init) ? init : Object.entries(init);
+          for (const [k, v] of entries) this._map.set(k.toLowerCase(), String(v));
+        }
+      }
+      get(name) {
+        return this._map.get(name.toLowerCase()) ?? null;
+      }
+      has(name) {
+        return this._map.has(name.toLowerCase());
+      }
+      set(name, value) {
+        this._map.set(name.toLowerCase(), String(value));
+      }
+      delete(name) {
+        this._map.delete(name.toLowerCase());
+      }
+      forEach(cb) {
+        this._map.forEach((v, k) => cb(v, k, this));
+      }
+      entries() {
+        return this._map.entries();
+      }
+      keys() {
+        return this._map.keys();
+      }
+      values() {
+        return this._map.values();
+      }
+      [Symbol.iterator]() {
+        return this._map.entries();
+      }
+    };
+    g.Headers = HeadersShim;
+  }
+  if (typeof g.Request === "undefined") {
+    const H = g.Headers;
+    const RequestShim = class Request {
+      method;
+      url;
+      headers;
+      _body;
+      constructor(input, init) {
+        this.url = input;
+        this.method = String(init?.method ?? "GET");
+        this.headers = new H(init?.headers);
+        this._body = init?.body ?? null;
+      }
+      async text() {
+        return this._body ?? "";
+      }
+      async json() {
+        return JSON.parse(this._body ?? "null");
+      }
+      clone() {
+        return new RequestShim(this.url, {
+          method: this.method,
+          headers: Object.fromEntries(this.headers.entries()),
+          body: this._body ?? void 0
+        });
+      }
+    };
+    g.Request = RequestShim;
+  }
+  if (typeof g.Response === "undefined") {
+    const H = g.Headers;
+    const ResponseShim = class Response {
+      status;
+      statusText;
+      headers;
+      ok;
+      _body;
+      constructor(body, init) {
+        this._body = body ?? null;
+        this.status = init?.status ?? 200;
+        this.statusText = init?.statusText ?? "";
+        this.headers = new H(init?.headers);
+        this.ok = this.status >= 200 && this.status < 300;
+      }
+      async text() {
+        return this._body ?? "";
+      }
+      async json() {
+        return JSON.parse(this._body ?? "null");
+      }
+      clone() {
+        return new ResponseShim(this._body, {
+          status: this.status,
+          statusText: this.statusText,
+          headers: Object.fromEntries(this.headers.entries())
+        });
+      }
+    };
+    g.Response = ResponseShim;
+  }
+  const result = { responseMismatch: false, unconsumedNetworkCalls: false };
   try {
     const handlerModule = await import(handlerPath);
-    await handlerModule.handler({
-      httpMethod: requestInfo.method,
-      path: requestInfo.url,
-      headers: requestInfo.headers,
-      body: requestInfo.body ?? null
-    });
+    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) {
+      throw new Error(
+        `Could not resolve handler from ${handlerPath}. Module exports: [${Object.keys(handlerModule).join(", ")}]`
+      );
+    }
+    let rawResult;
+    if (isV2) {
+      const url = requestInfo.rawUrl ?? `https://localhost${requestInfo.url}`;
+      const reqInit = {
+        method: requestInfo.method,
+        headers: requestInfo.headers
+      };
+      if (requestInfo.body && requestInfo.method !== "GET" && requestInfo.method !== "HEAD") {
+        reqInit.body = requestInfo.body;
+      }
+      const RequestCtor = globalThis.Request;
+      if (!RequestCtor) {
+        throw new Error(
+          "Handler uses Netlify Functions v2 signature but Request is not available in this environment. Ensure undici or a Request polyfill is installed."
+        );
+      }
+      const req = new RequestCtor(url, reqInit);
+      const context = { geo: {}, ip: "127.0.0.1", requestId: "replay", server: { region: "local" } };
+      const response = await handler(req, context);
+      if (response && typeof response === "object" && typeof response.status === "number" && typeof response.text === "function") {
+        const res = response;
+        rawResult = {
+          statusCode: res.status,
+          body: await res.text()
+        };
+      } else {
+        rawResult = response;
+      }
+    } else {
+      rawResult = await handler({
+        httpMethod: requestInfo.method,
+        path: requestInfo.url,
+        headers: requestInfo.headers,
+        body: requestInfo.body ?? null,
+        queryStringParameters: requestInfo.queryStringParameters ?? null,
+        multiValueQueryStringParameters: requestInfo.multiValueQueryStringParameters ?? null,
+        rawUrl: requestInfo.rawUrl ?? requestInfo.url,
+        rawQuery: requestInfo.rawQuery ?? "",
+        isBase64Encoded: requestInfo.isBase64Encoded ?? false
+      });
+    }
+    if (blobData.handlerResponse) {
+      const replayRes = rawResult;
+      const replayResponse = {
+        statusCode: replayRes?.statusCode ?? 0,
+        body: replayRes?.body
+      };
+      result.replayResponse = replayResponse;
+      result.capturedResponse = blobData.handlerResponse;
+      const statusMismatch = replayResponse.statusCode !== blobData.handlerResponse.statusCode;
+      const bodyMismatch = replayResponse.body !== blobData.handlerResponse.body;
+      if (statusMismatch || bodyMismatch) {
+        result.responseMismatch = true;
+        const details = [];
+        if (statusMismatch) {
+          details.push(
+            `Status code: captured=${blobData.handlerResponse.statusCode}, replay=${replayResponse.statusCode}`
+          );
+        }
+        if (bodyMismatch) {
+          const capturedPreview = (blobData.handlerResponse.body ?? "").slice(0, 200);
+          const replayPreview = (replayResponse.body ?? "").slice(0, 200);
+          details.push(
+            `Body differs: captured=${JSON.stringify(capturedPreview)}, replay=${JSON.stringify(replayPreview)}`
+          );
+        }
+        result.mismatchDetails = details.join("; ");
+        console.error(`RESPONSE_MISMATCH: The replay response differs from the captured response.`);
+        console.error(`  ${result.mismatchDetails}`);
+      } else {
+        console.log(`  [response-check] Replay response matches captured response.`);
+      }
+    }
   } finally {
+    const consumed = networkHandle.consumedCount();
+    const total = networkHandle.totalCount();
+    if (consumed < total) {
+      result.unconsumedNetworkCalls = true;
+      const details = [
+        `Consumed ${consumed} of ${total} calls. ${total - consumed} call(s) were never replayed.`
+      ];
+      console.error(
+        `ERROR: Not all recorded network calls were consumed during replay. Consumed ${consumed} of ${total} calls. ${total - consumed} call(s) were never replayed.`
+      );
+      for (let i = consumed; i < total; i++) {
+        const call = blobData.capturedData.networkCalls[i];
+        if (call) {
+          details.push(`Unconsumed: ${call.method} ${call.url} => ${call.responseStatus}`);
+          console.error(
+            `  Unconsumed call ${i + 1}/${total}: ${call.method} ${call.url} => ${call.responseStatus}`
+          );
+        }
+      }
+      result.unconsumedNetworkDetails = details.join("; ");
+    } else {
+      console.log(`  [network-replay] All ${total} recorded network call(s) were consumed.`);
+    }
     globalThis.__REPLAY_RECORDING_MODE__ = false;
     networkHandle.restore();
     envHandle.restore();
   }
+  return result;
 }
 export {
   createRequestRecording,

package/package.json

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