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

package/src/Change.ts

@@ -0,0 +1,88 @@
+/**
+ * What visibly changed on a page over a window, element by element: text that changed, appeared,
+ * disappeared or came and went, a field's value, and the document's title. A change says what was
+ * shown at the window's start and at its end, how often it changed between, where it is on the
+ * page, and the input it followed, where it was that input's doing.
+ *
+ * `Page.changes` reads it. A page records once something reads its changes: from then, and from the
+ * start of each later document once it is parsed, until nobody has read it for two minutes. A page
+ * nobody reads records nothing. The record keeps 256 elements, each with its last 32 changes, for a
+ * minute; an element that keeps changing gives way before news, and what gives way is counted in
+ * `dropped`, with `from` moved past it. A change is told when it was in view as the page rendered
+ * it, its style showing it, so one scrolled away later is still told, and something removed or
+ * hidden only if it was in view before. What the record cannot see: pictures, a canvas, frames,
+ * shadow roots and SVG; a value a script sets; and a class that reveals an element the record has
+ * not seen before, such as a toast already on the page, though its later changes are seen.
+ *
+ * @since 0.3.0
+ */
+import { Schema } from "effect";
+
+import { Subject } from "./BrowserEvent.ts";
+import * as Words from "./internal/timeline/words.ts";
+
+/**
+ * `text` changed; `appeared` and `disappeared`, whether added or removed or shown or hidden;
+ * `brief`, appeared and gone again by the window's end; `value`, a field's; `title`, the document's.
+ */
+export const Kind = Schema.Literals(["text", "appeared", "disappeared", "brief", "value", "title"]);
+
+export type Kind = typeof Kind.Type;
+
+export class Change extends Schema.Class<Change>("effect-browser/Change")({
+  kind: Kind,
+  /**
+   * What changed, as the page names it now, or where it was for what went. Its own words are what
+   * changed, so its name is empty unless something else names it, as a field's label does.
+   */
+  subject: Subject,
+  /** When it first changed in the window, in host monotonic milliseconds on the browser's clock. */
+  startedAt: Schema.Finite,
+  /** When it last changed in the window. */
+  at: Schema.Finite,
+  /**
+   * What it showed at the window's start; absent for what appeared and where the record let that go.
+   * What disappeared says what it showed as it went. A field's value reads `••••` unless unmasked.
+   */
+  before: Schema.optional(Schema.String),
+  /** What it showed at the window's end; absent for what disappeared. What came and went says what it showed. */
+  after: Schema.optional(Schema.String),
+  /** How many times what it showed changed in the window. */
+  count: Schema.Int.check(Schema.isGreaterThan(0)),
+  /** For a number that changed more than once, its lowest and highest, as shown. */
+  lowest: Schema.optional(Schema.String),
+  highest: Schema.optional(Schema.String),
+  /** When it last changed before the window, as far back as the record keeps: in flux, not news. */
+  earlier: Schema.optional(Schema.Finite),
+  /**
+   * When the trusted input it followed reached the page, where it was that input's doing. It was not
+   * in flux: in the 10 s before the input it had not changed, and nothing had come into or left what
+   * it sits in, so a ticker's tick or a feed's line is not. Then it changed within 3 s inside what
+   * the input acted on or its row, form, dialog or controlled element; or, elsewhere, within 500 ms
+   * of an input on a page where nothing had changed in the 2 s before, as a menu a portal puts at
+   * the end of the page does. What holds the input's target, as a menu holds its item, does not
+   * count against it. The page's `Action` that sent it holds that time.
+   */
+  cause: Schema.optional(Schema.Finite),
+}) {}
+
+export class Changes extends Schema.Class<Changes>("effect-browser/Changes")({
+  /** The page's document these changes belong to, as `Navigated` counts them. */
+  document: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  /** Where the record is whole: before it, changes may be missing. */
+  from: Schema.Finite,
+  /** Where the window ends: its `until`, or when the page was read. */
+  until: Schema.Finite,
+  /**
+   * Where the window ends on the page's own clock. Give these changes as the next read's `since` and
+   * the two windows meet exactly, whatever the clock mapping does meanwhile.
+   */
+  cursor: Schema.Finite,
+  /** Changes in the window the record let go, at least; 0 when it kept them all. */
+  dropped: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  /** Oldest first, by when each began to change. */
+  changes: Schema.Array(Change),
+}) {}
+
+/** A change in words for a model, such as `"$61,240" became "$62,010" (row "Bitcoin", column "Price")`. */
+export const describe = (change: Change): string => Words.describe(change);

