effect-browser 0.2.0-beta.9 → 0.3.0-beta.11

package/src/internal/page/navigation.ts

@@ -0,0 +1,183 @@
+/**
+ * Moving a page between documents: going to an address, back through its history, or reloading.
+ * Each move is an action, so it takes the page's turn, goes through the input guard and is
+ * recorded, but it sends no input.
+ */
+import { Deferred, Duration, Effect, Schedule } from "effect";
+
+import {
+  BrowserError,
+  InvalidRequest,
+  NavigationFailed,
+  NotActionable,
+  NotFound,
+} from "../../BrowserError.ts";
+import type { Guard } from "../input/guard.ts";
+import type { InputMarks, Perform } from "../input/perform.ts";
+import { failWith, type PageContext } from "./context.ts";
+import * as Url from "./url.ts";
+
+export const make = (
+  page: PageContext,
+  perform: Perform,
+  preparePolicy: Guard["preparePolicy"],
+) => {
+  const { playwright, settings, native } = page;
+  const { send } = page.protocol;
+
+  // `address` is where `run` goes, as the action, the guard and a failure report it.
+  const navigation = (name: string, run: () => Promise<unknown>, address: string) => {
+    const url = Url.redact(address);
+
+    return perform(
+      name,
+      { target: url, input: false },
+      settings.navigationTimeout,
+      preparePolicy(name, { target: url }, [], { destination: url }),
+      (marks) =>
+        marks.sent.pipe(
+          Effect.andThen(native(name, run)),
+          Effect.mapError((error) =>
+            error.reason._tag === "Failed" &&
+            /net::|NS_ERROR|Cannot navigate/i.test(error.reason.detail)
+              ? new BrowserError({
+                  operation: name,
+                  reason: new NavigationFailed({ url, detail: error.reason.detail }),
+                  dispatched: true,
+                })
+              : error,
+          ),
+          Effect.asVoid,
+        ),
+    );
+  };
+
+  const history = native("back", () => send("Page.getNavigationHistory"));
+
+  // While a traversal swaps documents, Chromium can briefly route this session to the outgoing
+  // document, which has become inactive (for instance after it entered the back-forward cache),
+  // so a read during the traversal is retried until the session reaches the active document.
+  const traversingHistory = history.pipe(
+    Effect.retry({
+      schedule: Schedule.spaced(Duration.millis(50)),
+      while: (error) =>
+        error.reason._tag === "Failed" &&
+        /not attached to an active page/i.test(error.reason.detail),
+    }),
+  );
+
+  // The current entry's title is the one the page last set, and empty where it set none, so no
+  // address stands in for it. The browser answers it, whatever the page's script is doing.
+  const title = native("title", () => send("Page.getNavigationHistory")).pipe(
+    Effect.map(({ entries, currentIndex }) => entries[currentIndex]?.title ?? ""),
+  );
+
+  const noPrevious = failWith("back", new NotFound({ target: "a previous page in this tab" }));
+
+  const prepareBack = Effect.gen(function* () {
+    const before = yield* history;
+    const current = before.entries[before.currentIndex];
+    const previous = before.entries[before.currentIndex - 1];
+
+    if (previous === undefined) return yield* noPrevious;
+    const plan = yield* preparePolicy("back", {}, [], { destination: Url.redact(previous.url) });
+
+    return {
+      request: plan.request,
+      validate: Effect.gen(function* () {
+        const approval = yield* plan.validate;
+        const latest = yield* history;
+
+        if (
+          latest.currentIndex !== before.currentIndex ||
+          latest.entries[latest.currentIndex]?.id !== current?.id ||
+          latest.entries[latest.currentIndex - 1]?.id !== previous.id ||
+          latest.entries[latest.currentIndex - 1]?.url !== previous.url
+        )
+          return yield* failWith(
+            "back",
+            new NotActionable({
+              detail: "the navigation history changed while input policy was pending",
+            }),
+          );
+
+        return approval;
+      }),
+    };
+  });
+
+  // One protocol traversal on every path. It has committed once the tab leaves its entry, which
+  // also covers entries that only an iframe created, where the main frame never navigates, and
+  // entries sharing a URL. A frame navigation then shows Playwright has caught up before the
+  // main document's readiness is read.
+  const goBack = (marks: InputMarks) =>
+    Effect.gen(function* () {
+      const before = yield* history;
+      const current = before.entries[before.currentIndex];
+      const previous = before.entries[before.currentIndex - 1];
+
+      if (current === undefined || previous === undefined) return yield* noPrevious;
+      const navigated = yield* Deferred.make<void>();
+
+      const onNavigation = () => {
+        Deferred.doneUnsafe(navigated, Effect.void);
+      };
+
+      yield* Effect.acquireUseRelease(
+        Effect.sync(() => playwright.on("framenavigated", onNavigation)),
+        () =>
+          Effect.gen(function* () {
+            yield* marks.sent;
+            yield* native("back", () =>
+              send("Page.navigateToHistoryEntry", { entryId: previous.id }),
+            );
+            yield* traversingHistory.pipe(
+              Effect.repeat({
+                schedule: Schedule.spaced(Duration.millis(50)),
+                until: (latest) => latest.entries[latest.currentIndex]?.id !== current.id,
+              }),
+            );
+            yield* Deferred.await(navigated);
+          }),
+        () => Effect.sync(() => playwright.off("framenavigated", onNavigation)),
+      );
+      yield* native("back", () => playwright.waitForLoadState("domcontentloaded", { timeout: 0 }));
+    });
+
+  const goto = (url: string) => {
+    const parsed = Url.parse(url);
+
+    if (
+      parsed === null ||
+      !["http:", "https:", "about:", "data:", "file:"].includes(parsed.protocol)
+    )
+      return failWith(
+        "navigate",
+        new InvalidRequest({ detail: `"${Url.redact(url)}" is not a URL` }),
+      );
+
+    return navigation(
+      "navigate",
+      () => playwright.goto(parsed.href, { waitUntil: "domcontentloaded", timeout: 0 }),
+      parsed.href,
+    );
+  };
+
+  const back = perform(
+    "back",
+    { target: "back", input: false },
+    settings.navigationTimeout,
+    prepareBack,
+    goBack,
+  );
+
+  const reload = Effect.suspend(() =>
+    navigation(
+      "reload",
+      () => playwright.reload({ waitUntil: "domcontentloaded", timeout: 0 }),
+      playwright.url(),
+    ),
+  );
+
+  return { goto, back, reload, title };
+};

