@falkenslab/moodle-driver 0.0.0-stage → 0.4.0

package/dist/browser/manager.js

@@ -0,0 +1,177 @@
+import { mkdir } from "node:fs/promises";
+import { chromium } from "playwright-core";
+import { installChromium } from "./chromium.js";
+import { SYSTEM_CHANNELS } from "../options.js";
+import { followPages } from "../core/session.js";
+import { restoreSessionCookies, saveSessionCookies } from "./cookies.js";
+import { MoodleError } from "../core/errors.js";
+/** No installed browser could be launched, and Chromium can't be downloaded (ADR-001). */
+export class BrowserNotFoundError extends MoodleError {
+    name = "BrowserNotFoundError";
+    constructor(message) {
+        super(message, "browser-not-found");
+    }
+}
+/** No browser yet: Chromium is downloading in the background, and the call should be retried later. */
+export class BrowserDownloadingError extends MoodleError {
+    name = "BrowserDownloadingError";
+    constructor(message) {
+        super(message, "browser-downloading");
+    }
+}
+/** A window was asked for where there's no screen to show it (a container, a server). */
+export class NoDisplayError extends MoodleError {
+    name = "NoDisplayError";
+    constructor(message) {
+        super(message, "no-display");
+    }
+}
+/**
+ * Whether a window can be shown. On Linux it needs an X or Wayland display; without one (Docker, a
+ * server) the driver refuses rather than trying, so it never reaches a display it wasn't given.
+ */
+export function canShowWindow(env = process.env, platform = process.platform) {
+    return platform !== "linux" || Boolean(env.DISPLAY || env.WAYLAND_DISPLAY);
+}
+// Playwright's message when a channel isn't installed: "Chromium distribution 'msedge' is not found",
+// with " at <path>" only when it knows where to look (playwright-core 1.64).
+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;
+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.
+    let shown;
+    let followTab;
+    // The download runs in the background, outside the queue: it takes minutes, longer than some
+    // callers wait, so calls meanwhile answer at once that it's downloading.
+    let download;
+    let downloadFailure;
+    function startDownload() {
+        const retry = downloadFailure ? ` The previous download failed (${downloadFailure}); trying again.` : "";
+        downloadFailure = undefined;
+        download ??= install().then(() => {
+            download = undefined;
+        }, (error) => {
+            download = undefined;
+            downloadFailure = error.message ?? String(error);
+        });
+        return downloading(retry);
+    }
+    function downloading(extra = "") {
+        return new BrowserDownloadingError(`${config.channel === "chromium" ? "Chromium isn't downloaded yet" : "Neither Microsoft Edge nor Google Chrome is available"}, so it's being downloaded (about 180 MB, into PLAYWRIGHT_BROWSERS_PATH or the user's ms-playwright cache).${extra} Try again in a minute or two.`);
+    }
+    // One operation at a time: two launches on the same profile would fail.
+    let queue = Promise.resolve();
+    function exclusive(operation) {
+        const result = queue.then(operation, operation);
+        queue = result.catch(() => undefined);
+        return result;
+    }
+    async function launchFirstAvailable(headed) {
+        await mkdir(config.profileDir, { recursive: true });
+        const channels = config.channel ? [config.channel] : [...SYSTEM_CHANNELS, ...(config.downloadBrowser ? ["chromium"] : [])];
+        const missing = [];
+        for (const channel of channels) {
+            if (channel === "chromium" && download)
+                throw downloading();
+            let context;
+            try {
+                // A window keeps its own size; a fixed viewport would leave it half empty.
+                context = await launch(config.profileDir, { channel, headless: !headed, ...(headed ? { viewport: null } : {}) });
+            }
+            catch (error) {
+                const message = error.message ?? String(error);
+                if (!NOT_INSTALLED.test(message))
+                    throw error;
+                if (channel === "chromium" && config.downloadBrowser)
+                    throw startDownload();
+                missing.push(channel);
+                continue;
+            }
+            context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
+            followPages(context, (url) => manager.show(url));
+            await restoreSessionCookies(context, config.profileDir);
+            const opened = { context, channel, headed };
+            // The person may close the window: the next call opens the browser again, headless if they had
+            // asked to see it (closing it says they're done watching).
+            context.on("close", () => {
+                if (open !== opened)
+                    return;
+                open = undefined;
+                if (opened.headed && shown)
+                    shown = false;
+            });
+            return opened;
+        }
+        throw new BrowserNotFoundError(`No browser found (tried ${missing.join(", ")}). Install Microsoft Edge or Google Chrome${config.downloadBrowser ? "" : ", or allow downloading Chromium (downloadBrowser)"}, or choose another channel.`);
+    }
+    /** The working tab in `context`: the one already in use, else the window's first empty tab, else a new one. */
+    async function workTab(context) {
+        if (!followTab || followTab.isClosed())
+            followTab = context.pages().find((p) => p.url() === "about:blank") ?? (await context.newPage());
+        return followTab;
+    }
+    async function closeOpen() {
+        const current = open;
+        open = undefined;
+        followTab = undefined;
+        if (!current)
+            return;
+        await saveSessionCookies(current.context, config.profileDir).catch(() => undefined);
+        await current.context.close().catch(() => undefined);
+    }
+    const manager = {
+        context({ headed = false } = {}) {
+            return exclusive(async () => {
+                const wantHeaded = headed || (shown ?? !config.headless);
+                if (open && (open.headed || !wantHeaded))
+                    return open.context;
+                if (wantHeaded && !windowsPossible()) {
+                    throw new NoDisplayError(`There's no screen to show a browser window here (no DISPLAY or WAYLAND_DISPLAY), so ${headed ? "logging in by hand isn't possible" : "a headed browser can't open"}. Run headless with a profile already logged in, or where there's a screen.`);
+                }
+                await closeOpen();
+                open = await launchFirstAvailable(wantHeaded);
+                return open.context;
+            });
+        },
+        visible: () => shown ?? !config.headless,
+        setVisible: (visible) => exclusive(async () => {
+            if (visible && !windowsPossible()) {
+                throw new NoDisplayError("There's no screen to show a browser window here (no DISPLAY or WAYLAND_DISPLAY). The browser keeps working headless.");
+            }
+            shown = visible;
+            if (visible && !open?.headed) {
+                await closeOpen();
+                open = await launchFirstAvailable(true);
+            }
+            else if (!visible && open?.headed) {
+                await closeOpen();
+            }
+        }),
+        async show(url) {
+            const current = open;
+            if (!shown || !current?.headed)
+                return;
+            try {
+                const tab = await workTab(current.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 manager.context()),
+        openChannel: () => open?.channel,
+        chromiumDownload: () => (download ? "downloading" : downloadFailure ? "failed" : undefined),
+        saveSession: () => exclusive(async () => {
+            if (open)
+                await saveSessionCookies(open.context, config.profileDir);
+        }),
+        close: () => exclusive(closeOpen),
+    };
+    return manager;
+}
+//# sourceMappingURL=manager.js.map

package/dist/browser/manager.js.map

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

package/dist/browser.d.ts

@@ -0,0 +1,53 @@
+import { chromium, type BrowserContext, type Page } from "playwright-core";
+import { type InstallChromium } from "./chromiumInstaller.js";
+import { type BrowserOptions, type Channel } from "./options.js";
+type LaunchPersistentContext = typeof chromium.launchPersistentContext;
+export interface ContextOptions {
+    /** A visible window, whatever the options say (logging in by hand). */
+    headed?: boolean;
+}
+/** The browser's single persistent context, opened on first use (ADR-002). */
+export interface BrowserManager {
+    /**
+     * The open context, launching it if needed. A headed request relaunches a headless context with
+     * a window; a headless request reuses a headed one rather than closing a window the person may be using.
+     */
+    context(options?: ContextOptions): Promise<BrowserContext>;
+    /** The channel of the open context, or `undefined` while none is open. */
+    openChannel(): Channel | undefined;
+    /** Whether Chromium is being downloaded, or the last download failed (ADR-001). */
+    chromiumDownload(): "downloading" | "failed" | undefined;
+    /** Whether the browser shows a window now: what `setVisible` asked for, else the options. */
+    visible(): boolean;
+    /**
+     * Shows the browser (relaunching it with a window now, session kept) and follows the pages functions open
+     * in it, or hides it (closing the window; the next call runs headless). ADR-007.
+     */
+    setVisible(visible: boolean): Promise<void>;
+    /** While following, brings `url` (a site page) to the front of the window; best effort, never throws. */
+    show(url: string): Promise<void>;
+    /** The one working tab a program drives itself (ADR-007), the same one following shows; opens the browser if needed. */
+    tab(): Promise<Page>;
+    /** Saves the session cookies of the open context, if any (ADR-003). */
+    saveSession(): Promise<void>;
+    close(): Promise<void>;
+}
+/** No installed browser could be launched, and Chromium can't be downloaded (ADR-001). */
+export declare class BrowserNotFoundError extends Error {
+    name: string;
+}
+/** No browser yet: Chromium is downloading in the background, and the call should be retried later. */
+export declare class BrowserDownloadingError extends Error {
+    name: string;
+}
+/** A window was asked for where there's no screen to show it (a container, a server). */
+export declare class NoDisplayError extends Error {
+    name: string;
+}
+/**
+ * Whether a window can be shown. On Linux it needs an X or Wayland display; without one (Docker, a
+ * 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;
+export declare function createBrowserManager(config: BrowserOptions, launch?: LaunchPersistentContext, install?: InstallChromium, windowsPossible?: () => boolean): BrowserManager;
+export {};

package/dist/browser.js

@@ -0,0 +1,167 @@
+import { mkdir } from "node:fs/promises";
+import { chromium } from "playwright-core";
+import { installChromium } from "./chromiumInstaller.js";
+import { SYSTEM_CHANNELS } from "./options.js";
+import { followPages } from "./moodle/session.js";
+import { restoreSessionCookies, saveSessionCookies } from "./sessionCookies.js";
+/** No installed browser could be launched, and Chromium can't be downloaded (ADR-001). */
+export class BrowserNotFoundError extends Error {
+    name = "BrowserNotFoundError";
+}
+/** No browser yet: Chromium is downloading in the background, and the call should be retried later. */
+export class BrowserDownloadingError extends Error {
+    name = "BrowserDownloadingError";
+}
+/** A window was asked for where there's no screen to show it (a container, a server). */
+export class NoDisplayError extends Error {
+    name = "NoDisplayError";
+}
+/**
+ * Whether a window can be shown. On Linux it needs an X or Wayland display; without one (Docker, a
+ * server) the driver refuses rather than trying, so it never reaches a display it wasn't given.
+ */
+export function canShowWindow(env = process.env, platform = process.platform) {
+    return platform !== "linux" || Boolean(env.DISPLAY || env.WAYLAND_DISPLAY);
+}
+// Playwright's message when a channel isn't installed: "Chromium distribution 'msedge' is not found",
+// with " at <path>" only when it knows where to look (playwright-core 1.64).
+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;
+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.
+    let shown;
+    let followTab;
+    // The download runs in the background, outside the queue: it takes minutes, longer than some
+    // callers wait, so calls meanwhile answer at once that it's downloading.
+    let download;
+    let downloadFailure;
+    function startDownload() {
+        const retry = downloadFailure ? ` The previous download failed (${downloadFailure}); trying again.` : "";
+        downloadFailure = undefined;
+        download ??= install().then(() => {
+            download = undefined;
+        }, (error) => {
+            download = undefined;
+            downloadFailure = error.message ?? String(error);
+        });
+        return downloading(retry);
+    }
+    function downloading(extra = "") {
+        return new BrowserDownloadingError(`${config.channel === "chromium" ? "Chromium isn't downloaded yet" : "Neither Microsoft Edge nor Google Chrome is available"}, so it's being downloaded (about 180 MB, into PLAYWRIGHT_BROWSERS_PATH or the user's ms-playwright cache).${extra} Try again in a minute or two.`);
+    }
+    // One operation at a time: two launches on the same profile would fail.
+    let queue = Promise.resolve();
+    function exclusive(operation) {
+        const result = queue.then(operation, operation);
+        queue = result.catch(() => undefined);
+        return result;
+    }
+    async function launchFirstAvailable(headed) {
+        await mkdir(config.profileDir, { recursive: true });
+        const channels = config.channel ? [config.channel] : [...SYSTEM_CHANNELS, ...(config.downloadBrowser ? ["chromium"] : [])];
+        const missing = [];
+        for (const channel of channels) {
+            if (channel === "chromium" && download)
+                throw downloading();
+            let context;
+            try {
+                // A window keeps its own size; a fixed viewport would leave it half empty.
+                context = await launch(config.profileDir, { channel, headless: !headed, ...(headed ? { viewport: null } : {}) });
+            }
+            catch (error) {
+                const message = error.message ?? String(error);
+                if (!NOT_INSTALLED.test(message))
+                    throw error;
+                if (channel === "chromium" && config.downloadBrowser)
+                    throw startDownload();
+                missing.push(channel);
+                continue;
+            }
+            context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
+            followPages(context, (url) => manager.show(url));
+            await restoreSessionCookies(context, config.profileDir);
+            const opened = { context, channel, headed };
+            // The person may close the window: the next call opens the browser again, headless if they had
+            // asked to see it (closing it says they're done watching).
+            context.on("close", () => {
+                if (open !== opened)
+                    return;
+                open = undefined;
+                if (opened.headed && shown)
+                    shown = false;
+            });
+            return opened;
+        }
+        throw new BrowserNotFoundError(`No browser found (tried ${missing.join(", ")}). Install Microsoft Edge or Google Chrome${config.downloadBrowser ? "" : ", or allow downloading Chromium (downloadBrowser)"}, or choose another channel.`);
+    }
+    /** The working tab in `context`: the one already in use, else the window's first empty tab, else a new one. */
+    async function workTab(context) {
+        if (!followTab || followTab.isClosed())
+            followTab = context.pages().find((p) => p.url() === "about:blank") ?? (await context.newPage());
+        return followTab;
+    }
+    async function closeOpen() {
+        const current = open;
+        open = undefined;
+        followTab = undefined;
+        if (!current)
+            return;
+        await saveSessionCookies(current.context, config.profileDir).catch(() => undefined);
+        await current.context.close().catch(() => undefined);
+    }
+    const manager = {
+        context({ headed = false } = {}) {
+            return exclusive(async () => {
+                const wantHeaded = headed || (shown ?? !config.headless);
+                if (open && (open.headed || !wantHeaded))
+                    return open.context;
+                if (wantHeaded && !windowsPossible()) {
+                    throw new NoDisplayError(`There's no screen to show a browser window here (no DISPLAY or WAYLAND_DISPLAY), so ${headed ? "logging in by hand isn't possible" : "a headed browser can't open"}. Run headless with a profile already logged in, or where there's a screen.`);
+                }
+                await closeOpen();
+                open = await launchFirstAvailable(wantHeaded);
+                return open.context;
+            });
+        },
+        visible: () => shown ?? !config.headless,
+        setVisible: (visible) => exclusive(async () => {
+            if (visible && !windowsPossible()) {
+                throw new NoDisplayError("There's no screen to show a browser window here (no DISPLAY or WAYLAND_DISPLAY). The browser keeps working headless.");
+            }
+            shown = visible;
+            if (visible && !open?.headed) {
+                await closeOpen();
+                open = await launchFirstAvailable(true);
+            }
+            else if (!visible && open?.headed) {
+                await closeOpen();
+            }
+        }),
+        async show(url) {
+            const current = open;
+            if (!shown || !current?.headed)
+                return;
+            try {
+                const tab = await workTab(current.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 manager.context()),
+        openChannel: () => open?.channel,
+        chromiumDownload: () => (download ? "downloading" : downloadFailure ? "failed" : undefined),
+        saveSession: () => exclusive(async () => {
+            if (open)
+                await saveSessionCookies(open.context, config.profileDir);
+        }),
+        close: () => exclusive(closeOpen),
+    };
+    return manager;
+}
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

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

package/dist/categories.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A kind of data a function reads or writes:
+ * - `none`: the session or the site, nothing of anyone's; also functions that only parse what the
+ *   caller already fetched (a page, HTML, JSON), whose data belongs to whatever fetched it.
+ * - `own`: the person's own data and actions (their courses, attempts, submissions, grades).
+ * - `course-content`: what teachers make (structure, activities' content and settings, rubrics' definitions, questions).
+ * - `others-aggregate`: counts about others that identify no one ("2 of 4 submitted").
+ * - `others-personal`: others' data or work (names, roles, submissions, posts, attempts, responses, grades).
+ * - `others-write`: deciding about others (grades, feedback, extensions, overrides, completion).
+ * - `communication`: writing to or before others (forum posts, messages).
+ * - `any`: generic primitives that reach whatever they're pointed at (services, pages, forms).
+ */
+export declare const ALL_DATA_CATEGORIES: readonly ["none", "own", "course-content", "others-aggregate", "others-personal", "others-write", "communication", "any"];
+export type DataCategory = (typeof ALL_DATA_CATEGORIES)[number];
+/**
+ * The data categories of every function exported from the package, and of the browser manager's
+ * methods (`BrowserManager.<method>`) and the Moodle object's own (`Moodle.<method>`; its other methods are
+ * the functions of the same name). A function that may touch several kinds lists them all; a
+ * program takes the strictest. Functions that read activities of any module answer per module
+ * through `moduleCategories()`.
+ */
+export declare const DATA_CATEGORIES: Readonly<Record<string, readonly DataCategory[]>>;
+/**
+ * The data a teacher reads when reading an activity of `module` with everything in it: course
+ * content alone for what teachers make (pages, books, files…), also others' personal data where
+ * participants leave work or responses. An unknown module (a plugin) could hold anything: `any`.
+ */
+export declare function moduleCategories(module: string): readonly DataCategory[];