package/src/Chromium.ts

@@ -0,0 +1,102 @@
+/**
+ * A local Chromium, launched for the scope and closed with it.
+ *
+ * It uses the Chromium build that `playwright-core` installs
+ * (`npx playwright-core install chromium`), unless `executablePath` names another.
+ *
+ * Signals are the program's to handle: run it with `NodeRuntime.runMain`, which interrupts it on
+ * SIGINT and SIGTERM, so the browser closes with its scope.
+ *
+ * @since 0.3.0
+ */
+import { Effect, Layer } from "effect";
+import { chromium } from "playwright-core";
+
+import * as Browser from "./Browser.ts";
+import { type BrowserError, Failed } from "./BrowserError.ts";
+import { reasonOf, undispatched } from "./internal/page/context.ts";
+
+export interface Options extends Browser.Options {
+  /** Defaults to true. */
+  readonly headless?: boolean | undefined;
+  /**
+   * Run Chromium's sandbox. Defaults to false, as in Playwright, so an exploit in a page's renderer
+   * runs with this process's privileges. Hosts that don't allow unprivileged user namespaces, such
+   * as many containers and Ubuntu 23.10 or later by default, can't start the sandbox; opening then
+   * fails and says so.
+   */
+  readonly sandbox?: boolean | undefined;
+  /** Defaults to 1280x720 CSS pixels at a device scale factor of 1. */
+  readonly viewport?: { readonly width: number; readonly height: number } | undefined;
+  readonly executablePath?: string | undefined;
+  readonly args?: ReadonlyArray<string> | undefined;
+  readonly userAgent?: string | undefined;
+  readonly locale?: string | undefined;
+}
+
+// Playwright's own default, stated so that a launch timeout reports the bound it exceeded.
+const launchTimeoutMillis = 180_000;
+
+const failed = (operation: string, timeoutMillis?: number) => (cause: unknown) =>
+  undispatched(operation, reasonOf(cause, timeoutMillis));
+
+// Playwright puts this in place of Chromium's startup log when the sandbox could not start, in an
+// error that otherwise reads as a closed browser.
+const sandboxFailed = /Chromium sandboxing failed|No usable sandbox/;
+
+const launchFailed = (cause: unknown) =>
+  sandboxFailed.test(String(cause))
+    ? undispatched(
+        "launch",
+        new Failed({
+          detail:
+            "Chromium's sandbox could not start on this host: it needs unprivileged user namespaces, and a user other than root",
+        }),
+      )
+    : failed("launch", launchTimeoutMillis)(cause);
+
+/** Launch Chromium and open a `Browser` over a fresh context. */
+export const open = Effect.fn("Chromium.open")(function* (options: Options = {}) {
+  const launched = yield* Effect.acquireRelease(
+    Effect.tryPromise({
+      try: () =>
+        chromium.launch({
+          headless: options.headless ?? true,
+          chromiumSandbox: options.sandbox ?? false,
+          timeout: launchTimeoutMillis,
+          // The program owns its signals. Playwright's handlers close every browser on any of
+          // these, and on SIGINT then exit the process, so no finalizer would run.
+          handleSIGINT: false,
+          handleSIGTERM: false,
+          handleSIGHUP: false,
+          ...(options.executablePath === undefined
+            ? {}
+            : { executablePath: options.executablePath }),
+          ...(options.args === undefined ? {} : { args: [...options.args] }),
+        }),
+      catch: launchFailed,
+    }).pipe(Effect.withSpan("Chromium.launch", {}, { captureStackTrace: false })),
+    (browser) => Effect.tryPromise(() => browser.close()).pipe(Effect.ignore),
+  );
+
+  const context = yield* Effect.tryPromise({
+    try: () =>
+      launched.newContext({
+        viewport: options.viewport ?? { width: 1280, height: 720 },
+        deviceScaleFactor: 1,
+        ...(options.userAgent === undefined ? {} : { userAgent: options.userAgent }),
+        ...(options.locale === undefined ? {} : { locale: options.locale }),
+      }),
+    catch: failed("launch"),
+  });
+
+  return yield* Browser.make(
+    context,
+    { id: `chromium-${launched.version()}`, provider: "chromium" },
+    options,
+  );
+});
+
+/** A `Browser` Layer that launches Chromium when built and closes it when released. */
+export const layer = (options: Options = {}): Layer.Layer<Browser.Browser, BrowserError> =>
+  Layer.effect(Browser.Browser, open(options));