package/src/internal/page/openings.ts

@@ -0,0 +1,87 @@
+/** A page's input waits for the actual tabs it opened to finish the browser's registration. */
+import { Deferred, Effect, Exit } from "effect";
+import type { CDPSession, Page as PlaywrightPage } from "playwright-core";
+
+import { BrowserError, Closed, Failed, type Reason } from "../../BrowserError.ts";
+
+/** How the browser's registration of each tab it was told of ended, once it has. */
+export type Registrations = WeakMap<PlaywrightPage, Deferred.Deferred<void, BrowserError>>;
+
+export interface Mark {
+  windows: number;
+  readonly registrations: Array<Effect.Effect<void, BrowserError>>;
+  changed: Deferred.Deferred<void>;
+}
+
+export const make = Effect.fnUntraced(function* (
+  playwright: PlaywrightPage,
+  cdp: CDPSession,
+  registrations: Registrations,
+  closedBy: () => Closed["cause"],
+) {
+  const failed = (reason: Reason) =>
+    Exit.fail(new BrowserError({ operation: "newPage", reason, dispatched: false }));
+
+  let active: Mark | undefined;
+  const gone = Deferred.makeUnsafe<never, BrowserError>();
+
+  const windowOpened = () => {
+    if (active !== undefined) active.windows += 1;
+  };
+
+  const popup = (opened: PlaywrightPage) => {
+    if (active === undefined) return;
+    // Playwright emits the context's page event first, so its owner already has this exact
+    // popup's registration. A window notification alone has no target id and cannot name it.
+    const registered = registrations.get(opened);
+
+    active.registrations.push(
+      registered === undefined
+        ? failed(new Failed({ detail: "the popup has no registration" }))
+        : Deferred.await(registered),
+    );
+    Deferred.doneUnsafe(active.changed, Exit.void);
+    active.changed = Deferred.makeUnsafe<void>();
+  };
+
+  const clear = Effect.sync(() => {
+    active = undefined;
+  });
+
+  yield* Effect.acquireRelease(
+    Effect.sync(() => {
+      cdp.on("Page.windowOpen", windowOpened);
+      playwright.on("popup", popup);
+    }),
+    () =>
+      Effect.sync(() => {
+        active = undefined;
+        cdp.off("Page.windowOpen", windowOpened);
+        playwright.off("popup", popup);
+        Deferred.doneUnsafe(gone, failed(new Closed({ cause: closedBy() })));
+      }),
+  );
+
+  return {
+    mark: () => {
+      const mark: Mark = { windows: 0, registrations: [], changed: Deferred.makeUnsafe<void>() };
+
+      active = mark;
+
+      return mark;
+    },
+    clear,
+    settle: (mark: Mark) =>
+      Effect.gen(function* () {
+        // A blocked window or a tab that closes as it opens may never become a Playwright popup.
+        // Discovery and registration both share the input's deadline, so an unresolved opening
+        // fails with potentially dispatched input rather than claiming the tab has been tracked.
+        while (mark.registrations.length < mark.windows) yield* Deferred.await(mark.changed);
+        // A real popup has a known registration; its failure stays a failure, and its wait shares
+        // the input's deadline rather than quietly returning before the browser tracks it.
+        yield* Effect.forEach(mark.registrations, (registration) => registration);
+      }).pipe(Effect.raceFirst(Deferred.await(gone)), Effect.ensuring(clear)),
+  };
+});
+
+export type Openings = Effect.Success<ReturnType<typeof make>>;

