@itmetsam/samurai-framework 0.10.0 → 0.12.0

package/dist/network/network-tracker.js

@@ -1,18 +1,13 @@
 import EventEmitter from "node:events";
 import logger from "../logger/index.js";
-import { WaitTimeoutError } from "../wait/wait-until.js";
+import { headersFromBidi, toRequest } from "./bidi-wire.js";
+import { NetworkIdleTimeoutError } from "./network-wait.js";
+import {} from "./network-types.js";
+export { NetworkIdleTimeoutError } from "./network-wait.js";
 /** The error text of a request that the page left before it finished, when the browser says none */
 const ABORTED_BY_NAVIGATION = "aborted by navigation";
 /** How many URLs a timeout message names */
 const URLS_IN_MESSAGE = 5;
-/** waitForIdle ran out of time with requests still in flight; `last` holds (up to five of) their URLs */
-export class NetworkIdleTimeoutError extends WaitTimeoutError {
-    constructor(timeout, inflight, urls) {
-        super(timeout, urls);
-        this.name = "NetworkIdleTimeoutError";
-        this.message = `waitForNetworkIdle(): still ${inflight} request(s) in flight after ${timeout}ms: ${urls.join(", ")}`;
-    }
-}
 /**
  * Follows the network activity of one page (its frames included): which requests are in flight,
  * and `request` / `response` / `requestfailed` events. In-flight is keyed by `request id:redirect count`,
@@ -25,28 +20,26 @@ export class NetworkTracker {
         this.ignore = ignore;
         this.connector = connector;
         this.events = new EventEmitter();
-        this.active = new Map();
-        /** The context each request in flight belongs to, by the same key */
-        this.contexts = new Map();
-        /** Requests that may still be the source of a redirect, by hop key */
+        /**
+         * Every hop that is in flight or may still be the source of a redirect, by hop key. A redirect response ends a
+         * hop's flight (`live` false) but keeps it, for the next hop's `redirectedFrom`.
+         */
         this.hops = new Map();
+        /** Rejects a pending `waitForIdle`; each wait adds its own */
         this.waiters = new Set();
         this.disposed = false;
         this.onBeforeRequestSent = (params) => {
             if (!this.owns(params.context))
                 return;
             const key = NetworkTracker.key(params.request, params.redirectCount);
-            const redirectCount = Number(params.redirectCount);
+            const { redirectCount } = params;
             const previousKey = `${params.request.request}:${redirectCount - 1}`;
-            const redirectedFrom = redirectCount > 0 ? (this.hops.get(previousKey) ?? null) : null;
+            const redirectedFrom = redirectCount > 0 ? (this.hops.get(previousKey)?.request ?? null) : null;
             this.hops.delete(previousKey);
             const request = toRequest(params.request, params.navigation, params.isBlocked, redirectedFrom);
             if (this.ignore(request))
                 return;
-            this.hops.set(key, request);
-            this.active.set(key, request.url);
-            if (params.context)
-                this.contexts.set(key, params.context);
+            this.hops.set(key, { request, context: params.context, live: true });
             this.emit("request", request);
             this.events.emit("change");
         };
