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

package/src/BrowserError.ts

@@ -0,0 +1,225 @@
+/**
+ * The one error every browser operation fails with.
+ *
+ * `reason` says what went wrong and `dispatched` says whether the action's own input (a press,
+ * key, wheel, selection or hover, not the pointer travelling toward a press) or a navigation
+ * reached the browser first. `consequence` says what that leaves: what was lost, and whether the
+ * call can be repeated. `message` is a sentence for operators.
+ *
+ * @since 0.3.0
+ */
+import { Schema } from "effect";
+
+import { DisconnectCause } from "./BrowserEvent.ts";
+
+/** The operation did not finish in time. */
+export class Timeout extends Schema.TaggedError<Timeout>()("Timeout", {
+  millis: Schema.Finite,
+}) {
+  override get message() {
+    return `timed out after ${this.millis} ms`;
+  }
+}
+
+/**
+ * The operation waited its turn behind others on its page and was not given one in time, or was
+ * asked to fail fast: the page may be well, only busy.
+ */
+export class Busy extends Schema.TaggedError<Busy>()("Busy", {
+  waitedMillis: Schema.Finite,
+  /** The operations ahead of it: those holding the page and those asked before it. */
+  ahead: Schema.Int,
+}) {
+  override get message() {
+    const others = this.ahead === 1 ? "operation" : "operations";
+
+    return `the page was busy: it waited ${this.waitedMillis} ms behind ${this.ahead} other ${others}`;
+  }
+}
+
+/** The browser has as many pages open as `maxPages` allows, and none closed in time. */
+export class Limit extends Schema.TaggedError<Limit>()("Limit", {
+  maxPages: Schema.Int,
+}) {
+  override get message() {
+    return `the browser already has ${this.maxPages} pages open, as many as it allows`;
+  }
+}
+
+/** A ref from an earlier snapshot no longer names an element on the page. */
+export class StaleRef extends Schema.TaggedError<StaleRef>()("StaleRef", {
+  ref: Schema.String,
+}) {
+  override get message() {
+    return `${this.ref} is not on the page any more`;
+  }
+}
+
+/** What the operation looked for is not on the page. */
+export class NotFound extends Schema.TaggedError<NotFound>()("NotFound", {
+  target: Schema.String,
+}) {
+  override get message() {
+    return `${this.target} was not found`;
+  }
+}
+
+/** The element exists but cannot take this input: covered, disabled, hidden or the wrong kind. */
+export class NotActionable extends Schema.TaggedError<NotActionable>()("NotActionable", {
+  detail: Schema.String,
+}) {
+  override get message() {
+    return this.detail;
+  }
+}
+
+/** A navigation failed, for example on a DNS error or a refused connection. */
+export class NavigationFailed extends Schema.TaggedError<NavigationFailed>()("NavigationFailed", {
+  url: Schema.String,
+  detail: Schema.String,
+}) {
+  override get message() {
+    return `could not load ${this.url}: ${this.detail}`;
+  }
+}
+
+const closedBy = {
+  page: "the page was closed",
+  crashed: "the page crashed",
+  connection: "the connection to the browser was lost",
+  session: "the browser's session ended",
+  released: "the browser was released",
+};
+
+/**
+ * The page is gone: it was closed (`page`) or crashed, or its browser was lost for one of the
+ * browser's `DisconnectCause`s.
+ */
+export class Closed extends Schema.TaggedError<Closed>()("Closed", {
+  cause: Schema.Literals(["page", "crashed", ...DisconnectCause.literals]),
+}) {
+  override get message() {
+    return closedBy[this.cause];
+  }
+}
+
+/** The request itself is invalid, such as a ref that is not a ref or a point off the screen. */
+export class InvalidRequest extends Schema.TaggedError<InvalidRequest>()("InvalidRequest", {
+  detail: Schema.String,
+}) {
+  override get message() {
+    return this.detail;
+  }
+}
+
+/** The input policy refused the action before any input was sent. */
+export class PolicyDenied extends Schema.TaggedError<PolicyDenied>()("PolicyDenied", {
+  detail: Schema.String,
+  /** What made the policy deny, such as the failure of the judge it asked. */
+  cause: Schema.optional(Schema.Defect()),
+}) {
+  override get message() {
+    return `the input policy denied this action: ${this.detail}`;
+  }
+}
+
+/** The input policy did not release its hold within its own bound. */
+export class PolicyTimeout extends Schema.TaggedError<PolicyTimeout>()("PolicyTimeout", {
+  millis: Schema.Finite,
+}) {
+  override get message() {
+    return `the input policy did not allow this action within ${this.millis} ms`;
+  }
+}
+
+/** The requested event cursor fell behind the browser's bounded replay history. */
+export class EventHistoryExpired extends Schema.TaggedError<EventHistoryExpired>()(
+  "EventHistoryExpired",
+  {
+    after: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+    oldest: Schema.Int.check(Schema.isGreaterThan(0)),
+    latest: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  },
+) {
+  override get message() {
+    return `event history after ${this.after} expired; retained sequences are ${this.oldest}–${this.latest}`;
+  }
+}
+
+/** The browser, the connection or the provider failed in a way the other reasons do not cover. */
+export class Failed extends Schema.TaggedError<Failed>()("Failed", {
+  detail: Schema.String,
+}) {
+  override get message() {
+    return this.detail;
+  }
+}
+
+export const Reason = Schema.Union([
+  Timeout,
+  Busy,
+  Limit,
+  StaleRef,
+  NotFound,
+  NotActionable,
+  NavigationFailed,
+  Closed,
+  InvalidRequest,
+  PolicyDenied,
+  PolicyTimeout,
+  EventHistoryExpired,
+  Failed,
+]);
+
+export type Reason = typeof Reason.Type;
+
+export class BrowserError extends Schema.TaggedError<BrowserError>()("BrowserError", {
+  operation: Schema.String,
+  reason: Reason,
+  dispatched: Schema.Boolean,
+}) {
+  override get message() {
+    return `${this.operation} failed${this.dispatched ? " after it was sent" : ""}: ${this.reason.message}`;
+  }
+}
+
+/**
+ * What a failure leaves. `lost` is `"page"` when the page is gone and its browser stands, and
+ * `"session"` when the browser is gone with its pages. `repeat` says whether the call can be made
+ * again, on what still stands: `"safe"`, as nothing reached the browser; `"check"`, as it may have
+ * taken effect, so look first, as an `Expect` attempt does; `"pointless"`, as it fails again unless
+ * something changes, such as
+ * a new ref; or `"resume"`, reading events again from a newer cursor.
+ */
+export interface Consequence {
+  readonly lost: "nothing" | "page" | "session";
+  readonly repeat: "safe" | "check" | "pointless" | "resume";
+}
+
+/** What `error` leaves, from its reason and whether it was dispatched alone. */
+export const consequence = ({ reason, dispatched }: BrowserError): Consequence => {
+  const repeat = dispatched ? "check" : "safe";
+
+  switch (reason._tag) {
+    case "Closed":
+      return {
+        lost: reason.cause === "page" || reason.cause === "crashed" ? "page" : "session",
+        repeat,
+      };
+    case "Busy":
+    case "Timeout":
+    case "Failed":
+    case "NavigationFailed":
+      return { lost: "nothing", repeat };
+    case "EventHistoryExpired":
+      return { lost: "nothing", repeat: "resume" };
+    case "StaleRef":
+    case "NotFound":
+    case "NotActionable":
+    case "InvalidRequest":
+    case "Limit":
+    case "PolicyDenied":
+    case "PolicyTimeout":
+      return { lost: "nothing", repeat: "pointless" };
+  }
+};

