effect-browserbase 0.2.0-beta.8 → 0.3.0-beta.10

package/src/ContextLease.ts

@@ -0,0 +1,118 @@
+/**
+ * Who may write a stored context. A session that persists to a context saves to it when the
+ * session ends, so two at once can lose one's changes. `Browserbase.open` holds a context through
+ * its `ContextLease` from before it creates a persisting session until that session has ended and
+ * its save has settled, and the next writer waits. `verifyContext` and `reconcile` hold it too.
+ *
+ * The lease is a port. `layer` holds contexts within the process that builds it. An application
+ * whose writers run in several processes provides its own, such as an advisory lock in its
+ * database, and so excludes them all.
+ *
+ * A hold also passes on how the writer before left the context: `unsettled` while a session that
+ * saves to it may still run, as when that writer's release was left unconfirmed, its create's answer
+ * was lost, or it kept its session past its scope. The next writer then ends the context's sessions
+ * before it writes. A writer says how it leaves the context once, as it lets the hold go; a hold
+ * that never says, as when its process ends first, must read as `unsettled` to the next.
+ *
+ * @since 0.3.0
+ */
+import { Context, Effect, Layer, Schema, type Scope, Semaphore } from "effect";
+
+/**
+ * The stored context could not be held for writing: a session that saves to it may still run, as
+ * its sessions could not be confirmed ended, or the lease itself could not be taken. The next try
+ * clears it again.
+ */
+export class ContextHeld extends Schema.TaggedError<ContextHeld>()("ContextHeld", {
+  context: Schema.String,
+  detail: Schema.String,
+}) {
+  override get message() {
+    return `context ${this.context} is held: ${this.detail}`;
+  }
+}
+
+/** A writer's hold on a stored context, for the scope `hold` was given. */
+export interface Hold {
+  /** Whether a session that saves to the context may still run, as the writer before left it. */
+  readonly unsettled: boolean;
+  /** Say how this writer leaves the context, once, before the hold goes: the next writer reads it. */
+  readonly leave: (unsettled: boolean) => Effect.Effect<void>;
+}
+
+export interface Service {
+  /**
+   * Hold the context as its only writer until the scope closes, waiting while another holds it.
+   * It fails with `ContextHeld` when the lease cannot be taken, as when its own store is down.
+   */
+  readonly hold: (context: string) => Effect.Effect<Hold, ContextHeld, Scope.Scope>;
+}
+
+export class ContextLease extends Context.Service<ContextLease, Service>()(
+  "effect-browserbase/ContextLease",
+) {}
+
+interface Entry {
+  readonly lock: Semaphore.Semaphore;
+  unsettled: boolean;
+  /** Its holder and the writers waiting for it. */
+  users: number;
+}
+
+/**
+ * The lease within this process: one writer at a time for each stored context. A context it has
+ * not held is presumed settled, so writers in other processes are the application's to exclude,
+ * with a lease of its own. It forgets a context once nobody holds it, or waits for it, and it was
+ * left settled.
+ */
+export const layer: Layer.Layer<ContextLease> = Layer.sync(ContextLease, () => {
+  const contexts = new Map<string, Entry>();
+
+  const enter = (context: string) => {
+    const entry = contexts.get(context) ?? {
+      lock: Semaphore.makeUnsafe(1),
+      unsettled: false,
+      users: 0,
+    };
+
+    entry.users += 1;
+    contexts.set(context, entry);
+
+    return entry;
+  };
+
+  const exit = (context: string, entry: Entry) => {
+    entry.users -= 1;
+    if (entry.users === 0 && !entry.unsettled) contexts.delete(context);
+  };
+
+  return ContextLease.of({
+    hold: (context) =>
+      Effect.gen(function* () {
+        const entry = yield* Effect.acquireRelease(
+          Effect.sync(() => enter(context)),
+          (entered) => Effect.sync(() => exit(context, entered)),
+        );
+
+        // Unless the holder says otherwise, it leaves a session that saves to the context running.
+        let leaving = true;
+
+        yield* Effect.acquireRelease(
+          entry.lock.take(1),
+          () =>
+            Effect.sync(() => {
+              entry.unsettled = leaving;
+            }).pipe(Effect.andThen(entry.lock.release(1))),
+          { interruptible: true },
+        );
+
+        return {
+          unsettled: entry.unsettled,
+          leave: (unsettled) =>
+            Effect.sync(() => {
+              leaving = unsettled;
+            }),
+        } satisfies Hold;
+      }),
+  });
+});