@@ -54,19 +47,21 @@ export class NetworkTracker {
             if (!this.owns(params.context))
                 return;
             const key = NetworkTracker.key(params.request, params.redirectCount);
-            const request = this.hops.get(key);
-            if (!this.active.delete(key) || !request)
+            const hop = this.hops.get(key);
+            if (!hop?.live)
                 return;
-            this.contexts.delete(key);
+            const { request } = hop;
             const { response } = params;
             // A redirect response keeps its request around: the next hop links back to it
             if (response.status < 300 || response.status >= 400)
                 this.hops.delete(key);
+            else
+                hop.live = false;
             this.emit("response", {
                 url: response.url,
                 status: response.status,
                 statusText: response.statusText,
-                headers: toHeaders(response.headers),
+                headers: headersFromBidi(response.headers),
                 fromCache: response.fromCache,
                 request,
             });
@@ -76,12 +71,11 @@ export class NetworkTracker {
             if (!this.owns(params.context))
                 return;
             const key = NetworkTracker.key(params.request, params.redirectCount);
-            const request = this.hops.get(key);
-            if (!this.active.delete(key) || !request)
+            const hop = this.hops.get(key);
+            if (!hop?.live)
                 return;
-            this.contexts.delete(key);
             this.hops.delete(key);
-            this.emit("requestfailed", Object.assign(request, { errorText: params.errorText }));
+            this.emit("requestfailed", Object.assign(hop.request, { errorText: params.errorText }));
             this.events.emit("change");
         };
         /**
@@ -92,14 +86,11 @@ export class NetworkTracker {
             if (!this.owns(params.context))
                 return;
             let changed = false;
-            for (const [key, requestContext] of [...this.contexts]) {
-                const request = this.hops.get(key);
-                if (!request || request.navigation === params.navigation)
+            for (const [key, { request, context, live }] of [...this.hops]) {
+                if (!live || request.navigation === params.navigation)
                     continue;
-                if (!this.tree.isWithin(requestContext, params.context))
+                if (!this.tree.isWithin(context, params.context))
                     continue;
-                this.contexts.delete(key);
-                this.active.delete(key);
                 this.hops.delete(key);
                 this.emit("requestfailed", Object.assign(request, { errorText: ABORTED_BY_NAVIGATION }));
                 changed = true;
@@ -131,11 +122,14 @@ export class NetworkTracker {
     }
     /** Requests currently in flight */
     get inflight() {
-        return this.active.size;
+        return this.liveHops().length;
     }
     /** URLs of the requests currently in flight, oldest first */
     get inflightUrls() {
-        return [...this.active.values()];
+        return this.liveHops().map(({ request }) => request.url);
+    }
+    liveHops() {
+        return [...this.hops.values()].filter(({ live }) => live);
     }
     /** Waits that have not finished yet */
     get waiting() {
@@ -154,9 +148,7 @@ export class NetworkTracker {
     waitForIdle({ idleTime, timeout, }) {
         return new Promise((resolve, reject) => {
             let idleTimer;
-            const waiter = {
-                reject: (reason) => finish(() => reject(reason)),
-            };
+            const waiter = (reason) => finish(() => reject(reason));
             const finish = (settle) => {
                 clearTimeout(idleTimer);
                 clearTimeout(deadline);
@@ -166,10 +158,10 @@ export class NetworkTracker {
             };
             const check = () => {
                 clearTimeout(idleTimer);
-                if (this.active.size === 0)
+                if (this.inflight === 0)
                     idleTimer = setTimeout(() => finish(resolve), idleTime);
             };
-            const deadline = setTimeout(() => finish(() => reject(new NetworkIdleTimeoutError(timeout, this.active.size, this.inflightUrls.slice(0, URLS_IN_MESSAGE)))), timeout);
+            const deadline = setTimeout(() => finish(() => reject(new NetworkIdleTimeoutError(timeout, this.inflight, this.inflightUrls.slice(0, URLS_IN_MESSAGE)))), timeout);
             this.waiters.add(waiter);
             this.events.on("change", check);
             check();
@@ -181,10 +173,8 @@ export class NetworkTracker {
             return;
         this.disposed = true;
         this.removeListeners();
-        this.active.clear();
-        this.contexts.clear();
         this.hops.clear();
-        [...this.waiters].forEach((waiter) => waiter.reject(new Error("page closed")));
+        [...this.waiters].forEach((reject) => reject(new Error("page closed")));
         await this.subscription?.unsubscribe();
     }
     removeListeners() {
@@ -197,7 +187,7 @@ export class NetworkTracker {
         return context !== null && this.tree.isWithin(context, this.contextId);
     }
     static key(data, redirectCount) {
-        return `${data.request}:${Number(redirectCount)}`;
+        return `${data.request}:${redirectCount}`;
     }
     /** A listener that throws must not stop the tracker or the other listeners */
     emit(event, ...args) {
@@ -211,27 +201,3 @@ export class NetworkTracker {
         }
     }
 }
-export function toRequest(data, navigation, isBlocked, redirectedFrom) {
-    return {
-        id: data.request,
-        url: data.url,
-        method: data.method,
-        headers: toHeaders(data.headers),
-        resourceType: data.destination || data.initiatorType || "other",
-        navigation,
-        redirectedFrom,
-        isBlocked,
-    };
-}
-/** Header list to a lower-cased record; repeated names are joined, base64 values decoded */
-export function toHeaders(headers) {
-    const result = {};
-    for (const { name, value } of headers) {
-        const text = value.type === "base64"
-            ? Buffer.from(value.value, "base64").toString("utf8")
-            : value.value;
-        const key = name.toLowerCase();
-        result[key] = key in result ? `${result[key]}, ${text}` : text;
-    }
-    return result;
-}

package/dist/network/network-types.d.ts

@@ -0,0 +1,33 @@
+export interface NetworkRequest {
+    /** The browser's id; the same for every hop of a redirect chain */
+    id: string;
+    url: string;
+    method: string;
+    /** Header names lower-cased; repeated headers joined with ", " */
+    headers: Record<string, string>;
+    /** "document", "script", "image", …; falls back to the initiator type, then "other" */
+    resourceType: string;
+    navigation: string | null;
+    /** The request this one is the redirect of, or null */
+    redirectedFrom: NetworkRequest | null;
+    /** True while a network intercept holds it */
+    isBlocked: boolean;
+}
+export interface NetworkResponse {
+    url: string;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    fromCache: boolean;
+    request: NetworkRequest;
+}
+export type FailedRequest = NetworkRequest & {
+    errorText: string;
+};
+/** What `page.on` and the tracker emit: the event name and the arguments its listeners get */
+export interface EventMap {
+    request: [NetworkRequest];
+    response: [NetworkResponse];
+    requestfailed: [FailedRequest];
+}
+export type NetworkEventName = keyof EventMap;

package/dist/network/network-types.js

@@ -0,0 +1 @@
+export {};

package/dist/network/network-wait.d.ts

@@ -2,15 +2,20 @@ import { WaitTimeoutError } from "../wait/wait-until.js";
 import { type UrlPattern } from "./url-match.js";
 /** What `page.waitForRequest` / `waitForResponse` match: a URL pattern, or a function */
 export type NetworkMatch<T> = UrlPattern | ((item: T) => boolean);
-/** No matching request or response arrived in time */
-export declare class NetworkWaitTimeoutError extends WaitTimeoutError<undefined> {
+/** No matching request or response arrived in time; each subclass names itself */
+declare class NetworkWaitTimeoutError extends WaitTimeoutError<undefined> {
     constructor(operation: "waitForRequest" | "waitForResponse", match: NetworkMatch<never>, timeout: number);
 }
 export declare class RequestTimeoutError extends NetworkWaitTimeoutError {
 }
 export declare class ResponseTimeoutError extends NetworkWaitTimeoutError {
 }
+/** waitForIdle ran out of time with requests still in flight; `last` holds (up to five of) their URLs */
+export declare class NetworkIdleTimeoutError extends WaitTimeoutError<string[]> {
+    constructor(timeout: number, inflight: number, urls: string[]);
+}
 /** The predicate for a match: a function as it is, a URL pattern tested on the item's url */
 export declare function toPredicate<T extends {
     url: string;
 }>(match: NetworkMatch<T>): (item: T) => boolean;
+export {};

package/dist/network/network-wait.js

@@ -1,10 +1,10 @@
 import { WaitTimeoutError } from "../wait/wait-until.js";
 import { matchUrl } from "./url-match.js";
-/** No matching request or response arrived in time */
-export class NetworkWaitTimeoutError extends WaitTimeoutError {
+/** No matching request or response arrived in time; each subclass names itself */
+class NetworkWaitTimeoutError extends WaitTimeoutError {
     constructor(operation, match, timeout) {
         super(timeout, undefined);
-        this.name = operation === "waitForRequest" ? "RequestTimeoutError" : "ResponseTimeoutError";
+        this.name = new.target.name;
         const kind = operation === "waitForRequest" ? "request" : "response";
         this.message = `${operation}(): no ${kind} matching ${describeMatch(match)} within ${timeout}ms`;
     }
@@ -13,6 +13,14 @@ export class RequestTimeoutError extends NetworkWaitTimeoutError {
 }
 export class ResponseTimeoutError extends NetworkWaitTimeoutError {
 }
+/** waitForIdle ran out of time with requests still in flight; `last` holds (up to five of) their URLs */
+export class NetworkIdleTimeoutError extends WaitTimeoutError {
+    constructor(timeout, inflight, urls) {
+        super(timeout, urls);
+        this.name = "NetworkIdleTimeoutError";
+        this.message = `waitForNetworkIdle(): still ${inflight} request(s) in flight after ${timeout}ms: ${urls.join(", ")}`;
+    }
+}
 function describeMatch(match) {
     if (typeof match === "function")
         return "the given function";
@@ -20,5 +28,7 @@ function describeMatch(match) {
 }
 /** The predicate for a match: a function as it is, a URL pattern tested on the item's url */
 export function toPredicate(match) {
-    return typeof match === "function" ? match : (item) => matchUrl(match, item.url);
+    return typeof match === "function"
+        ? match
+        : (item) => matchUrl(match, item.url);
 }

package/dist/network/response.d.ts

@@ -1,4 +1,4 @@
-import type { NetworkRequest, NetworkResponse } from "./network-tracker.js";
+import type { NetworkRequest, NetworkResponse } from "./network-types.js";
 /** A response of the page, with access to its body */
 export declare class Response {
     private loadBody;

package/dist/network/response.js

@@ -36,7 +36,7 @@ export class Response {
             return JSON.parse(text);
         }
         catch (err) {
-            throw new Error(`Response body of ${this.url} is not JSON: ${err.message}`);
+            throw new Error(`json(): the response body of ${this.url} is not JSON: ${err.message}`);
         }
     }
 }

package/dist/network/route.d.ts

@@ -0,0 +1,92 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { NetworkRequest } from "./network-types.js";
+import type { UrlPattern } from "./url-match.js";
+export type RouteHandler = (route: Route) => void | Promise<void>;
+export interface FulfillOptions {
+    /** @default 200 */
+    status?: number;
+    headers?: Record<string, string>;
+    /** Sets `content-type` unless `headers` has one; `json` implies "application/json" */
+    contentType?: string;
+    body?: string | Buffer;
+    /** Sent as JSON text; cannot be combined with `body` */
+    json?: unknown;
+}
+export interface ContinueOptions {
+    /**
+     * Sends the request to another URL. Firefox applies this to navigations only: the page's `fetch`, XHR and
+     * image requests fail when their URL is changed, so mock those with `fulfill` instead
+     */
+    url?: string;
+    method?: string;
+    /** Replaces all request headers */
+    headers?: Record<string, string>;
+    postData?: string | Buffer;
+}
+export interface RouteEntry {
+    pattern: UrlPattern;
+    handler: RouteHandler;
+}
+/** Answers `network.*` commands for one blocked request */
+export interface RouteDeps {
+    send: BiDiConnector["send"];
+    /** Passes the request to the next matching route, or lets it continue */
+    next: () => Promise<void>;
+    /** Called once the route is answered, whichever way */
+    settled: () => void;
+    /**
+     * Whether a replaced body needs a `content-length` of its own. Firefox keeps the old one and cuts the new body
+     * off; Chrome sets the right one itself and hangs the request when it is given one.
+     */
+    sendsContentLength: boolean;
+}
+/**
+ * A request the browser holds until it is answered. Answer it exactly once with `fulfill`, `continue`,
+ * `abort` or `fallback`; a second call throws.
+ */
+export declare class Route {
+    private readonly info;
+    private readonly deps;
+    private answered;
+    constructor(info: NetworkRequest, deps: RouteDeps);
+    request(): NetworkRequest;
+    /** Answers the request without sending it: status 200 and no body unless told otherwise */
+    fulfill(options?: FulfillOptions): Promise<void>;
+    /**
+     * Lets the request go on, optionally changed. `headers` replaces all request headers. A new `postData` brings its
+     * own `content-length` (the request's old one would cut the new body off or leave the server waiting).
+     */
+    continue(options?: ContinueOptions): Promise<void>;
+    /** Makes the request fail (the browser reports a network error to the page) */
+    abort(): Promise<void>;
+    /** Hands the request to the next route that matches it, or lets it continue when there is none */
+    fallback(): Promise<void>;
+    private claim;
+    private answer;
+}
+/** What a `PendingRoute` needs of the router: how to talk to the browser and where to go on */
+export type PendingRouteControl = Omit<RouteDeps, "settled"> & {
+    /** Called once the request is answered, whichever way */
+    onSettled: (pending: PendingRoute) => void;
+};
+/**
+ * A request the browser holds, with what the router needs to see to it: the `Route` handed to the handler, the
+ * route entry that holds it, and the timer that lets it continue when the handler is too slow.
+ * Not part of the public API: handlers only ever see the `Route`.
+ */
+export declare class PendingRoute {
+    private readonly info;
+    readonly entry?: RouteEntry | undefined;
+    readonly route: Route;
+    private answered;
+    private timer;
+    /** `entry` is the route that holds the request; none for one nobody asked for */
+    constructor(info: NetworkRequest, control: PendingRouteControl, entry?: RouteEntry | undefined);
+    get isAnswered(): boolean;
+    /** Calls `onLate` when nothing answered after `ms`; the timer never keeps the process alive */
+    startTimer(ms: number, onLate: () => void): void;
+    /** Lets the request continue unchanged; failures are logged, not thrown */
+    release(): Promise<void>;
+    /** Fails the request; failures are logged, not thrown */
+    failQuietly(): Promise<void>;
+}

package/dist/network/route.js

@@ -0,0 +1,142 @@
+import { STATUS_CODES } from "node:http";
+import logger from "../logger/index.js";
+import { headersToBidi, toBytes } from "./bidi-wire.js";
+const hasHeader = (headers, name) => Object.keys(headers).some((key) => key.toLowerCase() === name);
+/**
+ * A request the browser holds until it is answered. Answer it exactly once with `fulfill`, `continue`,
+ * `abort` or `fallback`; a second call throws.
+ */
+export class Route {
+    constructor(info, deps) {
+        this.info = info;
+        this.deps = deps;
+        this.answered = false;
+    }
+    request() {
+        return this.info;
+    }
+    /** Answers the request without sending it: status 200 and no body unless told otherwise */
+    async fulfill(options = {}) {
+        if (options.json !== undefined && options.body !== undefined) {
+            throw new TypeError("fulfill(): use either json or body, not both");
+        }
+        const text = options.json !== undefined ? JSON.stringify(options.json) : undefined;
+        const body = options.body ?? text;
+        const headers = { ...options.headers };
+        const contentType = options.contentType ??
+            (text !== undefined ? "application/json" : undefined);
+        if (contentType && !hasHeader(headers, "content-type"))
+            headers["content-type"] = contentType;
+        if (!hasHeader(headers, "content-length")) {
+            headers["content-length"] = String(body === undefined ? 0 : Buffer.byteLength(body));
+        }
+        const status = options.status ?? 200;
+        await this.answer("network.provideResponse", {
+            request: this.info.id,
+            statusCode: status,
+            reasonPhrase: STATUS_CODES[status] ?? "",
+            headers: headersToBidi(headers),
+            ...(body !== undefined && { body: toBytes(body) }),
+        });
+    }
+    /**
+     * Lets the request go on, optionally changed. `headers` replaces all request headers. A new `postData` brings its
+     * own `content-length` (the request's old one would cut the new body off or leave the server waiting).
+     */
+    async continue(options = {}) {
+        let headers = options.headers;
+        if (options.postData !== undefined) {
+            const withoutLength = Object.fromEntries(Object.entries(headers ?? this.info.headers).filter(([name]) => name.toLowerCase() !== "content-length"));
+            headers = this.deps.sendsContentLength
+                ? {
+                    ...withoutLength,
+                    "content-length": String(Buffer.byteLength(options.postData)),
+                }
+                : withoutLength;
+        }
+        await this.answer("network.continueRequest", {
+            request: this.info.id,
+            ...(options.url !== undefined && { url: options.url }),
+            ...(options.method !== undefined && { method: options.method }),
+            ...(headers !== undefined && { headers: headersToBidi(headers) }),
+            ...(options.postData !== undefined && {
+                body: toBytes(options.postData),
+            }),
+        });
+    }
+    /** Makes the request fail (the browser reports a network error to the page) */
+    async abort() {
+        await this.answer("network.failRequest", { request: this.info.id });
+    }
+    /** Hands the request to the next route that matches it, or lets it continue when there is none */
+    async fallback() {
+        this.claim();
+        await this.deps.next();
+    }
+    claim() {
+        if (this.answered)
+            throw new Error("route already handled");
+        this.answered = true;
+        this.deps.settled();
+    }
+    async answer(method, params) {
+        this.claim();
+        await this.deps.send(method, params);
+    }
+}
+/**
+ * A request the browser holds, with what the router needs to see to it: the `Route` handed to the handler, the
+ * route entry that holds it, and the timer that lets it continue when the handler is too slow.
+ * Not part of the public API: handlers only ever see the `Route`.
+ */
+export class PendingRoute {
+    /** `entry` is the route that holds the request; none for one nobody asked for */
+    constructor(info, control, entry) {
+        this.info = info;
+        this.entry = entry;
+        this.answered = false;
+        this.route = new Route(info, {
+            send: control.send,
+            next: control.next,
+            sendsContentLength: control.sendsContentLength,
+            settled: () => {
+                this.answered = true;
+                clearTimeout(this.timer);
+                control.onSettled(this);
+            },
+        });
+    }
+    get isAnswered() {
+        return this.answered;
+    }
+    /** Calls `onLate` when nothing answered after `ms`; the timer never keeps the process alive */
+    startTimer(ms, onLate) {
+        this.timer = setTimeout(() => {
+            if (!this.answered)
+                onLate();
+        }, ms);
+        this.timer.unref?.();
+    }
+    /** Lets the request continue unchanged; failures are logged, not thrown */
+    async release() {
+        if (this.answered)
+            return;
+        try {
+            await this.route.continue();
+        }
+        catch (err) {
+            logger.debug("Could not let %s continue", this.info.url, { err });
+        }
+    }
+    /** Fails the request; failures are logged, not thrown */
+    async failQuietly() {
+        if (this.answered)
+            return;
+        try {
+            await this.route.abort();
+        }
+        catch (err) {
+            logger.debug("Could not fail %s", this.info.url, { err });
+        }
+    }
+}