package/src/Expect.ts

@@ -0,0 +1,180 @@
+/**
+ * Expectations: what an action is for, checked on the page, so that an action whose outcome is
+ * uncertain is sent again only where it did not take effect. An action that failed after its input
+ * went, a `Timeout` or a `Closed` with `dispatched`, may have done what it was for; repeating it
+ * blindly may do it twice, such as placing an order twice.
+ *
+ * An attempt takes its expectation's baseline from the page once, as it begins. Each `run` then
+ * checks first: where the expectation holds already, it sends nothing and is `AlreadyDone`.
+ * Otherwise it acts, and waits for the expectation: `Done`, or `NotDone` when it did not come in
+ * time. An action that fails after its input went is checked too, `Done` if its effect came, and
+ * otherwise fails as it did, so a later `run` of the same attempt checks before it acts again,
+ * on the same page or on the one a reconnect finds by its id.
+ *
+ * ```ts
+ * const placing = yield* Expect.attempt(page, Expect.appeared({ text: "Order placed" }))
+ * const outcome = yield* placing.run(page, (page) => page.click("e12"))
+ * // After a Timeout that left `dispatched`, the same call clicks again only if no order shows.
+ * ```
+ *
+ * A query is `Page.find`'s, over the whole document unless it says otherwise, and each check is one
+ * call to the page, a wait included; `navigated` reads the page's address and document, at no
+ * call. What `changed` compares stays in the page: text, field values and states, focus aside.
+ *
+ * @since 0.3.0
+ */
+import { Cause, Duration, Effect, Exit, Option, Schedule } from "effect";
+
+import { type BrowserError, InvalidRequest } from "./BrowserError.ts";
+import { undispatched } from "./internal/page/context.ts";
+import { type Internals, internalsOf } from "./internal/page/page.ts";
+import type { FindQuery, Page } from "./Page.ts";
+
+/** What an action is for, as the page can tell it. */
+export type Expectation =
+  | { readonly _tag: "Appeared"; readonly query: FindQuery }
+  | { readonly _tag: "Gone"; readonly query: FindQuery }
+  | { readonly _tag: "Changed"; readonly query: FindQuery }
+  | { readonly _tag: "Navigated"; readonly url: string | RegExp | undefined };
+
+/** Something the query finds. */
+export const appeared = (query: FindQuery): Expectation => ({ _tag: "Appeared", query });
+
+/** Nothing the query finds. */
+export const gone = (query: FindQuery): Expectation => ({ _tag: "Gone", query });
+
+/**
+ * What the query finds shows something other than it did as the attempt began: other elements, or
+ * their text, values or states.
+ */
+export const changed = (query: FindQuery): Expectation => ({ _tag: "Changed", query });
+
+/**
+ * The page is at `url`, the whole address or a pattern; without one, at an address or in a
+ * document other than the attempt's first.
+ */
+export const navigated = (url?: string | RegExp): Expectation => ({ _tag: "Navigated", url });
+
+/**
+ * `Done`: the action ran, and what it was for came. `AlreadyDone`: it held before the action was
+ * sent, so it was not. `NotDone`: the action ran, and it did not come within the attempt's wait.
+ */
+export type Outcome = "Done" | "AlreadyDone" | "NotDone";
+
+export interface Options {
+  /** How long an action's effect may take to show. Defaults to 5 seconds. */
+  readonly wait?: Duration.Input | undefined;
+}
+
+export interface Attempt {
+  readonly expectation: Expectation;
+  /** Whether the expectation holds on `page` now. */
+  readonly holds: (page: Page) => Effect.Effect<boolean, BrowserError>;
+  /**
+   * `act` on `page`, unless the expectation holds there already: see the module's comment. A
+   * failure before its input went is the action's own, and nothing is checked.
+   */
+  readonly run: (
+    page: Page,
+    act: (page: Page) => Effect.Effect<unknown, BrowserError>,
+  ) => Effect.Effect<Outcome, BrowserError>;
+}
+
+const refused = (detail: string) => undispatched("expect", new InvalidRequest({ detail }));
+
+const internalsFor = (page: Page): Effect.Effect<Internals, BrowserError> => {
+  const internals = internalsOf(page);
+
+  return internals === undefined
+    ? Effect.fail(
+        refused("only a page a Browser opened, or a presenter's view of one, can be checked"),
+      )
+    : Effect.succeed(internals);
+};
+
+const atUrl = (url: string, wanted: string | RegExp) =>
+  typeof wanted === "string" ? url === wanted : new RegExp(wanted.source, wanted.flags).test(url);
+
+/** Begin an attempt at `expectation` on `page`, which takes its baseline from the page now. */
+export const attempt = Effect.fn("Expect.attempt")(function* (
+  page: Page,
+  expectation: Expectation,
+  options: Options = {},
+) {
+  const wait = Duration.fromInput(options.wait ?? Duration.seconds(5));
+
+  if (Option.isNone(wait) || Duration.isNegative(wait.value))
+    return yield* refused("wait must be a duration, not negative");
+  const waitMillis = Duration.toMillis(wait.value);
+  const first = yield* page.state;
+  const internals = yield* internalsFor(page);
+
+  // What `changed` compares with: the mark of what the query found as the attempt began.
+  const from =
+    expectation._tag === "Changed"
+      ? (yield* internals.until(expectation.query, "some", 0)).mark
+      : undefined;
+
+  // Navigated: at the address asked, or, without one, somewhere other than the attempt's first,
+  // where a document counts only on the page that counted it, not on one a reconnect found.
+  const navigatedOn = (target: Page, url: string | RegExp | undefined) =>
+    Effect.map(target.state, (now) =>
+      url !== undefined
+        ? atUrl(now.url, url)
+        : now.url !== first.url ||
+          (internalsOf(target) === internals && now.document !== first.document),
+    );
+
+  const holdsWithin = (target: Page, millis: number): Effect.Effect<boolean, BrowserError> => {
+    if (expectation._tag === "Navigated") {
+      const look = navigatedOn(target, expectation.url);
+
+      return look.pipe(
+        Effect.repeat({
+          until: (held) => held,
+          schedule: Schedule.spaced(Duration.millis(50)),
+        }),
+        Effect.timeoutOrElse({ duration: Duration.millis(millis), orElse: () => look }),
+      );
+    }
+
+    const want =
+      expectation._tag === "Appeared"
+        ? "some"
+        : expectation._tag === "Gone"
+          ? "none"
+          : { other: from ?? "" };
+
+    return internalsFor(target).pipe(
+      Effect.flatMap((own) => own.until(expectation.query, want, millis)),
+      Effect.map(({ met }) => met),
+    );
+  };
+
+  const run = Effect.fn("Expect.run")(
+    function* (target: Page, act: (page: Page) => Effect.Effect<unknown, BrowserError>) {
+      if (yield* holdsWithin(target, 0)) return "AlreadyDone" as const;
+      const acted = yield* Effect.exit(act(target));
+
+      if (Exit.isSuccess(acted))
+        return (yield* holdsWithin(target, waitMillis)) ? ("Done" as const) : ("NotDone" as const);
+      const error = Cause.findErrorOption(acted.cause);
+
+      // A failure before the input went did nothing; one after it may have done what it was for.
+      if (Option.isNone(error) || !error.value.dispatched)
+        return yield* Effect.failCause(acted.cause);
+      const held = yield* Effect.exit(holdsWithin(target, waitMillis));
+
+      return Exit.isSuccess(held) && held.value
+        ? ("Done" as const)
+        : yield* Effect.failCause(acted.cause);
+    },
+    Effect.tap((outcome) => Effect.annotateCurrentSpan({ expectation: expectation._tag, outcome })),
+  );
+
+  return {
+    expectation,
+    holds: (target) => holdsWithin(target, 0),
+    run,
+  } satisfies Attempt;
+});