package/src/internal/page/page.ts

@@ -0,0 +1,165 @@
+/**
+ * The page implementation behind `Page.Page`. `Browser` constructs pages and owns the state they
+ * share (the clock mapping and event publication), so construction stays internal. A page is
+ * assembled here from its domains: the script bridge, pictures, reading, its timeline, input and
+ * navigation.
+ * What a presenter and a stage need of a page, and no caller should, it keeps out of sight.
+ */
+import { type Effect as Eff, Effect, Option } from "effect";
+
+import type { BrowserError } from "../../BrowserError.ts";
+import type { Frame } from "../../Frame.ts";
+import { type Page, State } from "../../Page.ts";
+import * as Actions from "../input/actions.ts";
+import type { Controller } from "../pictures/capture.ts";
+import * as Pictures from "../pictures/pictures.ts";
+import * as Reading from "../reading/reading.ts";
+import * as Ready from "../reading/ready.ts";
+import * as Changes from "../timeline/changes.ts";
+import * as Window from "../timeline/window.ts";
+import * as Bridge from "./bridge.ts";
+import * as Context from "./context.ts";
+import * as Navigation from "./navigation.ts";
+import * as Url from "./url.ts";
+import * as Viewport from "./viewport.ts";
+
+export interface Internals {
+  /** The page's input, in any style. */
+  readonly input: Actions.Input;
+  /** Drain earlier input and retain a read turn through the effect; the whole wait is bounded. */
+  readonly afterInput: <A, E, R>(effect: Eff.Effect<A, E, R>) => Eff.Effect<A, E | BrowserError, R>;
+  /** Start capture now, independently of its first frame. The calling scope keeps it running. */
+  readonly capture: Controller["open"];
+  /** Current capture/document evidence, without waiting for acknowledgement or transport. */
+  readonly current: (frame: Frame) => boolean;
+  /** A current frame, with a fresh bounded answer from the page and capture sessions. */
+  readonly confirm: (frame: Frame) => Eff.Effect<boolean, BrowserError>;
+  /** The page's documents so far, counted as `Navigated` counts them. */
+  readonly document: () => number;
+  /** Wait, in one call, until what a query finds is there, is not, or shows something else. */
+  readonly until: Reading.Reading["until"];
+}
+
+/** A page this library built: it keeps its internals where only this module reaches them. */
+class Built {
+  readonly #internals: Internals;
+
+  constructor(internals: Internals) {
+    this.#internals = internals;
+  }
+
+  static internalsOf(page: Page): Internals | undefined {
+    return page instanceof Built ? page.#internals : undefined;
+  }
+}
+
+/** What a page this library built keeps out of sight; nothing for any other `Page`. */
+export const internalsOf = (page: Page) => Built.internalsOf(page);
+
+/** `view`, made from `page` with some of its operations replaced, keeping what `page` keeps out of sight. */
+export const viewOf = <A extends Page>(page: Page, view: A): A => {
+  const internals = internalsOf(page);
+
+  return internals === undefined ? view : Object.assign(new Built(internals), view);
+};
+
+export const make = Effect.fnUntraced(function* (options: Context.MakeOptions) {
+  const page = Context.make(options, yield* Effect.scope);
+  const { id, playwright, native, owned, within, lane, span } = page;
+  const bridge = yield* Bridge.make(page);
+  const viewport = Viewport.make(page, bridge);
+  const input = Actions.make(page, bridge, viewport);
+  const pictures = yield* Pictures.make(page, bridge, viewport);
+  const reading = yield* Reading.make(page, bridge);
+  const navigation = Navigation.make(page, input.perform, input.preparePolicy);
+  const { capture } = pictures;
+  const changes = Changes.make(page, bridge, pictures.estimate);
+  const titles = lane.shared<string>("title", true);
+  const viewports = lane.shared<Effect.Success<Page["viewport"]>>("viewport", true);
+
+  // What the page's parts already know, asking it nothing: its documents as its own session saw
+  // them, the newest frame, and the viewport's text as last read since the document began.
+  const state = Effect.map(capture.latest, (latest) => {
+    const { document, url } = bridge.frameTag();
+    const committedAt = page.activity.documentAt;
+
+    return new State({
+      page: id,
+      at: page.now(),
+      url,
+      document,
+      committedAt: Number.isFinite(committedAt) ? committedAt : undefined,
+      load: bridge.loaded(),
+      frame: Option.getOrUndefined(latest),
+      text: reading.viewedSince(committedAt),
+    });
+  });
+
+  const current = (frame: Frame) =>
+    capture.current(frame) &&
+    bridge.frameTag().document === frame.document &&
+    frame.hostTime - frame.timing.uncertaintyMillis > page.activity.documentAt;
+
+  const assembled: Page = {
+    id,
+    playwright,
+    url: Effect.sync(() => Url.redact(playwright.url())),
+    title: titles("", navigation.title.pipe(within("title"))).pipe(span("Page.title"), owned),
+    goto: navigation.goto,
+    back: navigation.back,
+    reload: navigation.reload,
+    bringToFront: native("bringToFront", () => playwright.bringToFront()),
+    // Playwright answers once the page has closed, and at once for one already closed.
+    close: native("close", () => playwright.close()),
+    snapshot: reading.snapshot,
+    screenshot: pictures.screenshot,
+    frame: pictures.frame,
+    zoom: pictures.zoom,
+    viewport: viewports("", viewport.viewportFor("viewport").pipe(within("viewport"))).pipe(
+      span("Page.viewport"),
+      owned,
+    ),
+    find: reading.find,
+    text: reading.text,
+    changes,
+    window: Window.make(page, changes, capture.recent),
+    state,
+    click: (target, options) => input.click(target, options),
+    hover: (target) => input.hover(target),
+    drag: (from, to) => input.drag(from, to),
+    type: (text, options) => input.type(text, options),
+    press: (keys, options) => input.press(keys, options),
+    scroll: (options) => input.scroll(options),
+    select: input.select,
+    waitFor: reading.waitFor,
+    ready: Ready.make(page, bridge, capture),
+    screencast: capture.stream,
+    captureStats: pictures.captureStats,
+    recentFrames: capture.recent,
+    recentEvents: options.recentEvents,
+  };
+
+  const internals: Internals = {
+    input,
+    afterInput: (effect) =>
+      lane
+        .read(
+          "inputEnded",
+          page.settings.navigationTimeout,
+        )(Effect.andThen(input.perform.idle, effect))
+        .pipe(within("inputEnded", page.settings.navigationTimeout), owned),
+    capture: capture.open,
+    current,
+    confirm: (frame) =>
+      native("shown", () => page.protocol.send("Page.getFrameTree")).pipe(
+        Effect.flatMap(() => capture.confirm(frame)),
+        Effect.map((confirmed) => confirmed && current(frame)),
+        within("shown", "2 seconds"),
+        owned,
+      ),
+    document: () => bridge.frameTag().document,
+    until: reading.until,
+  };
+
+  return Object.assign(new Built(internals), assembled);
+});

