@dimina-kit/devtools 0.4.0 → 0.5.0-dev.20260908120530

package/dist/main/services/network-forward/http.js

@@ -0,0 +1,162 @@
+/**
+ * Synthesize Chrome DevTools Protocol `Network.request*`/`Network.loading*`
+ * messages from the main-process HTTP request trace stream (see
+ * electron-runtime `native-request/trace.ts`).
+ *
+ * Why this exists: `wx.request` runs on Node http/https in the MAIN process
+ * (see native-request's design notes — this replaced a renderer `fetch()`
+ * specifically to stop Chromium's Fetch/CORS algorithm from attaching a
+ * spurious OPTIONS preflight to it) — no `webContents.debugger` can observe
+ * it, so the embedded DevTools Network tab would otherwise show nothing for
+ * every wx.request call. The trace stream gives one ordered fact per
+ * lifecycle moment; this module re-shapes each fact into the CDP events the
+ * front-end already renders natively for an XHR-classified resource
+ * (`requestWillBeSent` creates the row, `responseReceived` fills in
+ * status/headers, `loadingFinished`/`loadingFailed` settles it).
+ *
+ * Ordering contract this module relies on (guaranteed by the trace layer):
+ * `sent` strictly precedes every other event for its requestId, and exactly
+ * one of `loadingFinished`/`loadingFailed` terminates each sent request. The
+ * front-end silently drops loading events for an unknown requestId, so this
+ * module mirrors that discipline defensively: any non-`sent` event for an
+ * unknown requestId is dropped rather than synthesized.
+ *
+ * Pure and self-contained (no Electron imports) so it is unit-testable.
+ */
+import { NATIVE_HTTP_REQUEST_ID_PREFIX } from "./request-ids.js";
+import { isUserFacingRequest } from "./user-facing.js";
+/** CDP `Network.ResourceType` this forwarder classifies every wx.request
+ * call as — the same bucket the real front-end uses for `XMLHttpRequest`/
+ * `fetch()` business calls, so it renders with the matching icon/filter. */
+const RESOURCE_TYPE = "XHR";
+export class RequestTraceSynthesizer {
+    options;
+    requests = new Map();
+    seq = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Map one trace event to its CDP message, or null when the event must be
+     * dropped (a non-`sent` event for a requestId this synthesizer never saw
+     * sent — defensive against out-of-order delivery).
+     */
+    synthesize(sessionId, event) {
+        const key = `${sessionId} ${event.requestId}`;
+        if (event.type === "sent" || event.type === "redirect") {
+            return this.synthesizeRequest(key, event);
+        }
+        const state = this.requests.get(key);
+        if (!state)
+            return null;
+        const { requestId, userFacing } = state;
+        const timestamp = event.time / 1000;
+        switch (event.type) {
+            case "response":
+                return {
+                    method: "Network.responseReceived",
+                    params: {
+                        requestId,
+                        loaderId: requestId,
+                        timestamp,
+                        type: RESOURCE_TYPE,
+                        response: {
+                            url: state.url,
+                            status: event.status,
+                            statusText: event.statusText,
+                            headers: event.headers,
+                            // Chromium uses these together to replace provisional headers
+                            // and expose the verbatim source. ExtraInfo has no raw request
+                            // text and would override this response snapshot in the frontend.
+                            ...(event.requestHeaders && event.requestHeadersText ? {
+                                requestHeaders: event.requestHeaders,
+                                requestHeadersText: event.requestHeadersText,
+                            } : {}),
+                            mimeType: mimeTypeOf(event.headers),
+                            connectionReused: false,
+                            connectionId: 0,
+                            encodedDataLength: 0,
+                            fromDiskCache: false,
+                            fromServiceWorker: false,
+                        },
+                    },
+                    userFacing,
+                };
+            case "finished":
+                // Terminal: release the id mapping so a long-lived owner can't grow it.
+                this.requests.delete(key);
+                return {
+                    method: "Network.loadingFinished",
+                    params: {
+                        requestId,
+                        timestamp,
+                        encodedDataLength: event.encodedDataLength,
+                    },
+                    userFacing,
+                    ...(event.body !== undefined ? { body: { base64Encoded: event.bodyBase64Encoded, body: event.body } } : {}),
+                };
+            case "failed":
+                this.requests.delete(key);
+                return {
+                    method: "Network.loadingFailed",
+                    params: {
+                        requestId,
+                        timestamp,
+                        type: RESOURCE_TYPE,
+                        errorText: event.errorText,
+                    },
+                    userFacing,
+                };
+        }
+    }
+    synthesizeRequest(key, event) {
+        const previous = this.requests.get(key);
+        if (event.type === "redirect" && !previous)
+            return null;
+        const requestId = event.type === "redirect" ? previous.requestId
+            : `${NATIVE_HTTP_REQUEST_ID_PREFIX}${this.options.epoch}:${this.seq++}`;
+        const userFacing = event.type === "redirect" ? previous.userFacing : isUserFacingRequest(event.url, this.options.internalOrigins?.());
+        this.requests.set(key, { requestId, url: event.url, userFacing });
+        const timestamp = event.time / 1000;
+        const hasPostData = event.hasPostData ?? event.postData !== undefined;
+        const message = {
+            method: "Network.requestWillBeSent",
+            params: {
+                requestId,
+                loaderId: requestId,
+                documentURL: event.url,
+                request: {
+                    url: event.url,
+                    method: event.method,
+                    headers: event.headers,
+                    hasPostData,
+                    ...(hasPostData ? { postData: event.postData } : {}),
+                },
+                timestamp,
+                wallTime: timestamp,
+                initiator: { type: "script" },
+                type: RESOURCE_TYPE,
+                ...(event.type === "redirect" ? { redirectResponse: {
+                        ...event.redirectResponse,
+                        mimeType: mimeTypeOf(event.redirectResponse.headers),
+                        connectionReused: false, connectionId: 0, encodedDataLength: 0,
+                    } } : {}),
+            },
+            userFacing,
+        };
+        if (hasPostData)
+            message.postData = event.postData;
+        return message;
+    }
+}
+/** `Content-Type: application/json; charset=utf-8` → `application/json`. Case
+ * -insensitive header lookup, matching HTTP semantics. */
+function mimeTypeOf(headers) {
+    for (const [name, value] of Object.entries(headers)) {
+        if (name.toLowerCase() !== "content-type")
+            continue;
+        return value.split(";")[0]?.trim() ?? "";
+    }
+    return "";
+}
+//# sourceMappingURL=http.js.map