package/src/Frame.ts

@@ -0,0 +1,130 @@
+/**
+ * Pictures of a page: screenshots, and screencast frames stamped with the browser's clock.
+ *
+ * @since 0.3.0
+ */
+import { Schema } from "effect";
+
+/** An encoded picture with its pixel dimensions. Crops also need their viewport origin. */
+export class Image extends Schema.Class<Image>("effect-browser/Image")({
+  data: Schema.Uint8Array,
+  mediaType: Schema.Literals(["image/jpeg", "image/png"]),
+  width: Schema.Finite,
+  height: Schema.Finite,
+}) {}
+
+const Nonnegative = Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0));
+const Count = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+
+/** Native CDP paint time mapped to the owning host clock, with transport uncertainty retained. */
+export class BrowserPaint extends Schema.TaggedClass<BrowserPaint>()("BrowserPaint", {
+  timestamp: Schema.Finite,
+  hostTime: Schema.Finite,
+  uncertaintyMillis: Nonnegative,
+}) {}
+
+/** A screenshot's host capture interval; it has no native browser paint timestamp. */
+export class Screenshot extends Schema.TaggedClass<Screenshot>()("Screenshot", {
+  hostTime: Schema.Finite,
+  uncertaintyMillis: Nonnegative,
+}) {}
+
+/**
+ * An image and its timing evidence. Paint time and screenshot capture time cannot be confused in
+ * serialized data. `receivedAt` records delivery on the owning host's monotonic clock; it does
+ * not make an old paint current.
+ */
+export class Frame extends Schema.Class<Frame>("effect-browser/Frame")({
+  page: Schema.String,
+  /** The page's browser session: its provider's session id, as `Browser.Service.id` gives it. */
+  session: Schema.String,
+  data: Schema.Uint8Array,
+  timing: Schema.Union([BrowserPaint, Screenshot]),
+  receivedAt: Schema.Finite,
+  width: Schema.Finite,
+  height: Schema.Finite,
+  /**
+   * The page's document committed before the frame arrived, as `Navigated` counts them. Just
+   * after a commit a browser can still show the old document's paint, so a frame may show the
+   * document before its own, never one after it.
+   */
+  document: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  /** The page's address when the frame arrived. */
+  url: Schema.String,
+}) {
+  get timestamp(): number | undefined {
+    return this.timing._tag === "BrowserPaint" ? this.timing.timestamp : undefined;
+  }
+
+  get hostTime(): number {
+    return this.timing.hostTime;
+  }
+
+  get image(): Image {
+    return new Image({
+      data: this.data,
+      mediaType: "image/jpeg",
+      width: this.width,
+      height: this.height,
+    });
+  }
+}
+
+/**
+ * A page's capture counts, over its life or a window of the latest minute: what Chromium sent,
+ * what readers got, and why the rest went no further. Frames that came late are counted apart from
+ * those a reader lost.
+ */
+export class CaptureStats extends Schema.Class<CaptureStats>("effect-browser/CaptureStats")({
+  received: Count,
+  accepted: Count,
+  /**
+   * Frames Chromium finished encoding after a newer one, dropped rather than reordered. It encodes
+   * several at once, so a busy machine makes more of them; none was a paint readers missed.
+   */
+  late: Count,
+  missingTimestamp: Count,
+  /**
+   * Frames dropped for their size. Most are other captures' frames, which a clipped screenshot
+   * draws into a screencast. The rest are the page's own frames of a new size, dropped while still
+   * unconfirmed: when another size replaced it, when its capture stopped, or beyond the 16 held.
+   */
+  foreignSize: Count,
+  /**
+   * Frames dropped because they may have been painted, or arrived, while the library took a clipped
+   * or scaled picture of the page, such as a zoom: Chromium draws those into the screencast too.
+   * Where Playwright emulates the viewport, the page's own frames from that time are among them; a
+   * crop on the page's own session leaves out only frames of another size than the page's.
+   */
+  duringPictures: Count,
+  /**
+   * Frames a reader missed by falling behind. Each reader counts its own, so with several readers
+   * this can exceed the frames accepted.
+   */
+  lost: Count,
+  /**
+   * Acknowledgements of frames sent and not yet answered, now, whatever the window. Chromium sends
+   * a frame only while few are unacknowledged, so a backlog means fewer frames.
+   */
+  ackBacklog: Count,
+  /** Paint-time gaps between consecutive accepted frames. */
+  gaps: Schema.Struct({
+    count: Count,
+    totalMillis: Nonnegative,
+    minMillis: Schema.NullOr(Nonnegative),
+    maxMillis: Schema.NullOr(Nonnegative),
+    lastMillis: Schema.NullOr(Nonnegative),
+  }),
+}) {}
+
+/**
+ * Settings for a page's one native capture. Readers that join a running capture share its
+ * settings: one without options accepts them, and one whose explicit options differ fails with
+ * `InvalidRequest`.
+ */
+export interface ScreencastOptions {
+  /** JPEG quality, 0 to 100. Defaults to 80. */
+  readonly quality?: number | undefined;
+  /** Frames are scaled down to fit this box. Defaults to the viewport in CSS pixels. */
+  readonly size?: { readonly width: number; readonly height: number } | undefined;
+}