@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/src/browser/browser-context.ts

@@ -1,208 +0,0 @@
-import type { BiDiConnector } from "../transport/bidi-connection.js";
-import { BiDiError } from "../transport/bidi-error.js";
-import type { Cookie as BiDiCookie, SameSite } from "../types/bidi-modules/network.js";
-import type { PartialCookie, PartitionDescriptor } from "../types/bidi-modules/storage.js";
-import { applyEmulation, type EmulationOptions } from "./emulation.js";
-import type Page from "./page.js";
-
-export type { SameSite } from "../types/bidi-modules/network.js";
-
-/** A cookie as `context.cookies()` returns it */
-export interface Cookie {
-  name: string;
-  value: string;
-  domain: string;
-  path: string;
-  httpOnly: boolean;
-  secure: boolean;
-  sameSite: SameSite;
-  /** Seconds since the epoch; absent for a session cookie */
-  expiry?: number;
-}
-
-/** A cookie to add: `domain`, or a `url` to take domain, path and `secure` from */
-export interface CookieInput {
-  name: string;
-  value: string;
-  domain?: string;
-  /** @default "/", or the path of `url` */
-  path?: string;
-  url?: string;
-  httpOnly?: boolean;
-  secure?: boolean;
-  sameSite?: SameSite;
-  /** Seconds since the epoch */
-  expiry?: number;
-}
-
-export interface CookieFilter {
-  name?: string;
-  domain?: string;
-  path?: string;
-}
-
-/** What a context needs from its browser */
-export interface ContextHost {
-  connector: BiDiConnector;
-  newPage(options: { type: "tab"; userContext?: string }): Promise<Page>;
-  /** Called when a context has been closed */
-  forget(context: BrowserContext): void;
-}
-
-/**
- * An isolated browsing session inside one browser: its own cookies, storage and cache. Pages opened in it
- * share them; pages of other contexts see none of it.
- */
-export class BrowserContext {
-  private opened: Page[] = [];
-  private isClosed = false;
-
-  constructor(
-    private host: ContextHost,
-    /** The BiDi user context id; "default" for the browser's own */
-    public readonly id: string,
-    public readonly isDefault: boolean,
-  ) {}
-
-  /** True once `close()` has run */
-  public get closed(): boolean {
-    return this.isClosed;
-  }
-
-  /** Opens a tab in this context */
-  public async newPage(): Promise<Page> {
-    this.assertOpen();
-    return this.host.newPage({ type: "tab", ...(!this.isDefault && { userContext: this.id }) });
-  }
-
-  /** The pages opened in this context that are still open */
-  public pages(): Page[] {
-    this.opened = this.opened.filter((page) => !page.closed);
-    return [...this.opened];
-  }
-
-  /** @internal Called when a page is opened in this context */
-  public register(page: Page): void {
-    this.opened.push(page);
-    page.setContext(this);
-  }
-
-  /** Adds cookies to this context's storage. Every cookie is checked before any is stored */
-  public async addCookies(cookies: CookieInput[]): Promise<void> {
-    this.assertOpen();
-    const prepared = cookies.map(toBiDiCookie);
-    for (const cookie of prepared) {
-      await this.host.connector.send("storage.setCookie", { cookie, partition: this.partition() });
-    }
-  }
-
-  /** The cookies of this context, optionally only those matching `filter` */
-  public async cookies(filter?: CookieFilter): Promise<Cookie[]> {
-    this.assertOpen();
-    const { cookies } = await this.host.connector.send("storage.getCookies", {
-      ...(filter && { filter }),
-      partition: this.partition(),
-    });
-    return cookies.map(toCookie);
-  }
-
-  /** Deletes all cookies of this context, or those matching `filter` */
-  public async clearCookies(filter?: CookieFilter): Promise<void> {
-    this.assertOpen();
-    await this.host.connector.send("storage.deleteCookies", {
-      ...(filter && { filter }),
-      partition: this.partition(),
-    });
-  }
-
-  /**
-   * Pretends things about every page of this context, including pages opened later: locale, timezone, user agent,
-   * geolocation, offline, orientation, screen size. A page's own `emulate()` wins over the context's.
-   * @example
-   *  await context.emulate({ locale: "nl-NL", timezone: "Europe/Amsterdam", offline: false });
-   */
-  public async emulate(options: EmulationOptions): Promise<void> {
-    this.assertOpen();
-    await applyEmulation(this.host.connector, { userContexts: [this.id] }, options);
-  }
-
-  /**
-   * Grants, denies or resets a browser permission ("geolocation", "notifications", "camera", …) for `origin`
-   * in this context. Geolocation emulation only answers once the permission is granted.
-   */
-  public async setPermission(
-    name: string,
-    state: "granted" | "denied" | "prompt",
-    origin: string,
-  ): Promise<void> {
-    this.assertOpen();
-    await this.host.connector.send("permissions.setPermission", {
-      descriptor: { name },
-      state,
-      origin,
-      ...(!this.isDefault && { userContext: this.id }),
-    });
-  }
-
-  /** Removes the context; the browser closes its pages. The default context cannot be closed */
-  public async close(): Promise<void> {
-    if (this.isDefault) throw new Error("cannot close the default context");
-    if (this.isClosed) return;
-    try {
-      await this.host.connector.send("browser.removeUserContext", { userContext: this.id });
-    } catch (err) {
-      // Already gone: the goal is met
-      if (!(err instanceof BiDiError && err.code === "no such user context")) throw err;
-    }
-    this.isClosed = true;
-    const pages = this.opened;
-    this.opened = [];
-    await Promise.all(pages.map((page) => page.detach()));
-    this.host.forget(this);
-  }
-
-  private partition(): PartitionDescriptor {
-    return { type: "storageKey", userContext: this.id };
-  }
-
-  private assertOpen() {
-    if (this.isClosed) throw new Error("context closed");
-  }
-}
-
-function toBiDiCookie(input: CookieInput): PartialCookie {
-  let { domain, path, secure } = input;
-  if (input.url !== undefined) {
-    const url = new URL(input.url);
-    domain ??= url.hostname;
-    path ??= url.pathname;
-    secure ??= url.protocol === "https:";
-  }
-  if (domain === undefined) throw new TypeError(`cookie "${input.name}" needs a domain or a url`);
-  return {
-    name: input.name,
-    value: { type: "string", value: input.value },
-    domain,
-    path: path ?? "/",
-    ...(secure !== undefined && { secure }),
-    ...(input.httpOnly !== undefined && { httpOnly: input.httpOnly }),
-    ...(input.sameSite !== undefined && { sameSite: input.sameSite }),
-    ...(input.expiry !== undefined && { expiry: input.expiry }),
-  };
-}
-
-function toCookie(cookie: BiDiCookie): Cookie {
-  return {
-    name: cookie.name,
-    value:
-      cookie.value.type === "base64"
-        ? Buffer.from(cookie.value.value, "base64").toString("utf8")
-        : cookie.value.value,
-    domain: cookie.domain,
-    path: cookie.path,
-    httpOnly: cookie.httpOnly,
-    secure: cookie.secure,
-    sameSite: cookie.sameSite,
-    ...(cookie.expiry !== undefined && { expiry: cookie.expiry }),
-  };
-}

