@falkenslab/moodle-driver 0.4.1 → 0.5.1

package/dist/browser/background.js

@@ -0,0 +1,164 @@
+// Working on a browser another process keeps open (ADR-014): where to find it, from the file it leaves
+// in its profile, and a browser manager that connects to it instead of launching one.
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { request } from "node:http";
+import path from "node:path";
+import { chromium } from "playwright-core";
+import { MoodleError } from "../core/errors.js";
+import { followPages } from "../core/session.js";
+import { saveSessionCookies } from "./cookies.js";
+import { NoDisplayError } from "./manager.js";
+/** The file a background browser leaves in its profile: where it is and its token, readable only by the person. */
+export const BACKGROUND_FILE = ".browser.json";
+const NAVIGATION_TIMEOUT_MS = 60_000;
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: it's there, someone else's.
+        return error.code === "EPERM";
+    }
+};
+/** Asks the background browser how it is: `undefined` when nothing answers on its port. */
+function status(endpoint, token) {
+    const url = new URL("/status", endpoint.replace(/^ws/, "http"));
+    return new Promise((resolve, reject) => {
+        const req = request(url, { headers: { authorization: `Bearer ${token}` }, timeout: 5000 }, (response) => {
+            let body = "";
+            response.setEncoding("utf8");
+            response.on("data", (chunk) => (body += chunk));
+            response.on("end", () => (response.statusCode === 200 ? resolve(JSON.parse(body)) : resolve(undefined)));
+        });
+        req.on("timeout", () => req.destroy(new MoodleError("The background browser doesn't answer.", "background-browser")));
+        req.on("error", (error) => (error.code === "ECONNREFUSED" ? resolve(undefined) : reject(error)));
+        req.end();
+    });
+}
+/**
+ * The browser another process keeps open on `profileDir` (the `moodle open` command's), or `undefined`
+ * when there's none. A `.browser.json` left by a process that's gone is removed.
+ */
+export async function backgroundBrowser(profileDir) {
+    const file = path.join(profileDir, BACKGROUND_FILE);
+    let found;
+    try {
+        found = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof found.pid === "number" && alive(found.pid) && (await status(found.endpoint, found.token)))
+        return found;
+    rmSync(file, { force: true });
+    return undefined;
+}
+/**
+ * Asks the background browser on `profileDir` to save the session and close, and waits until it has;
+ * `false` when there's none.
+ */
+export async function closeBackgroundBrowser(profileDir, timeoutMs = 20_000) {
+    const found = await backgroundBrowser(profileDir);
+    if (!found)
+        return false;
+    await new Promise((resolve, reject) => {
+        const req = request(new URL("/close", found.endpoint.replace(/^ws/, "http")), { method: "POST", headers: { authorization: `Bearer ${found.token}` } }, (response) => {
+            response.resume();
+            response.on("end", resolve);
+        });
+        req.on("error", reject);
+        req.end();
+    });
+    const until = Date.now() + timeoutMs;
+    // The process removes its file once the browser is closed and the session saved.
+    const file = path.join(profileDir, BACKGROUND_FILE);
+    while (existsSync(file) && alive(found.pid) && Date.now() < until)
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    rmSync(file, { force: true });
+    return true;
+}
+/**
+ * A browser manager on a browser another process keeps open (`backgroundBrowser`), for a program to
+ * share it: it connects on first use, works in the browser's own context, and `close()` only
+ * disconnects, leaving the browser open. With a window, the pages functions open are followed in its
+ * first tab (ADR-007); it can't add or remove a window from a browser it didn't launch.
+ */
+export function connectBrowserManager(options) {
+    const headed = options.headed ?? false;
+    let browser;
+    let context;
+    let following = headed;
+    let connecting;
+    async function connect() {
+        if (context && browser?.isConnected())
+            return context;
+        connecting ??= (async () => {
+            try {
+                browser = await chromium.connectOverCDP(options.endpoint, { headers: { authorization: `Bearer ${options.token}` } });
+            }
+            catch (error) {
+                throw new MoodleError(`Can't connect to the browser at ${options.endpoint}: ${error.message.split("\n")[0]}`, "background-browser");
+            }
+            const opened = browser.contexts()[0];
+            if (!opened)
+                throw new MoodleError("The browser connected to has no context to work in.", "background-browser");
+            opened.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
+            followPages(opened, (url) => manager.show(url));
+            browser.on("disconnected", () => {
+                browser = undefined;
+                context = undefined;
+            });
+            context = opened;
+            return opened;
+        })().finally(() => (connecting = undefined));
+        return connecting;
+    }
+    /** The window's tab: the first one the browser has, else a new one. */
+    async function workTab(current) {
+        return current.pages().find((p) => !p.isClosed()) ?? (await current.newPage());
+    }
+    const manager = {
+        async context({ headed: wantHeaded = false } = {}) {
+            if (wantHeaded && !headed)
+                throw new NoDisplayError("The browser connected to was opened without a window, so it can't show one (to log in, say).");
+            return connect();
+        },
+        openChannel: () => (context ? options.channel : undefined),
+        chromiumDownload: () => undefined,
+        visible: () => headed && following,
+        async setVisible(visible) {
+            if (visible && !headed)
+                throw new NoDisplayError("The browser connected to was opened without a window: it can't show one now.");
+            following = visible;
+        },
+        async show(url) {
+            if (!following || !headed || !context)
+                return;
+            try {
+                const tab = await workTab(context);
+                if (tab.url() !== url)
+                    await tab.goto(url, { waitUntil: "domcontentloaded" });
+                await tab.bringToFront();
+            }
+            catch {
+                // Following is a courtesy: a page that doesn't load never changes a function's result.
+            }
+        },
+        tab: async () => workTab(await connect()),
+        async saveSession() {
+            if (context && options.profileDir)
+                await saveSessionCookies(context, options.profileDir);
+        },
+        async close() {
+            const current = browser;
+            await manager.saveSession().catch(() => undefined);
+            browser = undefined;
+            context = undefined;
+            // Disconnects: the browser and its window stay open for the next one.
+            await current?.close().catch(() => undefined);
+        },
+    };
+    return manager;
+}
+//# sourceMappingURL=background.js.map

