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

package/src/internal/page/page.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 Page, State } from "../../Page.ts";
+import * as Actions from "../input/actions.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;
+  /** Completes once the input asked of the page so far has ended, failing `Busy` if it lasts. */
+  readonly inputEnded: Eff.Effect<void, 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 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,
+    inputEnded: lane.read("inputEnded")(Effect.void).pipe(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>;