package/src/browser/browser-finder.ts

@@ -1,110 +0,0 @@
-import assert from "node:assert";
-import { execSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import type { SupportedBrowser } from "../types/browser.js";
-import logger from "../logger/index.js";
-
-const supportedBrowsers: SupportedBrowser[] = ["firefox"];
-const macBrowserPaths: Record<SupportedBrowser, string> = {
-  // chrome: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-  firefox: "/Applications/Firefox.app/Contents/MacOS/Firefox",
-};
-
-export function findBrowser(browserName: SupportedBrowser) {
-  logger.verbose("Checking install location for %s", browserName);
-  if (!supportedBrowsers.includes(browserName)) {
-    throw new Error(
-      "This browser is not supported. Supported browsers include: " +
-        supportedBrowsers.join(", "),
-    );
-  }
-
-  let browserLocation = "";
-  const notFoundMsg = `Cannot find browser ${browserName} on this machine! Is it installed?`;
-  try {
-    browserLocation = tryFindBrowser(browserName);
-  } catch (err) {
-    throw new Error(notFoundMsg);
-  }
-
-  assert(browserLocation, notFoundMsg);
-  logger.verbose("Browser found at: %s", browserLocation);
-
-  return browserLocation;
-}
-
-function tryFindBrowser(browserName: SupportedBrowser): string {
-  logger.debug("Current platform: %s", process.platform);
-  switch (process.platform) {
-    case "win32":
-      return findBrowserWindows(browserName);
-    case "darwin":
-      return findBrowserMac(browserName);
-    case "linux":
-      return findBrowserLinux(browserName);
-    default:
-      throw new Error("This platform is not supported");
-  }
-}
-
-function findBrowserWindows(browserName: SupportedBrowser): string {
-  // Function to prevent search the entire file system
-  // We'll only try the most common paths
-  const possibleDirs = ["Program\ Files", "Program\ Files (x86)"];
-
-  const where = (dirPath: string) => {
-    const command: string = `where /r ${dirPath} ${browserName}.exe`;
-    try {
-      logger.verbose("Running command: %s", command);
-
-      const whereResults = execSync(command, {
-        encoding: "utf8",
-      });
-      logger.debug("Command results: \n", whereResults);
-      const results = whereResults.split(/\n/g);
-      return results[0];
-    } catch (error) {
-      logger.verbose("Error while executing %s", command, { error });
-    }
-  };
-
-  let result = undefined;
-
-  for (const possibleDir of possibleDirs) {
-    logger.debug("Checking directory: %s", possibleDir);
-    result = where(possibleDir);
-    if (result) break;
-  }
-
-  if (!result) {
-    throw new Error("'where' yielded no results");
-  }
-  return result;
-}
-
-function findBrowserMac(browserName: SupportedBrowser): string {
-  const checkPathExists = (path: string) => {
-    logger.debug("Checking path: %s", path);
-    const exists = existsSync(path);
-    if (!exists) {
-      throw new Error(`Did not find ${browserName} at ${path}`);
-    }
-    return path;
-  };
-  return checkPathExists(macBrowserPaths[browserName]);
-}
-
-const linuxBinaryNames: Record<SupportedBrowser, string> = {
-  // chrome: "google-chrome",
-  firefox: "firefox",
-};
-
-function findBrowserLinux(browserName: SupportedBrowser): string {
-  const command = `which ${linuxBinaryNames[browserName]}`;
-  logger.debug("Running command: %s", command);
-  const result = execSync(command, {
-    encoding: "utf8",
-    stdio: "pipe",
-  });
-  return result.replace(/\n/g, "");
-}

package/src/browser/browser.test.ts

@@ -1,88 +0,0 @@
-import assert from "node:assert/strict";
-import { test } from "node:test";
-import { autoReply, FakeWebSocket } from "../testing/fake-websocket.js";
-import { BiDiConnector } from "../transport/bidi-connection.js";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import path from "node:path";
-import { abandonLaunch, Browser, browserLaunchFlag, ensureBrowserProfile } from "./browser.js";
-
-function fakeBrowser(handlers: Record<string, (params: any) => object | Error> = {}) {
-  const ws = new FakeWebSocket();
-  const connector = new BiDiConnector(ws as unknown as WebSocket);
-  const stop = autoReply(ws, { "browsingContext.getTree": () => ({ contexts: [] }), ...handlers });
-  const browser = new Browser({ browserProc: {} as never, biDiConnector: connector });
-  return { ws, browser, stop };
-}
-
-test("newPage returns a page bound to the created context", async () => {
-  const { ws, browser, stop } = fakeBrowser({
-    "browsingContext.create": () => ({ context: "ctx-42", userContext: "default" }),
-  });
-  const page = await browser.newPage({ type: "tab" });
-  assert.equal(page.contextId, "ctx-42");
-  assert.deepEqual(
-    ws.sent.find((m) => m.method === "browsingContext.create")!.params,
-    { type: "tab" },
-  );
-  stop();
-});
-
-test("newPage passes background and userContext through", async () => {
-  const { ws, browser, stop } = fakeBrowser({
-    "browsingContext.create": () => ({ context: "c", userContext: "u1" }),
-  });
-  await browser.newPage({ type: "window", background: true, userContext: "u1" });
-  assert.deepEqual(ws.sent[0]!.params, { type: "window", background: true, userContext: "u1" });
-  stop();
-});
-
-test("newPage surfaces a failing create as a BiDiError", async () => {
-  const { browser, stop } = fakeBrowser({
-    "browsingContext.create": () => new Error("no window"),
-  });
-  await assert.rejects(browser.newPage({ type: "tab" }), { name: "BiDiError", code: "unknown error" });
-  stop();
-});
-
-test("firefox starts on about:blank, not its privileged home page", () => {
-  assert.deepEqual(browserLaunchFlag("firefox", { port: 9300, profileDir: "/tmp/profile", headless: true }), [
-    "--no-sandbox",
-    "--no-remote",
-    "--headless",
-    "--remote-debugging-port=9300",
-    "--profile",
-    "/tmp/profile",
-    "about:blank",
-  ]);
-});
-
-test("a failed launch stops the connection and the browser it started", () => {
-  const calls: string[] = [];
-  abandonLaunch({ kill: () => calls.push("browser") > 0 }, { kill: () => void calls.push("connector") });
-  assert.deepEqual(calls, ["connector", "browser"]);
-});
-
-test("a launch that failed before connecting still stops the browser", () => {
-  const calls: string[] = [];
-  abandonLaunch({ kill: () => calls.push("browser") > 0 }, undefined);
-  assert.deepEqual(calls, ["browser"]);
-});
-
-test("the firefox profile is written with a blank start page, and an outdated one is rewritten", () => {
-  const dir = mkdtempSync(path.join(tmpdir(), "samurai-profile-"));
-  try {
-    const userJs = path.join(dir, "firefox", "user.js");
-    ensureBrowserProfile("firefox", userJs);
-    const written = readFileSync(userJs, "utf8");
-    assert.match(written, /user_pref\("browser\.startup\.page", 0\);/);
-    assert.match(written, /user_pref\("browser\.startup\.homepage", "about:blank"\);/);
-    assert.match(written, /user_pref\("browser\.newtabpage\.enabled", false\);/);
-
-    writeFileSync(userJs, 'user_pref("devtools.chrome.enabled", true);');
-    ensureBrowserProfile("firefox", userJs);
-    assert.equal(readFileSync(userJs, "utf8"), written);
-  } finally {
-    rmSync(dir, { recursive: true, force: true });
-  }
-});