package/src/BrowserEvent.ts

@@ -0,0 +1,294 @@
+/**
+ * What happened in a browser, in order: pages and their documents, actions, pointer motion, and
+ * the browser's own end.
+ *
+ * Every event carries `at`, host monotonic milliseconds from the owning browser’s Effect `Clock`.
+ * This clock also stamps screencast frames’ `receivedAt` and moments, so wall-clock corrections
+ * cannot disturb their order. Compare stamps only within the same browser clock, not across hosts.
+ * A page is named by its CDP target id, which stays the same across reconnects, and every URL is
+ * reported without its userinfo or known secret parameters.
+ *
+ * @since 0.3.0
+ */
+import { Schema } from "effect";
+
+import * as Motion from "./Motion.ts";
+
+/** A page opened, and the page that opened it, as a link or `window.open` does, if one did. */
+export class PageOpened extends Schema.TaggedClass<PageOpened>()("PageOpened", {
+  at: Schema.Finite,
+  page: Schema.String,
+  url: Schema.String,
+  opener: Schema.optional(Schema.String),
+}) {}
+
+/**
+ * The page closed (`page`), or crashed and was closed (`crashed`). A page lost with its browser
+ * has no event of its own: `Disconnected` stands for all of them.
+ */
+export class PageClosed extends Schema.TaggedClass<PageClosed>()("PageClosed", {
+  at: Schema.Finite,
+  page: Schema.String,
+  cause: Schema.Literals(["page", "crashed"]),
+}) {}
+
+/**
+ * A tab the site opened that the library could not track, as its registration failed with
+ * `detail`. A tab that closed as it opened has no event.
+ */
+export class PageUntracked extends Schema.TaggedClass<PageUntracked>()("PageUntracked", {
+  at: Schema.Finite,
+  url: Schema.String,
+  detail: Schema.String,
+}) {}
+
+/**
+ * The page's main frame moved to `url`: into a new document, or within the current one
+ * (`sameDocument`), as `pushState` and fragment links do. Frames carry the document they followed.
+ */
+export class Navigated extends Schema.TaggedClass<Navigated>()("Navigated", {
+  at: Schema.Finite,
+  page: Schema.String,
+  url: Schema.String,
+  /**
+   * The page's documents counted from 0, the one it had when this browser began tracking it, one
+   * more for each new document. The count belongs to the page within one `Browser` and starts at
+   * 0 again on a new connection, so compare it only with the same page's in the same browser.
+   */
+  document: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  sameDocument: Schema.Boolean,
+}) {}
+
+/** The page's document finished parsing (`domcontentloaded`) or loading (`load`). */
+export class PageLoaded extends Schema.TaggedClass<PageLoaded>()("PageLoaded", {
+  at: Schema.Finite,
+  page: Schema.String,
+  state: Schema.Literals(["domcontentloaded", "load"]),
+}) {}
+
+/**
+ * Why a browser was lost to its owner: its connection dropped (`connection`), its provider ended
+ * its session, at or after the session's `expiresAt` (`session`), or its owner released it.
+ */
+export const DisconnectCause = Schema.Literals(["connection", "session", "released"]);
+
+export type DisconnectCause = typeof DisconnectCause.Type;
+
+/** The browser was lost to its owner, with every page in it. It happens once. */
+export class Disconnected extends Schema.TaggedClass<Disconnected>()("Disconnected", {
+  at: Schema.Finite,
+  cause: DisconnectCause,
+}) {}
+
+/** The provider ends this browser's session at `expiresAt`, a wall-clock instant. */
+export class SessionEnding extends Schema.TaggedClass<SessionEnding>()("SessionEnding", {
+  at: Schema.Finite,
+  expiresAt: Schema.DateTimeUtc,
+}) {}
+
+/**
+ * The words around a subject that say which one it is, each bound to it in the page rather than
+ * read off nearby text later. In a table, `row` is the row's header or first cell with text and
+ * `column` the header over it; elsewhere, `label` is the words just before it in its row, item,
+ * group or block, at most 40 characters. `heading` is the nearest heading above it, left out for
+ * what is pinned to the viewport. Row, column and heading are at most 60 characters.
+ */
+export const SubjectContext = Schema.Struct({
+  row: Schema.optional(Schema.String),
+  column: Schema.optional(Schema.String),
+  label: Schema.optional(Schema.String),
+  heading: Schema.optional(Schema.String),
+});
+
+export type SubjectContext = typeof SubjectContext.Type;
+
+/**
+ * What an input acted on, or what `Page.find` found, as the page named it then: its role (null
+ * when it has none), its accessible name (empty when it has none), its lowercase tag and its
+ * context. For a point, it is the control under the point, or else the element painted there.
+ * Unlike a ref, it keeps its meaning after the page changes.
+ */
+export class Subject extends Schema.Class<Subject>("effect-browser/Subject")({
+  role: Schema.NullOr(Schema.String),
+  name: Schema.String,
+  tag: Schema.String,
+  context: SubjectContext,
+}) {}
+
+const Button = Schema.Literals(["left", "right", "middle"]);
+
+/** An element's box in viewport CSS pixels; it may lie partly or wholly outside the viewport. */
+export const Box = Schema.Struct({
+  x: Schema.Finite,
+  y: Schema.Finite,
+  width: Schema.Finite,
+  height: Schema.Finite,
+});
+
+export type Box = typeof Box.Type;
+
+/**
+ * What else an action was asked, where it changes what the action does: a click's button, count
+ * and hold, how `type` enters its text, how often and how long `press` holds its keys, how far
+ * `scroll` moves, and the options `select` chose. Only a completed action records them.
+ */
+export const ActionOptions = Schema.Struct({
+  button: Schema.optional(Button),
+  clickCount: Schema.optional(Schema.Finite),
+  holdMillis: Schema.optional(Schema.Finite),
+  replace: Schema.optional(Schema.Boolean),
+  submit: Schema.optional(Schema.Boolean),
+  times: Schema.optional(Schema.Finite),
+  dx: Schema.optional(Schema.Finite),
+  dy: Schema.optional(Schema.Finite),
+  values: Schema.optional(Schema.Array(Schema.String)),
+});
+
+export type ActionOptions = typeof ActionOptions.Type;
+
+/**
+ * One page operation ended, including one its caller interrupted (`error: "interrupted"`).
+ * `target` is what the caller asked for: a ref, a point, a URL or keys, and `options` the rest.
+ * `subject` is what an element or point action found there, and `to` where a drag ended; an
+ * action that failed before finding its target has neither. Point actions carry the viewport
+ * point they used. `correlation` is the id its caller gave it with `Page.correlate`, such as a
+ * model's tool call id.
+ */
+export class Action extends Schema.TaggedClass<Action>()("Action", {
+  at: Schema.Finite,
+  startedAt: Schema.Finite,
+  page: Schema.String,
+  name: Schema.String,
+  correlation: Schema.optional(Schema.String),
+  target: Schema.optional(Schema.String),
+  options: Schema.optional(ActionOptions),
+  subject: Schema.optional(Subject),
+  to: Schema.optional(Subject),
+  /** For an action at a point, the box of what it found there. */
+  box: Schema.optional(Box),
+  text: Schema.optional(Schema.String),
+  x: Schema.optional(Schema.Finite),
+  y: Schema.optional(Schema.Finite),
+  ok: Schema.Boolean,
+  dispatched: Schema.Boolean,
+  error: Schema.optional(Schema.String),
+}) {}
+
+const Sequence = Schema.Int.check(Schema.isGreaterThan(0));
+
+/** One whole glide, published before its first input. Offsets use the host monotonic clock. */
+export class TrackPlanned extends Schema.TaggedClass<TrackPlanned>()("TrackPlanned", {
+  at: Schema.Finite,
+  page: Schema.String,
+  from: Motion.Point,
+  samples: Motion.Plan,
+}) {}
+
+/**
+ * The submitted prefix of a glide. `plan` is its TrackPlanned envelope sequence; `dispatched`
+ * counts samples. `complete` means every sample was submitted, not acknowledged by the browser.
+ * The terminal point clips a canceled plan so a compositor never draws its unrealized future.
+ */
+export class TrackPerformed extends Schema.TaggedClass<TrackPerformed>()("TrackPerformed", {
+  at: Schema.Finite,
+  page: Schema.String,
+  plan: Sequence,
+  dispatched: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  x: Schema.Finite,
+  y: Schema.Finite,
+  complete: Schema.Boolean,
+}) {}
+
+export class PointerPressed extends Schema.TaggedClass<PointerPressed>()("PointerPressed", {
+  at: Schema.Finite,
+  page: Schema.String,
+  x: Schema.Finite,
+  y: Schema.Finite,
+  button: Button,
+  clickCount: Schema.Int.check(Schema.isGreaterThan(0)),
+}) {}
+
+export class PointerReleased extends Schema.TaggedClass<PointerReleased>()("PointerReleased", {
+  at: Schema.Finite,
+  page: Schema.String,
+  x: Schema.Finite,
+  y: Schema.Finite,
+  button: Button,
+  clickCount: Schema.Int.check(Schema.isGreaterThan(0)),
+}) {}
+
+export class WheelScrolled extends Schema.TaggedClass<WheelScrolled>()("WheelScrolled", {
+  at: Schema.Finite,
+  page: Schema.String,
+  x: Schema.Finite,
+  y: Schema.Finite,
+  dx: Schema.Finite,
+  dy: Schema.Finite,
+}) {}
+
+export class KeyChanged extends Schema.TaggedClass<KeyChanged>()("KeyChanged", {
+  at: Schema.Finite,
+  page: Schema.String,
+  key: Schema.String,
+  phase: Schema.Literals(["down", "up"]),
+}) {}
+
+/** Literal text insertion has no corresponding key events, including Unicode and newlines. */
+export class TextInserted extends Schema.TaggedClass<TextInserted>()("TextInserted", {
+  at: Schema.Finite,
+  page: Schema.String,
+  text: Schema.String,
+}) {}
+
+/** The target's CSS cursor, obtained during target resolution without another browser call. */
+export class CursorChanged extends Schema.TaggedClass<CursorChanged>()("CursorChanged", {
+  at: Schema.Finite,
+  page: Schema.String,
+  cursor: Schema.String,
+}) {}
+
+export const TrackEvent = Schema.Union([
+  TrackPlanned,
+  TrackPerformed,
+  PointerPressed,
+  PointerReleased,
+  WheelScrolled,
+  KeyChanged,
+  TextInserted,
+  CursorChanged,
+]);
+
+export type TrackEvent = typeof TrackEvent.Type;
+
+/**
+ * A JavaScript dialog appeared and was answered: an alert or a leave-page prompt accepted, a
+ * confirm or a prompt dismissed, as if its Cancel were pressed.
+ */
+export class DialogShown extends Schema.TaggedClass<DialogShown>()("DialogShown", {
+  at: Schema.Finite,
+  page: Schema.String,
+  kind: Schema.String,
+  message: Schema.String,
+  answer: Schema.Literals(["accepted", "dismissed"]),
+}) {}
+
+export const BrowserEvent = Schema.Union([
+  PageOpened,
+  PageClosed,
+  PageUntracked,
+  Navigated,
+  PageLoaded,
+  Action,
+  ...TrackEvent.members,
+  DialogShown,
+  Disconnected,
+  SessionEnding,
+]);
+
+export type BrowserEvent = typeof BrowserEvent.Type;
+
+/** A position in the browser's one replayable event history. Sequences begin at one. */
+export class RecordedEvent extends Schema.Class<RecordedEvent>("effect-browser/RecordedEvent")({
+  sequence: Sequence,
+  event: BrowserEvent,
+}) {}