package/src/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @since 0.3.0
+ */
+export * as Browserbase from "./Browserbase.ts";
+export * as BrowserbaseClient from "./BrowserbaseClient.ts";
+export * as BrowserbaseError from "./BrowserbaseError.ts";
+export * as ContextLease from "./ContextLease.ts";

package/src/internal/captureConnection.ts

@@ -0,0 +1,214 @@
+/**
+ * The capture connection: a second DevTools connection to a session, for its pages' screencasts
+ * alone. A frame and its acknowledgement then never wait behind a large message on the
+ * connection Playwright drives the pages over, such as an upload or a read's answer: Browserbase
+ * refuses compression, and on air those waits stopped the picture for as long as the message took
+ * to cross.
+ *
+ * Raw CDP over the global WebSocket, with no Playwright. A page's session on it sends only the
+ * capture's commands, and receives that page's events. The connection opens as the first capture
+ * starts and stays until the scope closes, which closes it and waits, bounded, for it to close;
+ * one that fails ends every page's session on it, and the next capture opens another.
+ */
+import { Duration, Effect, Option, Redacted, Schema, Semaphore } from "effect";
+import type { CaptureSource } from "effect-browser/Browser";
+import { BrowserError, Failed } from "effect-browser/BrowserError";
+
+const Message = Schema.fromJsonString(
+  Schema.Struct({
+    id: Schema.optionalKey(Schema.Int),
+    sessionId: Schema.optionalKey(Schema.String),
+    method: Schema.optionalKey(Schema.String),
+    params: Schema.optionalKey(Schema.Unknown),
+    result: Schema.optionalKey(Schema.Unknown),
+    error: Schema.optionalKey(Schema.Struct({ message: Schema.String })),
+  }),
+);
+
+const Session = Schema.Struct({ sessionId: Schema.String });
+
+type Listener = Parameters<CaptureSource["attach"]>[1];
+
+interface Open {
+  readonly socket: WebSocket;
+  /** Replies awaited, by command id. */
+  readonly replies: Map<
+    number,
+    { readonly resolve: (result: unknown) => void; readonly reject: (error: BrowserError) => void }
+  >;
+  /** Each attached page's listener, by its session id. */
+  readonly sessions: Map<string, Listener>;
+}
+
+type State =
+  | { readonly _tag: "Idle" }
+  | { readonly _tag: "Open"; readonly open: Open }
+  | { readonly _tag: "Closed" };
+
+const failure = (detail: string) =>
+  new BrowserError({ operation: "screencast", reason: new Failed({ detail }), dispatched: false });
+
+const closing = Duration.seconds(2);
+
+/** The capture connection to the DevTools address `url`, for the scope. */
+export const make = Effect.fnUntraced(function* (url: Redacted.Redacted<string>) {
+  let state: State = { _tag: "Idle" };
+  let ids = 0;
+  const opening = yield* Semaphore.make(1);
+
+  // A failure ends every page's session on the connection; the next capture opens another.
+  const lose = (open: Open, error: BrowserError) => {
+    if (state._tag !== "Open" || state.open !== open) return;
+    state = { _tag: "Idle" };
+    for (const reply of open.replies.values()) reply.reject(error);
+    for (const listener of open.sessions.values()) listener.lost(error);
+    open.replies.clear();
+    open.sessions.clear();
+  };
+
+  const receive = (open: Open, data: unknown) => {
+    const decoded = typeof data === "string" ? Schema.decodeOption(Message)(data) : Option.none();
+
+    if (Option.isNone(decoded))
+      return lose(open, failure("the capture connection sent a message it could not read"));
+    const { id, sessionId, method, params, result, error } = decoded.value;
+
+    if (id !== undefined) {
+      const reply = open.replies.get(id);
+
+      open.replies.delete(id);
+      if (error === undefined) reply?.resolve(result);
+      else reply?.reject(failure(error.message));
+    } else if (method === undefined) return;
+    else if (sessionId !== undefined) open.sessions.get(sessionId)?.event(method, params);
+    // The connection's own session announces that a page's session ended.
+    else if (method === "Target.detachedFromTarget") {
+      const detached = Schema.decodeUnknownOption(Session)(params);
+      const ended = Option.isSome(detached) ? detached.value.sessionId : "";
+      const listener = open.sessions.get(ended);
+
+      open.sessions.delete(ended);
+      listener?.event(method, params);
+    }
+  };
+
+  const send = (
+    open: Open,
+    method: string,
+    params: Record<string, unknown> | undefined,
+    sessionId?: string,
+  ) => {
+    if (state._tag !== "Open" || state.open !== open)
+      return Promise.reject(failure("the capture connection was lost"));
+    const id = ++ids;
+    const { promise, resolve, reject } = Promise.withResolvers<unknown>();
+
+    open.replies.set(id, { resolve, reject });
+    try {
+      open.socket.send(JSON.stringify({ id, method, params, sessionId }));
+    } catch {
+      open.replies.delete(id);
+      reject(failure("the capture connection could not send"));
+    }
+
+    return promise;
+  };
+
+  const connect = Effect.callback<Open, BrowserError>((resume) => {
+    const socket = new WebSocket(Redacted.value(url));
+    const open: Open = { socket, replies: new Map(), sessions: new Map() };
+
+    const unopened = () => resume(Effect.fail(failure("the capture connection did not open")));
+
+    socket.addEventListener("close", unopened, { once: true });
+    socket.addEventListener(
+      "open",
+      () => {
+        socket.removeEventListener("close", unopened);
+        // A scope that closed meanwhile keeps no connection.
+        if (state._tag === "Closed") {
+          socket.close(1000);
+
+          return resume(Effect.fail(failure("the capture connection is closed")));
+        }
+        state = { _tag: "Open", open };
+        socket.addEventListener("close", () =>
+          lose(open, failure("the capture connection was lost")),
+        );
+        resume(Effect.succeed(open));
+      },
+      { once: true },
+    );
+    socket.addEventListener("message", ({ data }: MessageEvent<unknown>) => receive(open, data));
+
+    return Effect.sync(() => socket.close(1000));
+  });
+
+  const current = opening.withPermits(1)(
+    Effect.suspend(() =>
+      state._tag === "Open"
+        ? Effect.succeed(state.open)
+        : state._tag === "Closed"
+          ? Effect.fail(failure("the capture connection is closed"))
+          : connect,
+    ),
+  );
+
+  const replied = (reply: () => Promise<unknown>) =>
+    Effect.tryPromise({
+      try: reply,
+      catch: (cause) =>
+        Schema.is(BrowserError)(cause) ? cause : failure("the capture connection failed"),
+    });
+
+  const attach: CaptureSource["attach"] = (target, listener) =>
+    Effect.gen(function* () {
+      const open = yield* current;
+
+      const { sessionId } = yield* replied(() =>
+        send(open, "Target.attachToTarget", { targetId: target, flatten: true }),
+      ).pipe(
+        Effect.flatMap((result) =>
+          Schema.decodeUnknownEffect(Session)(result).pipe(
+            Effect.mapError(() => failure("the capture connection's attach had no session")),
+          ),
+        ),
+      );
+
+      open.sessions.set(sessionId, listener);
+      // Detached as the page's scope closes; a connection that closes detaches every session.
+      yield* Effect.addFinalizer(() =>
+        Effect.sync(() => {
+          if (open.sessions.delete(sessionId))
+            void send(open, "Target.detachFromTarget", { sessionId }, undefined).catch(
+              () => undefined,
+            );
+        }),
+      );
+
+      return (method, params) => send(open, method, params, sessionId);
+    });
+
+  // Closing the scope closes the connection and waits, bounded, until it has closed.
+  yield* Effect.addFinalizer(() =>
+    Effect.suspend(() => {
+      const previous = state;
+
+      state = { _tag: "Closed" };
+      if (previous._tag !== "Open") return Effect.void;
+      const { socket, replies, sessions } = previous.open;
+
+      for (const reply of replies.values()) reply.reject(failure("the capture connection closed"));
+      replies.clear();
+      sessions.clear();
+
+      return Effect.callback<void>((resume) => {
+        if (socket.readyState === WebSocket.CLOSED) return resume(Effect.void);
+        socket.addEventListener("close", () => resume(Effect.void), { once: true });
+        socket.close(1000);
+      }).pipe(Effect.timeoutOrElse({ duration: closing, orElse: () => Effect.void }));
+    }),
+  );
+
+  return { attach } satisfies CaptureSource;
+});

