browser-commander 0.20.0 → 0.21.1

package/src/cli/dispatcher.js

@@ -0,0 +1,99 @@
+/**
+ * The one dispatcher behind `serve --stdio` and `run` (issue #104).
+ *
+ * It owns the handle table, the sessions and the event subscriptions of one
+ * connection, and maps a JSON-RPC method name and params to a result or a
+ * thrown error. Transports (the stdio server and the script runner) only
+ * frame messages around it.
+ */
+import { HANDLE_METHODS, removeSubscription } from './handle-methods.js';
+import { HandleTable } from './handles.js';
+import { HIGH_LEVEL_METHODS } from './high-level-methods.js';
+import { DEFAULT_DEPENDENCIES } from './modules.js';
+import { RPC_ERROR, RpcError, invalidParams } from './rpc-error.js';
+import { SessionTable } from './sessions.js';
+
+const METHODS = Object.freeze({ ...HIGH_LEVEL_METHODS, ...HANDLE_METHODS });
+
+/** Every method name the dispatcher answers. */
+export const METHOD_NAMES = Object.freeze(Object.keys(METHODS).sort());
+
+/**
+ * Create a dispatcher.
+ *
+ * @param {Object} [options]
+ * @param {Object} [options.dependencies] - Replacements for {@link DEFAULT_DEPENDENCIES}
+ * @param {function(string, Object): void} [options.notify] - Sends a server notification (`events.emit`)
+ * @returns {{dispatch: function(string, Object=): Promise<unknown>, close: function(): Promise<void>, state: Object}}
+ */
+export function createDispatcher({
+  dependencies = {},
+  notify = () => {},
+} = {}) {
+  const state = {
+    dependencies: { ...DEFAULT_DEPENDENCIES, ...dependencies },
+    handles: new HandleTable(),
+    sessions: new SessionTable(),
+    subscriptions: new Map(),
+    nextSubscription: 1,
+    relay: null,
+    notify,
+  };
+
+  async function dispatch(method, params = {}) {
+    if (typeof method !== 'string' || !Object.hasOwn(METHODS, method)) {
+      throw new RpcError(
+        RPC_ERROR.METHOD_NOT_FOUND,
+        `Unknown method: ${method}`
+      );
+    }
+    if (
+      params === null ||
+      typeof params !== 'object' ||
+      Array.isArray(params)
+    ) {
+      throw invalidParams('params must be an object');
+    }
+    return await METHODS[method](state, params);
+  }
+
+  /** Remove every subscription, close every session and the relay. */
+  async function close() {
+    for (const subscription of [...state.subscriptions.keys()]) {
+      removeSubscription(state, subscription);
+    }
+    const { relay } = state;
+    state.relay = null;
+    await Promise.all([
+      state.sessions.closeAll(),
+      relay?.close().catch(() => {}),
+    ]);
+  }
+
+  return { dispatch, close, state };
+}
+
+/**
+ * Replace `"$session"` anywhere in params with the latest session id.
+ *
+ * @param {unknown} value - Step params
+ * @param {string|null} session - Latest session id
+ * @returns {unknown}
+ */
+export function substituteSession(value, session) {
+  if (value === '$session') {
+    return session ?? value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => substituteSession(item, session));
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        key,
+        substituteSession(item, session),
+      ])
+    );
+  }
+  return value;
+}

package/src/cli/handle-methods.js