package/src/Cdp.ts

@@ -0,0 +1,101 @@
+/**
+ * A browser reached over the Chrome DevTools Protocol: a Chrome started with
+ * `--remote-debugging-port`, or any provider that hands out a CDP WebSocket URL.
+ *
+ * Closing the scope disconnects. It does not close the remote browser; its owner does that.
+ *
+ * @since 0.3.0
+ */
+import { type DateTime, Effect, Layer, Redacted } from "effect";
+import { chromium } from "playwright-core";
+
+import * as Browser from "./Browser.ts";
+import { type BrowserError, Failed, type Reason } from "./BrowserError.ts";
+import { reasonOf, undispatched } from "./internal/page/context.ts";
+import * as Url from "./internal/page/url.ts";
+
+export interface Options extends Browser.Options {
+  /**
+   * `ws://`, `wss://` or `http://` DevTools endpoint. Often a credential, so it may be redacted;
+   * connect failures never include its userinfo, path or query.
+   */
+  readonly endpoint: string | Redacted.Redacted<string>;
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+  /** Identifies the session in `Browser.id`. Defaults to `"cdp"`. */
+  readonly id?: string | undefined;
+  readonly provider?: string | undefined;
+  /** Bound on connecting. Defaults to 30 seconds. */
+  readonly connectTimeoutMillis?: number | undefined;
+  /** When the provider ends the session on its own, as a hosted session's timeout does. */
+  readonly expiresAt?: DateTime.Utc | undefined;
+  /**
+   * A connection apart from this one for the pages' screencasts, as a hosted provider supplies.
+   * Without one, each page's capture runs on its own session.
+   */
+  readonly capture?: Browser.CaptureSource | undefined;
+}
+
+/**
+ * Playwright can echo the endpoint, or a URL derived from it with its query, userinfo or path, in
+ * a connect failure. Those parts are often the credential, so a URL keeps its scheme, host and
+ * port, and any other echo of the endpoint is replaced.
+ */
+const withoutEndpoint = (endpoint: string, reason: Reason): Reason => {
+  if (reason._tag !== "Failed") return reason;
+
+  const origins = reason.detail.replace(Url.quoted, (url) => {
+    const parsed = URL.parse(url);
+
+    return parsed === null || parsed.host === "" ? "<url>" : `${parsed.protocol}//${parsed.host}`;
+  });
+
+  return new Failed({
+    detail: endpoint === "" ? origins : origins.replaceAll(endpoint, "<endpoint>"),
+  });
+};
+
+/** Connect and open a `Browser` over the endpoint's first context. */
+export const open = Effect.fn("Cdp.open")(function* (options: Options) {
+  const endpoint = Redacted.isRedacted(options.endpoint)
+    ? Redacted.value(options.endpoint)
+    : options.endpoint;
+
+  const timeout = options.connectTimeoutMillis ?? 30_000;
+
+  const failed = (cause: unknown, timeoutMillis?: number) =>
+    undispatched("connect", withoutEndpoint(endpoint, reasonOf(cause, timeoutMillis)));
+
+  // The endpoint is often a credential, so the connect span names no part of it.
+  const connected = yield* Effect.acquireRelease(
+    Effect.tryPromise({
+      try: () =>
+        chromium.connectOverCDP(endpoint, {
+          timeout,
+          ...(options.headers === undefined ? {} : { headers: { ...options.headers } }),
+        }),
+      catch: (cause) => failed(cause, timeout),
+    }).pipe(Effect.withSpan("Cdp.connect", {}, { captureStackTrace: false })),
+    (browser) => Effect.tryPromise(() => browser.close()).pipe(Effect.ignore),
+  );
+
+  const context =
+    connected.contexts()[0] ??
+    (yield* Effect.tryPromise({
+      try: () => connected.newContext(),
+      catch: (cause) => failed(cause),
+    }));
+
+  return yield* Browser.make(
+    context,
+    {
+      id: options.id ?? "cdp",
+      provider: options.provider ?? "cdp",
+      expiresAt: options.expiresAt,
+      capture: options.capture,
+    },
+    options,
+  );
+});
+
+export const layer = (options: Options): Layer.Layer<Browser.Browser, BrowserError> =>
+  Layer.effect(Browser.Browser, open(options));