package/dist/browser/background.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background.js","sourceRoot":"","sources":["../../src/browser/background.ts"],"names":[],"mappings":"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"}

package/dist/browser/host.d.ts

@@ -0,0 +1,30 @@
+import { type Channel } from "../options.js";
+export interface HostOptions {
+    /** The browser profile: the person's session (ADR-002). */
+    profileDir: string;
+    /** A window, or headless. */
+    headed?: boolean;
+    /** One browser only; else Edge, Chrome, then Chromium (downloaded if missing) as `createBrowserManager` tries them. */
+    channel?: Channel;
+}
+/** A browser hosted for other processes, and how to reach it. */
+export interface BrowserHost {
+    /** The WebSocket to connect to (`connectBrowserManager`), on 127.0.0.1. */
+    endpoint: string;
+    /** What a client sends as `Authorization: Bearer <token>`: nothing without it reaches the browser. */
+    token: string;
+    /** The browser's process. */
+    pid: number;
+    channel: Channel;
+    headed: boolean;
+    /** Settles once the browser is closed: asked to, or the person closed its window. */
+    closed: Promise<void>;
+    /** Saves the session cookies and closes the browser. */
+    close(): Promise<void>;
+}
+/**
+ * Launches a browser on `profileDir` and offers it to other processes (`connectBrowserManager`): one
+ * at a time, each with the token, on 127.0.0.1 only. Restores the session cookies (ADR-003) and saves
+ * them after every client and when it closes. Throws `NoDisplayError` for a window where there's no screen.
+ */
+export declare function hostBrowser(options: HostOptions): Promise<BrowserHost>;

package/dist/browser/host.js