@@ -0,0 +1,136 @@
+/**
+ * Generic handle methods (docs/cli-and-bridge.md, "Generic handle methods").
+ *
+ * They reach every public method of Playwright and Puppeteer through remote
+ * object handles, so a Rust or Python program - or a shell script - can call
+ * `page.route()`, `locator.boundingBox()` or `cdpSession.send()` without a
+ * native binding for each of them.
+ */
+import { decodeValue, describeObject, encodeValue } from './handles.js';
+import { invalidParams, requireString } from './rpc-error.js';
+
+const ENGINE_ROOTS = Object.freeze(['playwright', 'puppeteer']);
+
+function targetOf(state, params) {
+  const handle = params.handle;
+  const id = typeof handle === 'object' && handle ? handle.$handle : handle;
+  return state.handles.get(requireString({ id }, 'id'));
+}
+
+/** Roots are always handles, even when the engine object is a plain object. */
+function handleOrNull(state, value) {
+  return value === null || value === undefined
+    ? null
+    : state.handles.register(value);
+}
+
+/**
+ * `playwright` and `puppeteer` resolve to the engine's entry object;
+ * `session:<id>` to the session's browser, context and page.
+ */
+async function root(state, params) {
+  const name = requireString(params, 'name');
+  if (name.startsWith('session:')) {
+    const session = state.sessions.get(name.slice('session:'.length));
+    return {
+      browser: handleOrNull(state, session.browser),
+      context: handleOrNull(state, session.context),
+      page: handleOrNull(state, session.page),
+    };
+  }
+  if (!ENGINE_ROOTS.includes(name)) {
+    throw invalidParams(
+      `Unknown root "${name}"; expected playwright, puppeteer or session:<id>`
+    );
+  }
+  const module = await state.dependencies.loadEngine(name);
+  return state.handles.register(module.default ?? module);
+}
+
+async function call(state, params) {
+  const target = targetOf(state, params);
+  const method = requireString(params, 'method');
+  const args = params.args ?? [];
+  if (!Array.isArray(args)) {
+    throw invalidParams('args must be an array');
+  }
+  if (typeof target?.[method] !== 'function') {
+    throw invalidParams(`${method} is not a method of this handle`);
+  }
+  const result = await target[method](...decodeValue(args, state.handles));
+  return encodeValue(result, state.handles);
+}
+
+async function get(state, params) {
+  const target = targetOf(state, params);
+  const property = requireString(params, 'property');
+  const value = target?.[property];
+  return encodeValue(
+    value instanceof Promise ? await value : value,
+    state.handles
+  );
+}
+
+function dispose(state, params) {
+  const id =
+    typeof params.handle === 'object' && params.handle
+      ? params.handle.$handle
+      : params.handle;
+  if (!state.handles.dispose(requireString({ id }, 'id'))) {
+    throw invalidParams(`Unknown handle: ${id}`);
+  }
+  return { disposed: true };
+}
+
+function describe(state, params) {
+  return describeObject(targetOf(state, params));
+}
+
+function subscribe(state, params) {
+  const target = targetOf(state, params);
+  const event = requireString(params, 'event');
+  if (typeof target?.on !== 'function') {
+    throw invalidParams('This handle does not emit events');
+  }
+  const subscription = `e${state.nextSubscription++}`;
+  const listener = (...args) =>
+    state.notify('events.emit', {
+      subscription,
+      args: args.map((arg) => encodeValue(arg, state.handles)),
+    });
+  target.on(event, listener);
+  state.subscriptions.set(subscription, { target, event, listener });
+  return { subscription };
+}
+
+/** Remove one subscription's listener. */
+export function removeSubscription(state, subscription) {
+  const entry = state.subscriptions.get(subscription);
+  if (!entry) {
+    return false;
+  }
+  state.subscriptions.delete(subscription);
+  const { target, event, listener } = entry;
+  const off = target.off ?? target.removeListener;
+  off?.call(target, event, listener);
+  return true;
+}
+
+function unsubscribe(state, params) {
+  const subscription = requireString(params, 'subscription');
+  if (!removeSubscription(state, subscription)) {
+    throw invalidParams(`Unknown subscription: ${subscription}`);
+  }
+  return { unsubscribed: true };
+}
+
+/** Method name to implementation. */
+export const HANDLE_METHODS = Object.freeze({
+  'handle.root': root,
+  'handle.call': call,
+  'handle.get': get,
+  'handle.dispose': dispose,
+  'handle.describe': describe,
+  'events.subscribe': subscribe,
+  'events.unsubscribe': unsubscribe,
+});

package/src/cli/handles.js