package/src/internal/page/url.ts

@@ -0,0 +1,100 @@
+/**
+ * Addresses: reading one the way a person types it, for `Page.goto` and the browser tools alike,
+ * and reporting one without the values that are credentials, by one rule that the page script runs
+ * too, for the outline's links.
+ */
+
+const scheme = /^[a-z][a-z0-9+.-]*:/i;
+
+// `localhost:3000` and `example.com:8080/a` look like a scheme to the URL parser; a port decides.
+const hostAndPort = /^[^\s/?#@:]+:\d+(?:[/?#]|$)/;
+
+const loopback = /^(?:localhost|127(?:\.\d+){3}|\[::1\])(?:[:/?#]|$)/i;
+
+/** The URL `input` names. Without a scheme it is a web address: HTTPS, or HTTP on loopback. */
+export const parse = (input: string): URL | null => {
+  const text = input.trim();
+
+  if (scheme.test(text) && !hostAndPort.test(text)) return URL.parse(text);
+
+  return URL.parse(`${loopback.test(text) ? "http" : "https"}://${text}`);
+};
+
+/**
+ * The rule that reports an address without its credentials. The page script runs it too, so it
+ * stays self-contained, as `names.inpage.ts` says a page-side part must.
+ */
+export const addresses = () => {
+  // What a credential's value reads as, as a secret field's text does (`Page.redacted`).
+  const withheld = "••••••••" as const;
+
+  // A parameter's name, compared in lowercase without separators, says it is a credential: a token,
+  // secret, password, signature, assertion, session id or one-time code, or a code or key of a kind
+  // that signs someone in or signs a request, such as `verification_code` or `api_key`.
+  const credential =
+    /token|secret|passw|passcode|passphrase|signature|credential|assertion|verifier|bearer|jwt|hmac|apikey|accesskey|privatekey|sess(?:ion)?id|saml(?:response|art)|(?:sig|otp)$|(?:auth|api|access|private|secret|signing|client|encryption|licen[cs]e|session|master|app|device|verification|verify|confirmation|confirm|activation|activate|reset|recovery|login|security|magic|onetime|mfa|2fa|sms|email|otp|oob)(?:code|key)$|^(?:auth|authorization|pwd|pass)$/;
+
+  // These names as often say what an address is about, such as a stock code, a support ticket or a
+  // conference session. Under them a value is a credential when it looks generated, at least 16
+  // characters with letters and digits, as tokens, session ids and authorization codes do.
+  const ambiguous = /^(?:code|key|session|sid|ticket)$/;
+
+  const secret = (name: string, value: string) => {
+    const bare = name.toLowerCase().replace(/[^a-z0-9]/g, "");
+
+    return (
+      value !== "" &&
+      (credential.test(bare) ||
+        (ambiguous.test(bare) && value.length >= 16 && /\d/.test(value) && /[a-z]/i.test(value)))
+    );
+  };
+
+  // Parameters as written, each credential's value withheld: a query's, a fragment's written as a
+  // query, or a path's segments', as a Java session id is.
+  const masked = (parameters: string, separator: string) =>
+    parameters
+      .split(separator)
+      .map((parameter) => {
+        const [name = "", value = ""] = [...new URLSearchParams(parameter)][0] ?? [];
+
+        return secret(name, value)
+          ? `${parameter.slice(0, parameter.indexOf("=") + 1)}${withheld}`
+          : parameter;
+      })
+      .join(separator);
+
+  /**
+   * `url` as the library reports it: without userinfo, and with each credential's value withheld,
+   * so the rest keeps its identity, such as a chart's `?ticker=ETH`. An address without a host,
+   * such as `data:` or `about:blank`, is content or a fixed name, and stays as it is.
+   */
+  const redact = (url: string): string => {
+    const parsed = URL.parse(url);
+
+    if (parsed === null || parsed.host === "") return url;
+    parsed.username = "";
+    parsed.password = "";
+    parsed.pathname = masked(parsed.pathname, ";");
+    parsed.search = masked(parsed.search.slice(1), "&");
+    if (parsed.hash.includes("=")) {
+      const fragment = parsed.hash.slice(1);
+      const question = fragment.indexOf("?");
+      // A route before the parameters, as in `#/inbox?token=…`, stays.
+      const start = question >= 0 && question < fragment.indexOf("=") ? question + 1 : 0;
+
+      parsed.hash = fragment.slice(0, start) + masked(fragment.slice(start), "&");
+    }
+
+    return parsed.href.replaceAll(encodeURIComponent(withheld), withheld);
+  };
+
+  return { withheld, redact };
+};
+
+export const { withheld, redact } = addresses();
+
+/** An address inside text, as a failure's message quotes one. */
+export const quoted = /[a-z][a-z\d+.-]*:\/\/[^\s"'<>]+/gi;
+
+/** `text` with each address in it redacted. */
+export const redactWithin = (text: string) => text.replace(quoted, (url) => redact(url));

package/src/internal/page/viewport.ts

@@ -0,0 +1,43 @@
+/**
+ * The viewport's size in CSS pixels. Playwright knows it only for a context it created; over CDP it
+ * reports none, so the page answers, and so does a picture taken at one device pixel per CSS
+ * pixel. Pointer bounds, page scrolls, crops, capture size and frame reuse all read this one
+ * source; the latest answer serves checks that cannot wait for the page.
+ */
+import { Effect } from "effect";
+
+import { ViewportResultSchema } from "../reading/outline.inpage.ts";
+import { type Bridge, scriptCall } from "./bridge.ts";
+import { decodeWith, type PageContext } from "./context.ts";
+
+export const make = (page: PageContext, bridge: Bridge) => {
+  const { playwright } = page;
+  let measuredViewport: { readonly width: number; readonly height: number } | null = null;
+
+  const knownViewport = () => playwright.viewportSize() ?? measuredViewport;
+
+  const viewportFor = (operation: string) =>
+    Effect.suspend(() => {
+      const known = playwright.viewportSize();
+
+      return known === null
+        ? bridge.evaluate(operation, scriptCall("viewport")).pipe(
+            Effect.flatMap(decodeWith(operation, ViewportResultSchema)),
+            Effect.tap((measured) =>
+              Effect.sync(() => {
+                measuredViewport = measured;
+              }),
+            ),
+          )
+        : Effect.succeed(known);
+    });
+
+  /** The size of an unscaled picture of the whole viewport, which is the viewport's own. */
+  const remember = (size: { readonly width: number; readonly height: number }) => {
+    measuredViewport = { width: size.width, height: size.height };
+  };
+
+  return { knownViewport, viewportFor, remember };
+};
+
+export type Viewport = ReturnType<typeof make>;