fix: record http client requests as self-contained call/return pairs

An http client request used to emit its call event when the request was
sent and its return event when the response arrived.  When two requests
overlap, the second response can arrive before the first one's, so the
events interleaved and a return event no longer closed the most recently
opened call, breaking the nesting the AppMap format requires.

Emit both events up front instead.  Recording.httpClientRequest() now
writes the call event and an incomplete return event, and hands the
latter back to the caller.  Once the response arrives the hook passes
that event to Recording.httpClientResponse(), which fills in the status
code, headers, body and elapsed time through the existing fixup
mechanism.  The pair is therefore always adjacent, whatever order the
responses come in.

Until (and unless) the response arrives the return event simply carries
no http_client_response, so that field is now optional on
HttpClientResponseEvent.  A request that is aborted, errors out or
outlives the recording ends up as a call/return pair with no response
data, which is both accurate and still properly nested.

Assisted-by: Claude:claude-opus-5

Author: dividedmind

src/AppMap.ts

@@ -168,8 +168,8 @@ export interface HttpServerResponseEvent extends ReturnEventBase {
 }
 
 export interface HttpClientResponseEvent extends ReturnEventBase {
-  // status_code is missing if the response hasn't arrived (yet)
-  http_client_response: Omit<HttpResponse, "status_code"> & { status_code?: number };
+  // absent until the response arrives — and permanently, if it never does
+  http_client_response?: HttpResponse;
 }
 
 export interface SqlQueryEvent extends CallEventBase {

src/Recording.ts

@@ -99,12 +99,15 @@ export default class Recording {
     return event;
   }
 
+  // Both the call and the return event are emitted right away, so that the events
+  // nest properly even if requests overlap. The returned event carries no response
+  // data yet; pass it to httpClientResponse() once the response arrives.
   httpClientRequest(
     method: string,
     url: string,
     headers?: Record<string, string>,
-  ): AppMap.HttpClientRequestEvent {
-    const event: AppMap.HttpClientRequestEvent = {
+  ): AppMap.HttpClientResponseEvent {
+    const call: AppMap.HttpClientRequestEvent = {
       event: "call",
       http_client_request: compactObject({
         request_method: method,
@@ -114,28 +117,20 @@ export default class Recording {
       id: this.nextId++,
       thread_id: 0,
     };
-    this.emit(event);
-
-    return event;
-  }
+    this.emit(call);
 
-  // Emits the return event for an http client request immediately after the call,
-  // so that overlapping requests don't break event nesting. The response data
-  // is filled in later with httpClientResponseFixup once it arrives.
-  httpClientResponse(callId: number): AppMap.HttpClientResponseEvent {
-    const event: AppMap.HttpClientResponseEvent = {
+    const response: AppMap.HttpClientResponseEvent = {
       event: "return",
-      http_client_response: {},
       id: this.nextId++,
       thread_id: 0,
-      parent_id: callId,
+      parent_id: call.id,
     };
-    this.emit(event);
+    this.emit(response);
 
-    return event;
+    return response;
   }
 
-  httpClientResponseFixup(
+  httpClientResponse(
     returnEvent: AppMap.HttpClientResponseEvent,
     elapsed: number,
     status: number,

src/hooks/http.ts

@@ -112,12 +112,9 @@ function handleClientRequest(request: http.ClientRequest) {
 
     const urlString = `${url.protocol}//${url.host}${url.pathname}`;
     const headers = normalizeHeaders(request.getHeaders());
-    // Emit both the call and the return right away so that the events nest properly
-    // even if multiple requests overlap; the return is fixed up once the response arrives.
-    const clientResponseEvents = recordings.map((r) => {
-      const call = r.httpClientRequest(request.method, urlString, headers);
-      return r.httpClientResponse(call.id);
-    });
+    const clientResponseEvents = recordings.map((r) =>
+      r.httpClientRequest(request.method, urlString, headers),
+    );
 
     request.on("response", (response) => {
       const capture = new BodyCapture();
@@ -141,7 +138,7 @@ function handleClientRequest(request: http.ClientRequest) {
           assert(response.statusCode != undefined);
           if (!isActive(recording)) return;
 
-          recording.httpClientResponseFixup(
+          recording.httpClientResponse(
             clientResponseEvents[idx],
             elapsed,
             response.statusCode,

test/__snapshots__/httpClient.test.ts.snap

@@ -1075,7 +1075,6 @@ exports[`mapping overlapping http client requests 1`] = `
     },
     {
       "event": "return",
-      "http_client_response": {},
       "id": 6,
       "parent_id": 5,
       "thread_id": 0,
@@ -1094,7 +1093,6 @@ exports[`mapping overlapping http client requests 1`] = `
     },
     {
       "event": "return",
-      "http_client_response": {},
       "id": 8,
       "parent_id": 7,
       "thread_id": 0,

test/nextApp.ts

@@ -40,7 +40,7 @@ export default async function testNextApp() {
     (a) =>
       a.events?.forEach((e) => {
         if ("http_server_response" in e) delete e.http_server_response.return_value;
-        if ("http_client_response" in e) delete e.http_client_response.return_value;
+        if ("http_client_response" in e) delete e.http_client_response?.return_value;
       }),
   );