package/src/testing/BrowserbaseContract.ts

@@ -0,0 +1,170 @@
+/**
+ * What this package relies on the Browserbase API to do, as named checks over
+ * `BrowserbaseClient`, each an Effect with no test runner around it. A package test runs them
+ * against `TestBrowserbase`, which keeps the fake to them; run against Browserbase itself, they
+ * show whether the fake is still faithful, at the cost of a few one-minute sessions. Checks that
+ * move the test clock run only against the fake.
+ *
+ * @category testing
+ * @since 0.3.0
+ */
+import { Clock, Effect, Schedule, Schema } from "effect";
+import { TestClock } from "effect/testing";
+
+import { BrowserbaseClient, type Session } from "../BrowserbaseClient.ts";
+import type { BrowserbaseError } from "../BrowserbaseError.ts";
+
+/** A check found the API behaving otherwise. */
+export class Broken extends Schema.TaggedError<Broken>()("Broken", {
+  check: Schema.String,
+  detail: Schema.String,
+}) {
+  override get message() {
+    return `${this.check}: ${this.detail}`;
+  }
+}
+
+export interface Check {
+  readonly name: string;
+  /** It moves the test clock, so only the fake can run it. */
+  readonly clock: boolean;
+  readonly run: Effect.Effect<void, Broken | BrowserbaseError, BrowserbaseClient>;
+}
+
+const check = (
+  name: string,
+  run: (
+    expect: (holds: boolean, detail: string) => Effect.Effect<void, Broken>,
+  ) => Effect.Effect<void, Broken | BrowserbaseError, BrowserbaseClient>,
+  clock = false,
+): Check => ({
+  name,
+  clock,
+  run: run((holds, detail) =>
+    holds ? Effect.void : Effect.fail(new Broken({ check: name, detail })),
+  ).pipe(Effect.withSpan("BrowserbaseContract.check", { attributes: { check: name } })),
+});
+
+const running = (session: Session) => session.status === "PENDING" || session.status === "RUNNING";
+
+/** What the call failed with, or `nothing` when it succeeded. */
+const failure = <A, R>(call: Effect.Effect<A, BrowserbaseError, R>) =>
+  Effect.match(call, { onFailure: (error) => error.reason._tag, onSuccess: () => "nothing" });
+
+/** Read the session until it has ended, for at most 10 seconds. */
+const ended = (client: BrowserbaseClient["Service"], id: string) =>
+  client.getSession(id).pipe(
+    Effect.repeat({
+      until: (session) => !running(session),
+      schedule: Schedule.spaced("1 second").pipe(Schedule.upTo({ times: 10 })),
+    }),
+  );
+
+export const checks: ReadonlyArray<Check> = [
+  check("a new session runs, and ends once released", (expect) =>
+    Effect.gen(function* () {
+      const client = yield* BrowserbaseClient;
+      const session = yield* client.createSession({ timeout: 60 });
+
+      yield* expect(running(session), `a new session is ${session.status}`);
+      yield* client.releaseSession(session.id);
+      const after = yield* ended(client, session.id);
+
+      yield* expect(after.status === "COMPLETED", `a released session is ${after.status}`);
+      // Releasing a session that has ended succeeds and changes nothing.
+      yield* client.releaseSession(session.id);
+      const again = yield* client.getSession(session.id);
+
+      yield* expect(again.status === "COMPLETED", `released twice, it is ${again.status}`);
+    }),
+  ),
+  check("a well-formed id no session has is not found", (expect) =>
+    Effect.gen(function* () {
+      const client = yield* BrowserbaseClient;
+      const read = yield* failure(client.getSession("00000000-0000-4000-8000-000000000000"));
+
+      yield* expect(read === "NotFound", `reading it failed with ${read}`);
+    }),
+  ),
+  check("a session id of another shape is refused as invalid", (expect) =>
+    Effect.gen(function* () {
+      const client = yield* BrowserbaseClient;
+      const read = yield* failure(client.getSession("not-a-session-of-this-project"));
+
+      yield* expect(read === "InvalidRequest", `reading it failed with ${read}`);
+    }),
+  ),
+  check("sessions are found by status and user metadata", (expect) =>
+    Effect.gen(function* () {
+      const client = yield* BrowserbaseClient;
+      const label = `contract-${yield* Clock.currentTimeMillis}`;
+      const session = yield* client.createSession({ timeout: 60, userMetadata: { label } });
+      const query = (value: string) => `user_metadata['label']:'${value}'`;
+
+      // A new session is PENDING or RUNNING, and may change between the two queries, so the
+      // package looks under both statuses; a check of one alone would fail a compliant API.
+      const running = (value: string) =>
+        Effect.map(
+          Effect.forEach(["PENDING", "RUNNING"], (status) =>
+            client.listSessions({ status, query: query(value) }),
+          ),
+          (found) => new Set(found.flat().map(({ id }) => id)),
+        );
+
+      const found = yield* running(label);
+      const other = yield* running(`${label}-x`);
+
+      yield* client.releaseSession(session.id);
+      yield* ended(client, session.id);
+      const gone = yield* running(label);
+      // With no status, a search finds sessions in every state, as a lost create's search needs.
+      const any = yield* client.listSessions({ query: query(label) });
+
+      yield* expect(
+        found.size === 1 && found.has(session.id),
+        `${found.size} unended sessions had its label`,
+      );
+      yield* expect(other.size === 0, `${other.size} sessions had another label`);
+      yield* expect(gone.size === 0, `${gone.size} still ran once it had ended`);
+      yield* expect(
+        any.some(({ id, status }) => id === session.id && status === "COMPLETED"),
+        `with no status, a search found ${any.length} sessions, not it ended`,
+      );
+    }),
+  ),
+  check("a context id of another shape is refused as invalid", (expect) =>
+    Effect.gen(function* () {
+      const client = yield* BrowserbaseClient;
+      const read = yield* failure(client.getContext("not-a-context-of-this-project"));
+
+      yield* expect(read === "InvalidRequest", `reading it failed with ${read}`);
+    }),
+  ),
+  check("a stored context reads back, and is gone once deleted", (expect) =>
+    Effect.gen(function* () {
+      const client = yield* BrowserbaseClient;
+      const created = yield* client.createContext();
+      const read = yield* client.getContext(created.id);
+
+      yield* client.deleteContext(created.id);
+      const gone = yield* failure(client.getContext(created.id));
+
+      yield* expect(read.id === created.id, `it read back as ${read.id}`);
+      yield* expect(gone === "NotFound", `once deleted, reading it failed with ${gone}`);
+    }),
+  ),
+  check(
+    "a session ends at its timeout",
+    (expect) =>
+      Effect.gen(function* () {
+        const client = yield* BrowserbaseClient;
+        const session = yield* client.createSession({ timeout: 60 });
+
+        yield* TestClock.adjust("61 seconds");
+        const after = yield* client.getSession(session.id);
+
+        yield* expect(after.status === "TIMED_OUT", `after its timeout it is ${after.status}`);
+      }),
+    true,
+  ),
+];