@@ -0,0 +1,273 @@
+/**
+ * Remote object handles and the value encoding of the `serve --stdio` bridge
+ * (issue #104, docs/cli-and-bridge.md "Value encoding").
+ *
+ * JSON values cross the bridge unchanged. Anything else - an engine object, a
+ * function, a buffer, a date - is tagged, so a client in any language can hold
+ * a Playwright `Page` or a Puppeteer `ElementHandle` as `{"$handle": "h3"}`
+ * and pass it back as an argument.
+ */
+import { invalidParams } from './rpc-error.js';
+
+const TAGS = Object.freeze([
+  '$handle',
+  '$binary',
+  '$function',
+  '$undefined',
+  '$date',
+  '$regexp',
+  '$bigint',
+  '$error',
+]);
+
+function isModuleNamespace(value) {
+  return Object.prototype.toString.call(value) === '[object Module]';
+}
+
+/** True for `{}` literals and null-prototype records, not class instances. */
+export function isPlainObject(value) {
+  if (value === null || typeof value !== 'object' || isModuleNamespace(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function isBinary(value) {
+  return value instanceof Uint8Array || value instanceof ArrayBuffer;
+}
+
+/**
+ * The class name a client sees for a handle.
+ *
+ * Bundlers rename colliding classes (`Page2`), so a trailing number after a
+ * lowercase letter is dropped to keep the public name.
+ */
+export function typeName(value) {
+  if (typeof value === 'function') {
+    return 'Function';
+  }
+  const name = value?.constructor?.name;
+  if (!name || isModuleNamespace(value)) {
+    return 'Object';
+  }
+  return name.replace(/(?<=[a-z])\d+$/u, '');
+}
+
+/**
+ * A table of remote objects with deterministic ids (`h1`, `h2`, …).
+ *
+ * The same object always gets the same id while it is registered, so a page
+ * returned by two calls is one handle.
+ */
+export class HandleTable {
+  constructor() {
+    this.nextId = 1;
+    this.byId = new Map();
+    this.idOf = new Map();
+  }
+
+  /** Register an object (or reuse its id) and return the encoded handle. */
+  register(value) {
+    let id = this.idOf.get(value);
+    if (!id) {
+      id = `h${this.nextId++}`;
+      this.byId.set(id, value);
+      this.idOf.set(value, id);
+    }
+    return { $handle: id, type: typeName(value) };
+  }
+
+  /** The object behind an id, or an invalid-params error. */
+  get(id) {
+    if (!this.byId.has(id)) {
+      throw invalidParams(`Unknown handle: ${id}`);
+    }
+    return this.byId.get(id);
+  }
+
+  /** Forget a handle. Returns whether it existed. */
+  dispose(id) {
+    if (!this.byId.has(id)) {
+      return false;
+    }
+    this.idOf.delete(this.byId.get(id));
+    this.byId.delete(id);
+    return true;
+  }
+}
+
+function encodeError(error) {
+  return { $error: { name: error.name, message: error.message } };
+}
+
+/**
+ * Encode a value for the wire.
+ *
+ * @param {unknown} value
+ * @param {HandleTable} handles - Where non-JSON objects are registered
+ * @param {Set<Object>} [seen] - Cycle guard for plain objects and arrays
+ * @returns {unknown} JSON-compatible value
+ */
+export function encodeValue(value, handles, seen = new Set()) {
+  if (value === undefined) {
+    return { $undefined: true };
+  }
+  if (value === null || ['boolean', 'string'].includes(typeof value)) {
+    return value;
+  }
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (typeof value === 'bigint') {
+    return { $bigint: value.toString() };
+  }
+  if (typeof value === 'symbol') {
+    return value.toString();
+  }
+  if (isBinary(value)) {
+    return { $binary: Buffer.from(value).toString('base64') };
+  }
+  if (value instanceof Date) {
+    return { $date: value.toISOString() };
+  }
+  if (value instanceof RegExp) {
+    return { $regexp: { source: value.source, flags: value.flags } };
+  }
+  if (value instanceof Error) {
+    return encodeError(value);
+  }
+  const container = Array.isArray(value) || isPlainObject(value);
+  if (!container || seen.has(value)) {
+    return handles.register(value);
+  }
+  seen.add(value);
+  const encoded = Array.isArray(value)
+    ? value.map((item) => encodeValue(item, handles, seen))
+    : Object.fromEntries(
+        Object.entries(value).map(([key, item]) => [
+          key,
+          encodeValue(item, handles, seen),
+        ])
+      );
+  seen.delete(value);
+  return encoded;
+}
+
+/**
+ * Compile a `$function` source on the server.
+ *
+ * The result's `toString()` is the original source, which is what both
+ * engines serialize when the function is evaluated in the page.
+ */
+export function compileFunction(source) {
+  if (typeof source !== 'string' || source.trim() === '') {
+    throw invalidParams('$function must be a function source string');
+  }
+  let compiled;
+  try {
+    compiled = (0, eval)(`(${source})`);
+  } catch (error) {
+    throw invalidParams(`Invalid $function source: ${error.message}`);
+  }
+  if (typeof compiled !== 'function') {
+    throw invalidParams('$function source did not evaluate to a function');
+  }
+  return compiled;
+}
+
+function decodeError({ name = 'Error', message = '' } = {}) {
+  const error = new Error(message);
+  error.name = name;
+  return error;
+}
+
+const DECODERS = {
+  $handle: (tag, handles) => handles.get(tag),
+  $binary: (tag) => Buffer.from(String(tag), 'base64'),
+  $function: (tag) => compileFunction(tag),
+  $undefined: () => undefined,
+  $date: (tag) => new Date(tag),
+  $regexp: (tag) => new RegExp(tag?.source ?? '', tag?.flags ?? ''),
+  $bigint: (tag) => BigInt(tag),
+  $error: (tag) => decodeError(tag),
+};
+
+function tagOf(value) {
+  return TAGS.find((tag) => Object.hasOwn(value, tag));
+}
+
+/**
+ * Decode a value received from a client.
+ *
+ * @param {unknown} value
+ * @param {HandleTable} handles - Resolves `$handle` references
+ * @returns {unknown}
+ */
+export function decodeValue(value, handles) {
+  if (Array.isArray(value)) {
+    return value.map((item) => decodeValue(item, handles));
+  }
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+  const tag = tagOf(value);
+  if (tag) {
+    return DECODERS[tag](value[tag], handles);
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      key,
+      decodeValue(item, handles),
+    ])
+  );
+}
+
+function isPublicName(name) {
+  return (
+    typeof name === 'string' && name !== 'constructor' && !name.startsWith('_')
+  );
+}
+
+function collectMembers(target) {
+  const methods = new Set();
+  const properties = new Set();
+  let current = target;
+  while (current && current !== Object.prototype) {
+    for (const name of Object.getOwnPropertyNames(current)) {
+      if (!isPublicName(name) || (current === target && name === 'prototype')) {
+        continue;
+      }
+      const descriptor = Object.getOwnPropertyDescriptor(current, name);
+      if (typeof descriptor.value === 'function') {
+        methods.add(name);
+      } else {
+        properties.add(name);
+      }
+    }
+    current = Object.getPrototypeOf(current);
+  }
+  for (const name of methods) {
+    properties.delete(name);
+  }
+  return { methods, properties };
+}
+
+/**
+ * Describe a remote object: every callable member on the object and its
+ * prototype chain, and its other public properties.
+ *
+ * @param {unknown} target
+ * @returns {{type: string, methods: string[], properties: string[]}}
+ */
+export function describeObject(target) {
+  const { methods, properties } =
+    target !== null && ['object', 'function'].includes(typeof target)
+      ? collectMembers(target)
+      : { methods: new Set(), properties: new Set() };
+  return {
+    type: typeName(target),
+    methods: [...methods].sort(),
+    properties: [...properties].sort(),
+  };
+}