@descryy/runtime-browser 0.2.0

package/dist/browser-network-collector.js

@@ -0,0 +1,682 @@
+/**
+ * §8's network evidence bucket: method · URL · safe request metadata/body
+ * · response status · safe response metadata/body · timing · initiator
+ * where available. `NETWORK_REQUEST` on `request`; `NETWORK_RESPONSE` (and
+ * `HTTP_ERROR` alongside it for status >= 400) on `requestfinished`, which
+ * is when `request.timing()` is actually complete; a network-level
+ * failure with no HTTP response at all (`requestfailed` -- DNS, connection
+ * refused, aborted) also becomes `HTTP_ERROR`, with `status: null`
+ * distinguishing "never got a response" from "got a bad one."
+ *
+ * Auth headers/cookies/tokens are not stripped here -- `headers()` already
+ * lower-cases header names, and `EvidenceStore.write()`'s generic
+ * redaction (RT-015) deep-redacts `authorization`/`cookie`/`set-cookie`/
+ * etc. by key name unconditionally at persist time, so a header object
+ * passed straight into payload is already covered by an existing,
+ * already-tested guarantee -- reimplementing it here would be a second,
+ * divergent copy of the same rule.
+ *
+ * A third `status: null` case (RT-194): a request that gets neither
+ * `requestfinished` nor `requestfailed` within this collector's own
+ * timeout window (`networkTimeoutMs`, default `context.configuration.
+ * timeoutMs` -- RT-030's precedent, not a second disagreeing default) is
+ * reported as `HTTP_ERROR` with `networkError` describing a collector-side
+ * timeout, distinguishable from a real Playwright `requestfailed` (whose
+ * `networkError` carries Chromium's own `net::ERR_*` text). Nothing in
+ * Playwright itself imposes a timeout on an in-page `fetch`/`XHR` that
+ * never completes -- a hung server would otherwise produce silence
+ * forever, not evidence.
+ *
+ * **"initiator where available" above is no longer only `resourceType`.**
+ * With a `stackTraceParser` injected, `NETWORK_REQUEST.stackTrace` carries
+ * a real, resolved call-site stack for `fetch()` requests (Chromium only —
+ * see `frontend-initiator-capture.ts` for the mechanism and the write it
+ * makes to the observed page). This is still not the same claim as
+ * `@descryy/runtime-graph-correlator`'s `resolveObservedFrontendCaller`
+ * upgrading a structural candidate to `observed`: that join happens one
+ * layer up, against the graph. This collector's job stops at attaching the
+ * resolved stack to the evidence record.
+ *
+ * **RT-225: WebSocket traffic is a fourth listener here, not a sibling
+ * collector.** `page.on("request"/"requestfinished"/"requestfailed")` never
+ * fires for a WebSocket connection -- Playwright surfaces it through a
+ * wholly separate `page.on("websocket")` stream, and before this a refused
+ * or dropped WebSocket connection produced zero evidence of any kind, not
+ * degraded, silently absent
+ * (`documents/decisions-inbox/RT-PENDING-websocket-network-observation-gap.md`).
+ * This collector draws its boundary by domain watched (browser network
+ * traffic), not by wire protocol, so WS traffic belongs here.
+ *
+ * Three moments, three choices:
+ * - **connection attempt** (`page.on("websocket")` firing -- "Emitted when
+ *   WebSocket request is sent," Playwright's own doc for the event) reuses
+ *   `NETWORK_REQUEST`: a real outbound call to a URL, the same fact that
+ *   type exists to record. No `method`/`headers`/`postData` fields are
+ *   invented -- Playwright's `WebSocket` object exposes only `url()`, so
+ *   the payload states only what was actually observed, plus a `protocol:
+ *   "websocket"` discriminator.
+ * - **connection failure** (`socketerror`) reuses `HTTP_ERROR` with
+ *   `status: null` -- the identical "no usable response ever came back"
+ *   convention already applied above to a refused `fetch()`
+ *   (`requestfailed`) and to this collector's own timeout. A refused
+ *   WebSocket is the same class of fact under a different wire protocol,
+ *   not a different fact.
+ * - **close** gets its own type, `WEBSOCKET_CLOSED` (`runtime-event.ts`),
+ *   because there is no honest way to fold it into `NETWORK_RESPONSE`:
+ *   that type means a response with a status arrived, and a close is
+ *   neither a response nor does it carry a status. Measured, not assumed:
+ *   Playwright's public `WebSocket.on("close")` carries no code or reason
+ *   at all, and probing it directly (a clean server-sent 1000 close vs. a
+ *   raw abrupt TCP termination) produced byte-identical event shapes --
+ *   so this collector does not claim "normal" vs "abnormal" either, only
+ *   that the socket closed. Only emitted when no `socketerror` already
+ *   reported the same socket as failed, so one failure is never reported
+ *   twice.
+ *
+ * Deliberately **not** captured: per-message frame traffic
+ * (`framesent`/`framereceived`) -- high-volume and not what the proven gap
+ * asked for; `EventSource`/SSE, which shares the same uncovered shape but
+ * is unmeasured and explicitly out of scope for this change, same as the
+ * RT-PENDING note that proved this gap already said.
+ */
+import { primaryFrameLocation } from "@descryy/runtime-contracts";
+import { extractHeaderCorrelationIds } from "./network-correlation.js";
+import { rewriteScriptUrls } from "./script-url-mapping.js";
+import { createFrontendInitiatorCapture, stripInitiatorWrapperFrame, INITIATOR_HEADER_NAME } from "./frontend-initiator-capture.js";
+import { COLLECTOR_VERSION } from "./collector-version.js";
+const DEFAULT_NETWORK_TIMEOUT_MS = 30000;
+function notThisCollectorsJob(what) {
+    return { availability: "unavailable", reason: `BrowserNetworkCollector handles network observation only, not ${what} -- see the dedicated collector.` };
+}
+const CAPABILITIES = {
+    domObservation: notThisCollectorsJob("DOM inspection"),
+    consoleObservation: notThisCollectorsJob("console/page-error observation"),
+    networkObservation: {
+        availability: "degraded",
+        reason: "response bodies are captured for JSON/text content types only; binary, streamed, or already-consumed bodies are not available. " +
+            "WebSocket connections (RT-225) are observed for connection attempt, connection failure and close, but not per-message frame " +
+            "traffic (framesent/framereceived, not captured), and a close cannot be told apart as normal vs. abnormal -- Playwright's public " +
+            "WebSocket API exposes no close code or reason, measured directly rather than assumed. EventSource/SSE traffic is ordinary browser " +
+            "network traffic under the hood and is already observed via the request/requestfailed path above -- verified directly, not assumed " +
+            "(see this collector's test suite).",
+    },
+    backendLogAccess: { availability: "unavailable", reason: "this collector observes browser-originated network activity, not a backend process." },
+    distributedTrace: { availability: "available", reason: null },
+    sourceMapping: { availability: "unavailable", reason: "no stackTraceParser was injected -- network evidence carries no stack traces." },
+    stackCapture: { availability: "unavailable", reason: "no stackTraceParser was injected -- network evidence carries no stack traces." },
+    processLifecycle: notThisCollectorsJob("process lifecycle observation"),
+    databaseObservation: notThisCollectorsJob("database query observation"),
+    // Not a claim on the requests this collector already captures under
+    // networkObservation, some of which do reach external hosts -- this
+    // field is specifically the process-instrumentation mechanism
+    // `ExternalRequestCollector` (RT-146) uses, a different capture path
+    // this collector does not have. See capability.ts's own doc comment.
+    externalServiceObservation: {
+        availability: "unavailable",
+        reason: "this collector captures browser-originated requests broadly (NETWORK_REQUEST/RESPONSE, §6); it does not instrument a process's own outbound client the way this field's producer does.",
+    },
+};
+/**
+ * With a parser wired: fetch-initiator capture is installed, so
+ * `NETWORK_REQUEST.stackTrace` and `.sourceLocation` are populated whenever
+ * a real call-site stack was captured and resolved. `degraded`, not
+ * `available`, for the identical reason `BrowserConsoleCollector` uses it
+ * for `sourceMapping`: a successful rewrite proves the script's origin maps
+ * to a configured directory, not that the served file came from that exact
+ * checkout. `stackCapture` is `degraded` too, one level up from that: it
+ * covers Chromium + `fetch()` only — no Firefox/WebKit, no `XMLHttpRequest`
+ * — and a header an intermediate proxy strips, or a call site the parser
+ * cannot symbolicate (a minified build), both degrade a given request back
+ * to `stackTrace: null` silently at the per-request level, which is exactly
+ * what "degraded" rather than "available" discloses at the capability
+ * level.
+ */
+const CAPABILITIES_WITH_STACKS = {
+    ...CAPABILITIES,
+    sourceMapping: {
+        availability: "degraded",
+        reason: "fetch() call-site stacks are parsed and script URLs are rewritten to on-disk paths via the execution's configured service roots, the same way BrowserConsoleCollector's page-error stacks are; " +
+            "a successful rewrite proves the origin maps to a configured directory, not that the served file came from that checkout.",
+    },
+    stackCapture: {
+        availability: "degraded",
+        reason: "captures the real call-site stack for fetch() requests only (Chromium + fetch(), via an injected header carrying a per-call id -- not XMLHttpRequest, not Firefox/WebKit); " +
+            "a header stripped by an intermediate proxy, or a call site the parser cannot symbolicate, degrades that one request's stackTrace to null rather than the whole capability.",
+    },
+};
+const BODY_CAPTURABLE_CONTENT_TYPE = /^(application\/json|text\/)/i;
+async function captureResponseBody(response, headers) {
+    const contentType = headers["content-type"] ?? "";
+    if (!BODY_CAPTURABLE_CONTENT_TYPE.test(contentType))
+        return null;
+    return response.text().catch(() => null);
+}
+export function createBrowserNetworkCollector(options) {
+    const { session } = options;
+    const { page } = session;
+    let emit;
+    let networkTimeoutMs = options.networkTimeoutMs ?? DEFAULT_NETWORK_TIMEOUT_MS;
+    let resolveSourceRoot;
+    /** Only true once both halves are present: a parser to read the stack, and a way to map its URLs -- same rule `BrowserConsoleCollector` uses. */
+    let stacksParsed = false;
+    let initiatorCapture;
+    const source = "browser-network";
+    // Tracks requests still awaiting `requestfinished`/`requestfailed`, keyed
+    // by the Playwright `Request` object itself -- not a URL or an id, which
+    // could collide across concurrent requests to the same endpoint. Cleared
+    // the moment either real event fires, or when this collector's own timer
+    // fires first and reports the exchange as timed out.
+    const pending = new Map();
+    /**
+     * In-flight `onRequest` handlers -- the identical reason
+     * `BrowserConsoleCollector.onPageError` keeps one (RT-023 regression):
+     * resolving a call-site stack is asynchronous, and Playwright's `request`
+     * listener is not, so `stop()` must drain this before clearing `emit`, or
+     * a NETWORK_REQUEST whose stack was still resolving at execution end is
+     * silently dropped rather than reported.
+     */
+    const inFlight = new Set();
+    const activeSockets = new Map();
+    function clearPending(request) {
+        const timer = pending.get(request);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            pending.delete(request);
+        }
+    }
+    /**
+     * `null` whenever this request's real call-site stack cannot be
+     * recovered, for any reason -- no parser wired, no id header (an
+     * intermediate proxy stripped it, or the request predates the init
+     * script installing on this document), or nothing was ever buffered for
+     * the id (evicted, or issued by a different capture instance). Every one
+     * of those degrades to exactly the same `null`, which is what lets the
+     * graph-correlator's structural-only fallback stay the single, unified
+     * "no observation" path rather than needing to distinguish the reason.
+     */
+    async function resolveInitiatorStack(headers) {
+        if (!stacksParsed || initiatorCapture === undefined)
+            return null;
+        const id = headers[INITIATOR_HEADER_NAME];
+        if (id === undefined)
+            return null;
+        const rawStack = initiatorCapture.take(id);
+        if (rawStack === undefined)
+            return null;
+        const mapping = rewriteScriptUrls(stripInitiatorWrapperFrame(rawStack), resolveSourceRoot);
+        try {
+            return await options.stackTraceParser.parse(mapping.text);
+        }
+        catch (error) {
+            // **A frame that cannot be resolved must not take the request with it.**
+            // Resolution reads files off disk — a stale source map, a permission
+            // error, a path that turned out to be a directory (`EISDIR`; see
+            // `script-url-mapping.ts`'s own `isFile` note) — and every one of those
+            // is a failure to *annotate* an observation, not a failure to make it.
+            // Before this, the throw propagated out of `emitNetworkRequest` into a
+            // bare `console.error` and the entire `NETWORK_REQUEST` row was dropped:
+            // a real request the page really issued, gone, with nothing in the
+            // evidence stream to say so. That is rule 7's "never silently do less",
+            // and the emphasis is on *silently*.
+            //
+            // So: degrade to `null` — the same value every other unresolvable
+            // initiator already degrades to, which is what keeps the
+            // graph-correlator's structural-only fallback a single path — and
+            // disclose the degradation as a first-class `COLLECTOR_ERROR` row.
+            emitCollectorError(`initiator stack resolution failed; this request's NETWORK_REQUEST carries no call-site stack: ${describe(error)}`, error);
+            return null;
+        }
+    }
+    /** A first-hand observation of this collector's own failure. Never throws — see the nested catch. */
+    function emitCollectorError(message, error) {
+        try {
+            emit?.({
+                timestamp: new Date().toISOString(),
+                source,
+                service: options.service ?? null,
+                process: null,
+                eventType: "COLLECTOR_ERROR",
+                payload: {
+                    raw: `browser network collector for session "${session.sessionId}": ${message}`,
+                    collectorId: `browser-network:${session.sessionId}`,
+                    error: describe(error),
+                    browserSessionId: session.sessionId,
+                },
+                traceId: null,
+                requestId: null,
+                correlationId: null,
+                graphNodeId: null,
+                sourceLocation: null,
+                stackTrace: null,
+                // About the observer, not the observed — as certain as any captured line.
+                confidence: 1,
+                redactionStatus: "pending-redaction",
+                collectorVersion: COLLECTOR_VERSION,
+            });
+        }
+        catch (emitError) {
+            // The evidence channel itself is gone, so the console is genuinely the
+            // last resort here rather than the first one it used to be.
+            console.error(`[browser-network:${session.sessionId}] could not disclose a collector error: ${String(emitError)}`);
+        }
+    }
+    function describe(error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    async function emitNetworkRequest(request, headers, traceId, requestId) {
+        const stackTrace = await resolveInitiatorStack(headers);
+        emit?.({
+            timestamp: new Date().toISOString(),
+            source,
+            service: options.service ?? null,
+            process: null,
+            eventType: "NETWORK_REQUEST",
+            payload: {
+                method: request.method(),
+                url: request.url(),
+                headers,
+                postData: request.postData(),
+                resourceType: request.resourceType(),
+                browserSessionId: session.sessionId,
+            },
+            traceId,
+            requestId,
+            correlationId: null,
+            graphNodeId: null,
+            // Same rule `Evidence.primaryFrameLocation`'s own doc states: the
+            // innermost frame after the wrapper's own frame is stripped, never a
+            // second, divergent copy of "which frame is the site of interest."
+            sourceLocation: primaryFrameLocation(stackTrace),
+            stackTrace,
+            confidence: 1,
+            redactionStatus: "pending-redaction",
+            collectorVersion: COLLECTOR_VERSION,
+        });
+    }
+    function onRequest(request) {
+        const headers = request.headers();
+        const { traceId, requestId } = extractHeaderCorrelationIds(headers);
+        // The timeout window starts here, synchronously -- not after
+        // emitNetworkRequest's stack resolution completes, which would let
+        // parse latency silently skew what this collector's own timer is
+        // supposed to measure.
+        const timer = setTimeout(() => {
+            pending.delete(request);
+            emit?.({
+                timestamp: new Date().toISOString(),
+                source,
+                service: options.service ?? null,
+                process: null,
+                eventType: "HTTP_ERROR",
+                payload: {
+                    // No response, and no Playwright-observed failure either -- this
+                    // collector gave up waiting. status: null puts it in the same
+                    // "never got a response" bucket onRequestFailed uses; networkError
+                    // names the collector as the reporter rather than Chromium, which
+                    // is what a test (or a reader) uses to tell it apart from a real
+                    // net::ERR_* failure.
+                    status: null,
+                    method: request.method(),
+                    url: request.url(),
+                    networkError: `collector timeout: no response within ${networkTimeoutMs}ms`,
+                    browserSessionId: session.sessionId,
+                },
+                traceId,
+                requestId,
+                correlationId: null,
+                graphNodeId: null,
+                sourceLocation: null,
+                stackTrace: null,
+                confidence: 1,
+                redactionStatus: "pending-redaction",
+                collectorVersion: COLLECTOR_VERSION,
+            });
+        }, networkTimeoutMs);
+        pending.set(request, timer);
+        const handled = emitNetworkRequest(request, headers, traceId, requestId).catch((error) => {
+            // Defence in depth. `resolveInitiatorStack` now absorbs the one failure
+            // that actually reached here in practice, so anything still arriving is
+            // unanticipated — which is exactly the case that most needs disclosing
+            // rather than logging to a console nobody reads. The row is still lost
+            // (whatever threw did so before `emit`), but the loss is now on the
+            // record instead of being indistinguishable from a request that never
+            // happened.
+            emitCollectorError(`request handling failed, so no NETWORK_REQUEST row was recorded for ${request.method()} ${request.url()}`, error);
+            console.error(`[browser-network:${session.sessionId}] request handling failed: ${String(error)}`);
+        });
+        inFlight.add(handled);
+        void handled.finally(() => inFlight.delete(handled));
+    }
+    async function onRequestFinished(request) {
+        const alreadyTimedOut = !pending.has(request);
+        clearPending(request);
+        if (alreadyTimedOut)
+            return; // this collector already reported it as timed out; a late real completion is not double-reported
+        const response = await request.response();
+        if (response === null)
+            return; // finished with no response is a real, if rare, Playwright outcome -- nothing to report
+        const headers = await response.allHeaders().catch(() => response.headers());
+        // **A response inherits its own request's correlation ids.** This read
+        // the response headers alone, and the result was that a NETWORK_REQUEST
+        // carried `x-request-id` while the NETWORK_RESPONSE and HTTP_ERROR for
+        // the very same exchange carried null — because a server is under no
+        // obligation to echo a header the client sent, and most do not.
+        //
+        // RT-044 measured what that cost: on the real fixture, one source landed
+        // in the real request bucket and two fell into the unscoped pool, which
+        // was the only route to `confirmed` and the reason the gate had to be
+        // tightened. This is the other half of that finding — the half that adds
+        // attribution rather than removing a false one.
+        //
+        // **This is not proxy matching.** `request` is the Playwright Request
+        // object this response belongs to, not one selected by matching a URL or
+        // a timestamp. It is the same HTTP exchange, so carrying its id forward
+        // is bookkeeping, not inference — which is exactly what separates it
+        // from joining a console message to a request by URL, something this
+        // collector still cannot honestly do.
+        //
+        // Per field, and the response wins: a server that assigns or rewrites an
+        // id is authoritative about the request it actually processed, which is
+        // the id its logs will carry. The request's value fills a gap, never
+        // overrides.
+        const fromResponse = extractHeaderCorrelationIds(headers);
+        const fromRequest = extractHeaderCorrelationIds(request.headers());
+        const traceId = fromResponse.traceId ?? fromRequest.traceId;
+        const requestId = fromResponse.requestId ?? fromRequest.requestId;
+        /** Which side of the exchange each id came from — so a reader can audit the join rather than trust it. */
+        const correlationOrigin = {
+            traceId: fromResponse.traceId !== null ? "response-headers" : fromRequest.traceId !== null ? "request-headers" : null,
+            requestId: fromResponse.requestId !== null ? "response-headers" : fromRequest.requestId !== null ? "request-headers" : null,
+        };
+        const status = response.status();
+        const body = await captureResponseBody(response, headers);
+        const basePayload = {
+            status,
+            statusText: response.statusText(),
+            url: response.url(),
+            headers,
+            body,
+            timing: request.timing(),
+            browserSessionId: session.sessionId,
+            correlationOrigin,
+        };
+        emit?.({
+            timestamp: new Date().toISOString(),
+            source,
+            service: options.service ?? null,
+            process: null,
+            eventType: "NETWORK_RESPONSE",
+            payload: basePayload,
+            traceId,
+            requestId,
+            correlationId: null,
+            graphNodeId: null,
+            sourceLocation: null,
+            stackTrace: null,
+            confidence: 1,
+            redactionStatus: "pending-redaction",
+            collectorVersion: COLLECTOR_VERSION,
+        });
+        if (status >= 400) {
+            emit?.({
+                timestamp: new Date().toISOString(),
+                source,
+                service: options.service ?? null,
+                process: null,
+                eventType: "HTTP_ERROR",
+                payload: { ...basePayload, method: request.method() },
+                traceId,
+                requestId,
+                correlationId: null,
+                graphNodeId: null,
+                sourceLocation: null,
+                stackTrace: null,
+                confidence: 1,
+                redactionStatus: "pending-redaction",
+                collectorVersion: COLLECTOR_VERSION,
+            });
+        }
+    }
+    function onRequestFailed(request) {
+        const alreadyTimedOut = !pending.has(request);
+        clearPending(request);
+        if (alreadyTimedOut)
+            return; // already reported as a collector timeout; a late Playwright failure is not double-reported
+        const headers = request.headers();
+        const { traceId, requestId } = extractHeaderCorrelationIds(headers);
+        emit?.({
+            timestamp: new Date().toISOString(),
+            source,
+            service: options.service ?? null,
+            process: null,
+            eventType: "HTTP_ERROR",
+            payload: {
+                // No response ever arrived -- status: null distinguishes this from
+                // a real HTTP error status, which onRequestFinished handles.
+                status: null,
+                method: request.method(),
+                url: request.url(),
+                networkError: request.failure()?.errorText ?? "unknown network failure",
+                browserSessionId: session.sessionId,
+            },
+            traceId,
+            requestId,
+            correlationId: null,
+            graphNodeId: null,
+            sourceLocation: null,
+            stackTrace: null,
+            confidence: 1,
+            redactionStatus: "pending-redaction",
+            collectorVersion: COLLECTOR_VERSION,
+        });
+    }
+    /**
+     * A WebSocket connection attempt -- `page.on("websocket")` firing.
+     * Reuses `NETWORK_REQUEST` (see this file's module doc, RT-225): a real
+     * outbound call was made to `ws.url()`, the same fact that type already
+     * exists to record. No `method`/`headers`/`postData` are invented --
+     * Playwright's `WebSocket` object exposes none of those, so they are
+     * simply absent from the payload rather than null-padded to look like a
+     * fetch/XHR request. `traceId`/`requestId` stay null: unlike `fetch()`,
+     * a page cannot attach a custom header to a WebSocket handshake, so
+     * there is no channel for this collector's own correlation id to ride on
+     * (`frontend-initiator-capture.ts`'s mechanism is fetch-only for the
+     * identical reason).
+     */
+    function emitWebSocketAttempt(ws) {
+        emit?.({
+            timestamp: new Date().toISOString(),
+            source,
+            service: options.service ?? null,
+            process: null,
+            eventType: "NETWORK_REQUEST",
+            payload: {
+                url: ws.url(),
+                protocol: "websocket",
+                browserSessionId: session.sessionId,
+            },
+            traceId: null,
+            requestId: null,
+            correlationId: null,
+            graphNodeId: null,
+            sourceLocation: null,
+            stackTrace: null,
+            confidence: 1,
+            redactionStatus: "pending-redaction",
+            collectorVersion: COLLECTOR_VERSION,
+        });
+    }
+    /**
+     * A WebSocket-level failure -- `socketerror`. Reuses `HTTP_ERROR` with
+     * `status: null`, the identical "no usable response ever came back"
+     * convention `onRequestFailed` above already uses for a refused
+     * `fetch()`: this is the same class of fact (an outbound network call
+     * that never got a usable response) under a different wire protocol, not
+     * a different fact requiring a different type.
+     */
+    function emitWebSocketError(ws, errorText) {
+        emit?.({
+            timestamp: new Date().toISOString(),
+            source,
+            service: options.service ?? null,
+            process: null,
+            eventType: "HTTP_ERROR",
+            payload: {
+                // No response ever arrived, and there is no HTTP status for a
+                // WebSocket handshake failure in the first place -- status: null
+                // is the same "never got a response" bucket onRequestFailed uses,
+                // not a WS-specific meaning bolted onto it.
+                status: null,
+                url: ws.url(),
+                protocol: "websocket",
+                networkError: errorText,
+                browserSessionId: session.sessionId,
+            },
+            traceId: null,
+            requestId: null,
+            correlationId: null,
+            graphNodeId: null,
+            sourceLocation: null,
+            stackTrace: null,
+            confidence: 1,
+            redactionStatus: "pending-redaction",
+            collectorVersion: COLLECTOR_VERSION,
+        });
+    }
+    /**
+     * A WebSocket closed with no prior `socketerror` reported for it. Its own
+     * type, `WEBSOCKET_CLOSED` (`runtime-event.ts`) -- see that type's doc
+     * for why forcing this into `NETWORK_RESPONSE` would misrepresent what
+     * was actually observed (no status, no body, nothing HTTP happened) and
+     * why "normal" vs. "abnormal" is not claimed either (measured: Playwright
+     * exposes no close code or reason on this event at all).
+     */
+    function emitWebSocketClosed(ws) {
+        emit?.({
+            timestamp: new Date().toISOString(),
+            source,
+            service: options.service ?? null,
+            process: null,
+            eventType: "WEBSOCKET_CLOSED",
+            payload: {
+                url: ws.url(),
+                protocol: "websocket",
+                browserSessionId: session.sessionId,
+            },
+            traceId: null,
+            requestId: null,
+            correlationId: null,
+            graphNodeId: null,
+            sourceLocation: null,
+            stackTrace: null,
+            confidence: 1,
+            redactionStatus: "pending-redaction",
+            collectorVersion: COLLECTOR_VERSION,
+        });
+    }
+    function onWebSocket(ws) {
+        const tracked = {
+            reported: false,
+            onSocketError: (error) => {
+                const entry = activeSockets.get(ws);
+                if (entry !== undefined)
+                    entry.reported = true;
+                emitWebSocketError(ws, error);
+            },
+            onClose: () => {
+                const entry = activeSockets.get(ws);
+                activeSockets.delete(ws);
+                // A failure already reported this exact socket via HTTP_ERROR --
+                // `close` always follows a failed connection, and reporting it
+                // again here would double-report the identical failure under a
+                // second eventType, the same double-report `onRequestFinished`/
+                // `onRequestFailed` guard against via `alreadyTimedOut` above.
+                if (entry?.reported !== true)
+                    emitWebSocketClosed(ws);
+            },
+        };
+        activeSockets.set(ws, tracked);
+        ws.on("socketerror", tracked.onSocketError);
+        ws.on("close", tracked.onClose);
+        emitWebSocketAttempt(ws);
+    }
+    function onRequestFinishedHandler(request) {
+        // Playwright event handlers don't propagate a returned promise's
+        // rejection to the emitter -- an unhandled rejection here would
+        // silently vanish rather than surface. Caught and logged rather than
+        // crashing the page's event loop, same failure-containment choice
+        // LogCollector's background consumption already makes.
+        const handled = onRequestFinished(request).catch((error) => {
+            console.error(`[browser-network:${session.sessionId}] requestfinished handling failed: ${String(error)}`);
+        });
+        // **Tracked, for the identical reason `onRequest` above is.** This
+        // handler is asynchronous the whole way down -- `request.response()`,
+        // `response.allHeaders()` and `captureResponseBody()` are each an IPC
+        // round-trip to the browser -- while Playwright's listener is not. Left
+        // untracked, a `NETWORK_RESPONSE` for a response the browser had already
+        // fully received met an `emit` that `stop()` had set to `undefined`
+        // underneath it, and the row was gone with nothing to say so. That is
+        // RT-023's regression exactly, one listener over in the same file: the
+        // fix was applied to `request` and not to `requestfinished`.
+        inFlight.add(handled);
+        void handled.finally(() => inFlight.delete(handled));
+    }
+    return {
+        collectorId: `browser-network:${session.sessionId}`,
+        async start(context) {
+            if (!session.isUsable()) {
+                return { available: false, reason: "the browser session's page has already crashed or closed." };
+            }
+            emit = context.emit;
+            resolveSourceRoot = context.resolveSourceRoot;
+            networkTimeoutMs = options.networkTimeoutMs ?? context.configuration.timeoutMs ?? DEFAULT_NETWORK_TIMEOUT_MS;
+            stacksParsed = options.stackTraceParser !== undefined && context.resolveSourceRoot !== undefined;
+            if (stacksParsed) {
+                initiatorCapture = createFrontendInitiatorCapture();
+                // Must be installed (and, per `page.addInitScript`'s own contract,
+                // installed before any navigation this execution wants covered) —
+                // start() being async is exactly what lets a caller await this
+                // before calling page.goto(), the identical ordering
+                // BrowserConsoleCollector's own page.on() registration already
+                // relies on.
+                await initiatorCapture.install(page);
+            }
+            page.on("request", onRequest);
+            page.on("requestfinished", onRequestFinishedHandler);
+            page.on("requestfailed", onRequestFailed);
+            page.on("websocket", onWebSocket);
+            return { available: true };
+        },
+        async stop() {
+            page.off("request", onRequest);
+            page.off("requestfinished", onRequestFinishedHandler);
+            page.off("requestfailed", onRequestFailed);
+            page.off("websocket", onWebSocket);
+            for (const timer of pending.values())
+                clearTimeout(timer);
+            pending.clear();
+            // `page.off("websocket", ...)` above only stops new sockets from
+            // being tracked -- a socket already open keeps its own `socketerror`/
+            // `close` listeners live until they are individually detached here,
+            // the same "no removeAllListeners on this interface" reason
+            // `TrackedSocket` keeps the exact listener references it registered.
+            for (const [ws, tracked] of activeSockets) {
+                ws.off("socketerror", tracked.onSocketError);
+                ws.off("close", tracked.onClose);
+            }
+            activeSockets.clear();
+            // Listeners off, timers cleared, THEN drain in-flight stack
+            // resolution, THEN clear emit -- draining before clearing is the
+            // RT-023-regression fix `BrowserConsoleCollector.stop()` already
+            // applies, for the identical reason: a NETWORK_REQUEST whose stack
+            // was still resolving when stop() was called must not be silently
+            // dropped by `emit?.()` becoming a no-op out from under it.
+            await Promise.allSettled([...inFlight]);
+            emit = undefined;
+        },
+        capabilities() {
+            return stacksParsed ? CAPABILITIES_WITH_STACKS : CAPABILITIES;
+        },
+    };
+}
+//# sourceMappingURL=browser-network-collector.js.map