@@ -0,0 +1,373 @@
+// A browser left open for other processes (ADR-014): launched with its debugging connection on a pipe
+// only this process holds, and offered to one client at a time through a WebSocket on 127.0.0.1 that
+// requires a random token. Chromium's own debugging port has no such check: anything on the machine
+// that reached it would drive the browser, logged in to Moodle as the person.
+import { spawn } from "node:child_process";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import path from "node:path";
+import { chromium } from "playwright-core";
+import { MoodleError } from "../core/errors.js";
+import { SYSTEM_CHANNELS } from "../options.js";
+import { installChromium } from "./chromium.js";
+import { SESSION_COOKIES_FILE } from "./cookies.js";
+import { BrowserNotFoundError, NoDisplayError, canShowWindow } from "./manager.js";
+// Playwright's message when a channel isn't installed (as in manager.ts).
+const NOT_INSTALLED = /distribution '[^']+' is not (found|supported)|Executable doesn't exist/i;
+// A CDP message as large as a full-page screenshot fits; anything larger is refused, not buffered.
+const MAX_MESSAGE = 256 * 1024 * 1024;
+const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+/**
+ * The executable and switches Playwright launches a channel with, from a browser server it starts and
+ * closes at once (with `--no-startup-window`, no window shows): the same switches as every other launch,
+ * without reaching into Playwright's internals.
+ */
+async function launchCommand(channel, headed) {
+    const server = await chromium.launchServer({ channel, headless: !headed });
+    try {
+        const process = server.process();
+        const args = process.spawnargs.slice(1).filter((arg) => arg.startsWith("-") && !/^--(user-data-dir|remote-debugging-pipe|remote-debugging-port|no-startup-window)\b/.test(arg));
+        return { executable: process.spawnfile, args };
+    }
+    finally {
+        await server.close();
+    }
+}
+async function findBrowser(options, headed) {
+    const channels = options.channel ? [options.channel] : [...SYSTEM_CHANNELS, "chromium"];
+    for (const channel of channels) {
+        try {
+            return { channel, ...(await launchCommand(channel, headed)) };
+        }
+        catch (error) {
+            if (!NOT_INSTALLED.test(error.message ?? ""))
+                throw error;
+            if (channel !== "chromium")
+                continue;
+            // Opening a browser to keep is worth waiting for the download (ADR-001).
+            await installChromium();
+            return { channel, ...(await launchCommand(channel, headed)) };
+        }
+    }
+    throw new BrowserNotFoundError(`No browser found (tried ${channels.join(", ")}).`);
+}
+/** Chrome's debugging protocol on the pipe it was given: JSON messages ending in a NUL byte. */
+class CdpPipe {
+    out;
+    chunks = [];
+    constructor(out, input, onMessage) {
+        this.out = out;
+        input.on("data", (data) => {
+            let start = 0;
+            for (let end = data.indexOf(0); end >= 0; end = data.indexOf(0, start)) {
+                this.chunks.push(data.subarray(start, end));
+                onMessage(Buffer.concat(this.chunks).toString("utf8"));
+                this.chunks = [];
+                start = end + 1;
+            }
+            if (start < data.length)
+                this.chunks.push(data.subarray(start));
+        });
+        input.on("error", () => undefined);
+        out.on("error", () => undefined);
+    }
+    send(text) {
+        this.out.write(`${text}\0`);
+    }
+}
+/** A WebSocket accepted on `socket` (RFC 6455, text messages, no extensions): just what CDP needs. */
+function acceptWebSocket(request, socket, head, onMessage, onClose) {
+    const key = request.headers["sec-websocket-key"];
+    const accept = createHash("sha1").update(`${key}${WS_GUID}`).digest("base64");
+    socket.setNoDelay(true);
+    socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
+    let buffer = head;
+    let fragments = [];
+    let fragmentsLength = 0;
+    let closed = false;
+    const frame = (opcode, payload) => {
+        if (closed || socket.destroyed)
+            return;
+        const length = payload.length;
+        const header = length < 126 ? Buffer.from([0x80 | opcode, length]) : length < 65536 ? Buffer.alloc(4) : Buffer.alloc(10);
+        if (length >= 126 && length < 65536) {
+            header[0] = 0x80 | opcode;
+            header[1] = 126;
+            header.writeUInt16BE(length, 2);
+        }
+        else if (length >= 65536) {
+            header[0] = 0x80 | opcode;
+            header[1] = 127;
+            header.writeBigUInt64BE(BigInt(length), 2);
+        }
+        socket.write(Buffer.concat([header, payload]));
+    };
+    const close = (code = 1000) => {
+        if (closed)
+            return;
+        const payload = Buffer.alloc(2);
+        payload.writeUInt16BE(code);
+        frame(0x8, payload);
+        closed = true;
+        socket.end();
+    };
+    const parse = () => {
+        while (buffer.length >= 2) {
+            const fin = (buffer[0] & 0x80) !== 0;
+            const opcode = buffer[0] & 0x0f;
+            // A client masks every frame (RFC 6455 5.1).
+            if ((buffer[1] & 0x80) === 0)
+                return close(1002);
+            let length = buffer[1] & 0x7f;
+            let offset = 2;
+            if (length === 126) {
+                if (buffer.length < 4)
+                    return;
+                length = buffer.readUInt16BE(2);
+                offset = 4;
+            }
+            else if (length === 127) {
+                if (buffer.length < 10)
+                    return;
+                const big = buffer.readBigUInt64BE(2);
+                if (big > BigInt(MAX_MESSAGE))
+                    return close(1009);
+                length = Number(big);
+                offset = 10;
+            }
+            if (length > MAX_MESSAGE || fragmentsLength + length > MAX_MESSAGE)
+                return close(1009);
+            if (buffer.length < offset + 4 + length)
+                return;
+            const mask = buffer.subarray(offset, offset + 4);
+            const payload = Buffer.from(buffer.subarray(offset + 4, offset + 4 + length));
+            for (let i = 0; i < payload.length; i++)
+                payload[i] ^= mask[i & 3];
+            buffer = buffer.subarray(offset + 4 + length);
+            if (opcode === 0x0 || opcode === 0x1 || opcode === 0x2) {
+                fragments.push(payload);
+                fragmentsLength += payload.length;
+                if (fin) {
+                    const message = Buffer.concat(fragments).toString("utf8");
+                    fragments = [];
+                    fragmentsLength = 0;
+                    onMessage(message);
+                }
+            }
+            else if (opcode === 0x8)
+                return close();
+            else if (opcode === 0x9)
+                frame(0xa, payload);
+            else if (opcode !== 0xa)
+                return close(1002);
+        }
+    };
+    socket.on("data", (data) => {
+        buffer = buffer.length > 0 ? Buffer.concat([buffer, data]) : data;
+        parse();
+    });
+    socket.on("close", onClose);
+    socket.on("error", () => socket.destroy());
+    if (buffer.length > 0)
+        parse();
+    return { send: (text) => frame(0x1, Buffer.from(text, "utf8")), close };
+}
+/** Whether the token in `Authorization: Bearer …` is `token`, compared in constant time. */
+function hasToken(request, token) {
+    const given = /^Bearer (\S+)$/.exec(request.headers.authorization ?? "")?.[1];
+    if (!given)
+        return false;
+    const a = Buffer.from(given);
+    const b = Buffer.from(token);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/**
+ * Launches a browser on `profileDir` and offers it to other processes (`connectBrowserManager`): one
+ * at a time, each with the token, on 127.0.0.1 only. Restores the session cookies (ADR-003) and saves
+ * them after every client and when it closes. Throws `NoDisplayError` for a window where there's no screen.
+ */
+export async function hostBrowser(options) {
+    const headed = options.headed ?? false;
+    if (headed && !canShowWindow())
+        throw new NoDisplayError("There's no screen to show a browser window here (no DISPLAY or WAYLAND_DISPLAY).");
+    const { channel, executable, args } = await findBrowser(options, headed);
+    // Chrome reads commands from fd 3 and writes to fd 4 (--remote-debugging-pipe); its own output is of no use here.
+    const child = spawn(executable, [...args, `--user-data-dir=${options.profileDir}`, "--remote-debugging-pipe", "about:blank"], {
+        stdio: ["ignore", "ignore", "ignore", "pipe", "pipe"],
+    });
+    const exited = new Promise((resolve) => child.once("exit", () => resolve()));
+    const killOnExit = () => child.kill();
+    process.on("exit", killOnExit);
+    const pending = new Map();
+    let nextId = 0;
+    let client;
+    // The sessions a client attached to targets: detached when it leaves, so the next one starts clean.
+    const sessions = new Set();
+    const pipe = new CdpPipe(child.stdio[3], child.stdio[4], (text) => {
+        let message;
+        try {
+            message = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        if (typeof message.id === "number") {
+            const waiting = pending.get(message.id);
+            pending.delete(message.id);
+            if (!waiting)
+                return;
+            if (waiting.own) {
+                if (message.error)
+                    waiting.reject(new MoodleError(message.error.message, "background-browser"));
+                else
+                    waiting.resolve(message.result);
+            }
+            else if (waiting.client === client)
+                client.send(JSON.stringify({ ...message, id: waiting.id }));
+            return;
+        }
+        if (message.method === "Target.attachedToTarget" && message.params?.sessionId)
+            sessions.add(message.params.sessionId);
+        if (message.method === "Target.detachedFromTarget" && message.params?.sessionId)
+            sessions.delete(message.params.sessionId);
+        client?.send(text);
+    });
+    const call = (method, params = {}) => new Promise((resolve, reject) => {
+        const id = ++nextId;
+        pending.set(id, { own: true, resolve: resolve, reject });
+        pipe.send(JSON.stringify({ id, method, params }));
+    });
+    const timeout = (promise, ms, what) => Promise.race([promise, new Promise((_, reject) => setTimeout(() => reject(new MoodleError(`The browser didn't ${what} in ${ms / 1000} s.`, "background-browser")), ms).unref())]);
+    async function saveCookies() {
+        const { cookies } = await call("Storage.getCookies");
+        const session = cookies.filter((c) => c.session).map((c) => ({ name: c.name, value: c.value, domain: c.domain, path: c.path, expires: -1, httpOnly: c.httpOnly, secure: c.secure, sameSite: c.sameSite ?? "Lax" }));
+        await writeFile(path.join(options.profileDir, SESSION_COOKIES_FILE), JSON.stringify(session), { mode: 0o600 });
+    }
+    async function restoreCookies() {
+        let saved;
+        try {
+            saved = JSON.parse(await readFile(path.join(options.profileDir, SESSION_COOKIES_FILE), "utf8"));
+        }
+        catch {
+            return;
+        }
+        if (!Array.isArray(saved) || saved.length === 0)
+            return;
+        // Cookies the browser kept itself are newer than the file's.
+        const { cookies } = await call("Storage.getCookies");
+        const kept = new Set(cookies.map((c) => `${c.name}|${c.domain}|${c.path}`));
+        const missing = saved.filter((c) => !kept.has(`${c.name}|${c.domain}|${c.path}`)).map((c) => ({ name: c.name, value: c.value, domain: c.domain, path: c.path, httpOnly: c.httpOnly, secure: c.secure, sameSite: c.sameSite }));
+        if (missing.length > 0)
+            await call("Storage.setCookies", { cookies: missing }).catch(() => undefined);
+    }
+    /** What a client left behind: its sessions attached, auto-attaching, its downloads folder. */
+    function cleanUp() {
+        for (const sessionId of sessions)
+            call("Target.detachFromTarget", { sessionId }).catch(() => undefined);
+        sessions.clear();
+        call("Target.setAutoAttach", { autoAttach: false, waitForDebuggerOnStart: false, flatten: true }).catch(() => undefined);
+        call("Target.setDiscoverTargets", { discover: false }).catch(() => undefined);
+        call("Browser.setDownloadBehavior", { behavior: "default" }).catch(() => undefined);
+        saveCookies().catch(() => undefined);
+    }
+    try {
+        await timeout(Promise.race([call("Browser.getVersion"), exited.then(() => Promise.reject(new MoodleError("The browser closed as it started: is another browser using this profile?", "background-browser")))]), 30_000, "start");
+        await restoreCookies();
+    }
+    catch (error) {
+        child.kill();
+        process.off("exit", killOnExit);
+        throw error;
+    }
+    const token = randomBytes(32).toString("base64url");
+    let closing;
+    const server = createServer();
+    // Only this machine, and only a client that isn't a web page: a page always sends Origin, and a
+    // name other than 127.0.0.1 in Host would be DNS rebinding.
+    const allowed = (request) => request.headers.origin === undefined && request.headers.host === host && hasToken(request, token);
+    server.on("request", (request, response) => {
+        if (!allowed(request))
+            return void response.writeHead(401).end();
+        if (request.method === "GET" && request.url === "/status") {
+            response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ pid: child.pid, channel, headed, busy: client !== undefined }));
+        }
+        else if (request.method === "POST" && request.url === "/close") {
+            response.writeHead(200).end();
+            void browserHost.close();
+        }
+        else
+            response.writeHead(404).end();
+    });
+    server.on("upgrade", (request, socket, head) => {
+        const refuse = (status) => socket.end(`HTTP/1.1 ${status}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+        if (!allowed(request))
+            return refuse("401 Unauthorized");
+        if (request.url !== "/devtools/browser" || request.headers.upgrade?.toLowerCase() !== "websocket" || !request.headers["sec-websocket-key"])
+            return refuse("400 Bad Request");
+        if (client || closing)
+            return refuse("409 Conflict");
+        const accepted = acceptWebSocket(request, socket, head, (text) => {
+            let message;
+            try {
+                message = JSON.parse(text);
+            }
+            catch {
+                return;
+            }
+            if (typeof message.id !== "number")
+                return;
+            // The browser outlives its clients: one closing it only disconnects (the host closes it, asked to).
+            if (message.method === "Browser.close") {
+                accepted.send(JSON.stringify({ id: message.id, result: {} }));
+                accepted.close();
+                return;
+            }
+            // Every client numbers its commands from 1: the browser sees ids of this process's own.
+            const id = ++nextId;
+            pending.set(id, { own: false, client: accepted, id: message.id });
+            pipe.send(JSON.stringify({ ...message, id }));
+        }, () => {
+            if (client !== accepted)
+                return;
+            client = undefined;
+            if (!closing)
+                cleanUp();
+        });
+        client = accepted;
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const port = server.address().port;
+    const host = `127.0.0.1:${port}`;
+    const closed = exited.then(() => {
+        process.off("exit", killOnExit);
+        client?.close(1001);
+        client = undefined;
+        for (const waiting of pending.values())
+            if (waiting.own)
+                waiting.reject(new MoodleError("The browser closed.", "background-browser"));
+        pending.clear();
+        server.close();
+        server.closeAllConnections();
+    });
+    const browserHost = {
+        endpoint: `ws://${host}/devtools/browser`,
+        token,
+        pid: child.pid,
+        channel,
+        headed,
+        closed,
+        close() {
+            closing ??= (async () => {
+                client?.close(1001);
+                await timeout(saveCookies(), 10_000, "give its cookies").catch(() => undefined);
+                await timeout(call("Browser.close"), 10_000, "close").catch(() => child.kill());
+                await timeout(exited, 10_000, "exit").catch(() => child.kill("SIGKILL"));
+                await closed;
+            })();
+            return closing;
+        },
+    };
+    return browserHost;
+}
+//# sourceMappingURL=host.js.map

package/dist/browser/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../../src/browser/host.ts"],"names":[],"mappings":"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"}

package/dist/browser/manager.d.ts

@@ -3,6 +3,7 @@ import { type InstallChromium } from "./chromium.js";
 import { type BrowserOptions, type Channel } from "../options.js";
 import { MoodleError } from "../core/errors.js";
 type LaunchPersistentContext = typeof chromium.launchPersistentContext;
+/** What `BrowserManager.context()` is asked for. */
 export interface ContextOptions {
     /** A visible window, whatever the options say (logging in by hand). */
     headed?: boolean;
@@ -53,5 +54,13 @@ export declare class NoDisplayError extends MoodleError {
  * server) the driver refuses rather than trying, so it never reaches a display it wasn't given.
  */
 export declare function canShowWindow(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/**
+ * A browser manager that launches the browser itself, in the persistent profile of `config`
+ * (ADR-002), on first use: nothing opens until a function needs the browser. It tries the
+ * installed browsers and, if allowed, downloads Chromium in the background (ADR-001). Its
+ * `context()` throws `BrowserNotFoundError` when no browser can be launched,
+ * `BrowserDownloadingError` while Chromium downloads, and `NoDisplayError` for a window without a
+ * screen. The other parameters are for tests.
+ */
 export declare function createBrowserManager(config: BrowserOptions, launch?: LaunchPersistentContext, install?: InstallChromium, windowsPossible?: () => boolean): BrowserManager;
 export {};

package/dist/browser/manager.js

@@ -38,6 +38,14 @@ export function canShowWindow(env = process.env, platform = process.platform) {
 const NOT_INSTALLED = /distribution '[^']+' is not (found|supported)|Executable doesn't exist/i;
 // Moodle pages can take long, above all the first ones after the site starts.
 const NAVIGATION_TIMEOUT_MS = 60_000;
+/**
+ * A browser manager that launches the browser itself, in the persistent profile of `config`
+ * (ADR-002), on first use: nothing opens until a function needs the browser. It tries the
+ * installed browsers and, if allowed, downloads Chromium in the background (ADR-001). Its
+ * `context()` throws `BrowserNotFoundError` when no browser can be launched,
+ * `BrowserDownloadingError` while Chromium downloads, and `NoDisplayError` for a window without a
+ * screen. The other parameters are for tests.
+ */
 export function createBrowserManager(config, launch = chromium.launchPersistentContext.bind(chromium), install = installChromium, windowsPossible = canShowWindow) {
     let open;
     // What `setVisible` asked for, over the options; following goes with it.