package/dist/main/services/network-forward/index.d.ts

@@ -49,23 +49,57 @@
  *  ✅ Forwarded to the native Network tab: requestWillBeSent, responseReceived,
  *     loadingFinished, loadingFailed (+ requestWillBeSentExtraInfo /
  *     responseReceivedExtraInfo when present, for accurate headers/status).
- *  ⏳ TODO (二期): `dataReceived` per-chunk forwarding (skipped to avoid an
- *     executeJavaScript per chunk), and response body / preview (needs hooking
- *     `InspectorFrontendHost.sendMessageToBackend` + a prefetched body cache so
- *     the front-end's `Network.getResponseBody` round-trip resolves).
- *  ⚠️ NOT captured here: requests issued from inside a render-host `<webview>`
- *     guest (page-level resource loads / page `fetch`). The safe-area service
- *     already owns each guest's `wc.debugger`, and `debugger.attach` is
- *     single-owner — bringing those in needs a shared CDP broker. `source:'render'`
- *     is reserved for when that's added (later).
- *  ⚠️ NOT observable by any `webContents.debugger`: a request a host module issues
- *     directly from the MAIN process. Those need an explicit `report()` call
- *     (exposed below; it uses the console fallback path).
+ *  ✅ Response body / preview and request post data: prefetched from the
+ *     simulator's CDP session at loadingFinished into a bounded cache keyed by
+ *     the VIRTUAL id (`bodies`, see NetworkBodyProvider). The front-end's
+ *     `Network.getResponseBody` / `Network.getRequestPostData` round-trips for
+ *     `dimina:sim:` ids are intercepted by the outbound CDP gate that
+ *     elements-forward installs on `InspectorFrontendHost.sendMessageToBackend`
+ *     and answered from that cache — the service-host backend the front-end
+ *     natively talks to has never heard of these ids.
+ *  ⏳ TODO: `dataReceived` per-chunk forwarding (skipped to avoid an
+ *     executeJavaScript per chunk).
+ *  ✅ Requests issued from inside a render-host `<webview>` guest (page-level
+ *     resource loads / page `fetch`, tagged `source: 'render'`) — `attachRenderGuest`
+ *     acquires a lease from the shared `CdpSessionBroker` (cdp-session/index.ts),
+ *     which is single owner of every render-guest `wc.debugger` session across
+ *     this forwarder, safe-area, elements-forward and render-inspect. An
+ *     external detach (another owner releasing the shared session, or a real
+ *     Chrome DevTools window) self-heals via the lease's `onDetach` — capture
+ *     re-wires itself even though `attachRenderGuest` is only ever called ONCE
+ *     per guest (at webview creation).
+ *  ⚠️ NOT observable by any `webContents.debugger`: traffic a host module issues
+ *     directly from the MAIN process. Plain requests need an explicit `report()`
+ *     call (console fallback path); `wx.connectSocket` sockets (Node `ws`
+ *     transport) arrive as trace events via `reportWebSocketTrace` and are
+ *     synthesized into `Network.webSocket*` CDP messages (see websocket.ts).
  */
-import type { WebContents } from 'electron';
-import { type ConnectionRegistry, type Disposable } from '@dimina-kit/electron-deck/main';
+import type { WebContents } from "electron";
+import { type ConnectionRegistry, type Disposable } from "@dimina-kit/electron-deck/main";
+import { type CdpSessionBroker } from "../cdp-session/index.js";
+import type { NativeRequestTrace, NativeWebSocketTrace } from "../../ipc/bridge-router.js";
+export { VIRTUAL_REQUEST_ID_PREFIX } from "./request-ids.js";
+/** CDP `Network.getResponseBody` result shape (served from the prefetch cache). */
+export interface CdpResponseBody {
+    body: string;
+    base64Encoded: boolean;
+}
+/**
+ * Answers the front-end's body/post-data lookups for virtual requestIds. The
+ * outbound CDP gate (elements-forward) consumes this: it intercepts the
+ * front-end's `Network.getResponseBody` / `Network.getRequestPostData` for
+ * `dimina:sim:` ids (the service-host backend has never heard of them) and
+ * replies from here instead. Rejections carry the same not-found message a
+ * real CDP backend produces for an unknown requestId.
+ */
+export interface NetworkBodyProvider {
+    getResponseBody(requestId: string): Promise<CdpResponseBody>;
+    getRequestPostData(requestId: string): Promise<{
+        postData: string;
+    }>;
+}
 /** Which layer a captured request came from (tags the fallback log line). */
-export type NetworkSource = 'service' | 'render';
+export type NetworkSource = "service" | "render";
 /** A normalized completed network request, used only by the console fallback. */
 export interface NetworkRequestRecord {
     source: NetworkSource;
@@ -90,6 +124,26 @@ export interface NetworkForwarderBridge {
      * `setDevtoolsHost`. Null until the DevTools host view exists.
      */
     getDevtoolsWc?(): WebContents | null;
+    /**
+     * The dimina resource server's baseUrl (e.g. `'http://127.0.0.1:54321/'`),
+     * when running — consulted by `isUserFacingRequest` so the framework
+     * bundle it serves is classified as host-internal, not business traffic.
+     * Absent → that origin check is simply skipped (the scheme rule alone
+     * still filters out file:// / difile:// / devtools:// framework loads).
+     */
+    getResourceServerBaseUrl?(): string | null;
+    /**
+     * The simulator's own static-asset server baseUrl (serves `simulator.html`
+     * + its JS/CSS — a devkit-owned server, independent from the resource
+     * server above, on its own dynamically-assigned port), when a project is
+     * open — consulted by `isUserFacingRequest` alongside
+     * `getResourceServerBaseUrl` so the simulator SHELL's own asset loading
+     * (captured because `attachSimulator` CDP-observes that whole
+     * WebContentsView, not just the mini-app's own `wx.request` calls) isn't
+     * misclassified as the developer's business traffic. Absent → that origin
+     * check is simply skipped.
+     */
+    getSimulatorServerBaseUrl?(): string | null;
     /**
      * Optional connection-layer registry (`@dimina-kit/electron-deck/main`). When
      * present, per-webContents teardowns route through `acquire(wc).own(d)` so the
@@ -98,6 +152,18 @@ export interface NetworkForwarderBridge {
      * `once('destroyed')` fallback is used, so existing callers compile unchanged.
      */
     connections?: ConnectionRegistry;
+    /**
+     * Shared CDP session broker (see cdp-session/index.ts) that owns every
+     * render-guest AND simulator debugger session's attach/detach lifecycle —
+     * safe-area, elements-forward, render-inspect and simulator-storage acquire
+     * leases from the same instance. Absent → a private broker is created and
+     * owned for this forwarder's lifetime (torn down on `dispose()`), so
+     * existing standalone callers/tests compile and behave unchanged, just
+     * without cross-module session sharing. Both `attachRenderGuest` and
+     * `attachSimulator` go through it — see detachSimulator's docstring for why
+     * the simulator path never forces a physical detach either.
+     */
+    broker?: CdpSessionBroker;
 }
 export interface NetworkForwarder extends Disposable {
     /**
@@ -109,17 +175,71 @@ export interface NetworkForwarder extends Disposable {
     attachSimulator(wc: WebContents): void;
     /** Detach from the current simulator WCV (without disposing the forwarder). */
     detachSimulator(): void;
+    /**
+     * Wire a render-host guest wc (pageFrame) for Network capture — page-level
+     * resource loads (images/fonts/page fetch) that never touch the simulator's
+     * network stack. Idempotent per wc. Acquires a lease from the shared
+     * `CdpSessionBroker` (cdp-session/index.ts) — reuses an already-attached
+     * session (safe-area / elements-forward / render-inspect may have attached
+     * first) or self-attaches when no one has; the broker alone decides who may
+     * detach. Self-heals after an external detach (the lease's `onDetach`
+     * re-wires automatically) even though this is only ever called ONCE per
+     * guest, at webview creation. Events share the simulator capture's
+     * virtual-id namespace prefix (distinct epochs keep them collision-free) and
+     * the same body prefetch cache.
+     */
+    attachRenderGuest(wc: WebContents): void;
     /**
      * Point the forwarder at the WebContents hosting the DevTools FRONT-END (the
      * primary, native-Network-tab sink). Pass null when that view is torn down so
      * we fall back to the console line. Re-callable across DevTools re-creates.
      */
     setDevtoolsHost(wc: WebContents | null): void;
+    /**
+     * Point the forwarder at the WebContents hosting the standalone internal
+     * (app-wide) DevTools window's front-end — the global mirror sink.
+     * Unlike `setDevtoolsHost` (the user-facing sink), this has NO probing/
+     * ready/degraded state machine and NO console fallback: every
+     * FORWARDED_METHODS event is mirrored here raw and UNFILTERED (no
+     * `isUserFacingRequest` gating) whenever a host is set, best-effort (a
+     * failed dispatch is silently dropped — nobody depends on this path having
+     * a fallback). Pass null when the window closes.
+     */
+    setGlobalDevtoolsHost(wc: WebContents | null): void;
     /**
      * Manually surface a request that no `webContents.debugger` can observe
      * (e.g. a main-process direct send). Uses the console fallback sink.
      */
     report(record: NetworkRequestRecord): void;
+    /**
+     * Surface one main-process WebSocket trace event (wx.connectSocket traffic
+     * lives on the Node `ws` transport, invisible to any debugger) as a
+     * synthesized `Network.webSocket*` CDP event, injected through the SAME
+     * channels as forwarded simulator traffic: the global mirror unfiltered,
+     * plus the user-facing native sink when the socket's url classified
+     * user-facing. Best-effort like every injection point — never throws.
+     */
+    reportWebSocketTrace(sessionId: string, event: NativeWebSocketTrace): void;
+    /**
+     * Surface one main-process HTTP request trace event (wx.request traffic
+     * runs on Node http/https, invisible to any debugger, precisely so it
+     * skips Chromium's Fetch/CORS algorithm and its OPTIONS preflight) as a
+     * synthesized `Network.request*`/`Network.loading*` CDP event, through the
+     * SAME channels as forwarded simulator traffic: the global mirror
+     * unfiltered, plus the user-facing native sink when the request's url
+     * classified user-facing. `finished` primes the body cache (the response is
+     * already fully buffered in-process, no CDP round-trip needed); `sent`
+     * primes the post-data cache when the request carried a body. Best-effort
+     * like every injection point — never throws.
+     */
+    reportNativeRequestTrace(sessionId: string, event: NativeRequestTrace): void;
+    /**
+     * Body/post-data lookups for the virtual requestIds this forwarder injected,
+     * backed by the loadingFinished-time prefetch cache. Keyed by virtual id, so
+     * entries stay valid across detach/re-attach (each attach epoch mints
+     * non-colliding ids); dispose() drops them all.
+     */
+    readonly bodies: NetworkBodyProvider;
 }
 /**
  * CDP events whose `params.requestId` we rewrite into the virtual namespace.