pi-feats 0.1.3 → 0.1.4

package/extensions/browser-harness/cdp/events.ts

@@ -0,0 +1,170 @@
+import { Type, type Static, type TSchema } from "typebox";
+import { Compile } from "typebox/compile";
+import { type Result, err, ok } from "../util/result";
+import { type CdpError, cdpError } from "./errors";
+
+const ev = <P extends TSchema>(params: P) => ({ params, validate: Compile(params) });
+
+const open = { additionalProperties: true } as const;
+
+const Anything = Type.Object({}, open);
+
+const StackTrace = Type.Object(
+  {
+    callFrames: Type.Optional(
+      Type.Array(
+        Type.Object(
+          {
+            url: Type.Optional(Type.String()),
+            lineNumber: Type.Optional(Type.Number()),
+            functionName: Type.Optional(Type.String()),
+          },
+          open,
+        ),
+      ),
+    ),
+  },
+  open,
+);
+
+const ConsoleArg = Type.Object(
+  {
+    type: Type.Optional(Type.String()),
+    value: Type.Optional(Type.Unknown()),
+    description: Type.Optional(Type.String()),
+    unserializableValue: Type.Optional(Type.String()),
+  },
+  open,
+);
+
+export const EVENTS = {
+  "Inspector.detached": ev(Anything),
+
+  "Page.javascriptDialogOpening": ev(
+    Type.Object(
+      {
+        type: Type.String(),
+        message: Type.String(),
+        defaultPrompt: Type.Optional(Type.String()),
+      },
+      open,
+    ),
+  ),
+  "Page.loadEventFired": ev(Anything),
+  "Page.frameNavigated": ev(Anything),
+
+  "Runtime.consoleAPICalled": ev(
+    Type.Object(
+      {
+        type: Type.Optional(Type.String()),
+        args: Type.Optional(Type.Array(ConsoleArg)),
+        stackTrace: Type.Optional(StackTrace),
+      },
+      open,
+    ),
+  ),
+
+  "Log.entryAdded": ev(
+    Type.Object(
+      {
+        entry: Type.Object(
+          {
+            level: Type.Optional(Type.String()),
+            text: Type.Optional(Type.String()),
+            url: Type.Optional(Type.String()),
+            lineNumber: Type.Optional(Type.Number()),
+            stackTrace: Type.Optional(StackTrace),
+          },
+          open,
+        ),
+      },
+      open,
+    ),
+  ),
+
+  "Network.requestWillBeSent": ev(
+    Type.Object(
+      {
+        requestId: Type.String(),
+        request: Type.Object(
+          {
+            url: Type.String(),
+            method: Type.String(),
+            postData: Type.Optional(Type.String()),
+          },
+          open,
+        ),
+        type: Type.Optional(Type.String()),
+      },
+      open,
+    ),
+  ),
+  "Network.responseReceived": ev(
+    Type.Object(
+      {
+        requestId: Type.String(),
+        response: Type.Optional(
+          Type.Object(
+            {
+              status: Type.Optional(Type.Number()),
+              statusText: Type.Optional(Type.String()),
+              mimeType: Type.Optional(Type.String()),
+            },
+            open,
+          ),
+        ),
+        type: Type.Optional(Type.String()),
+      },
+      open,
+    ),
+  ),
+  "Network.loadingFinished": ev(
+    Type.Object(
+      { requestId: Type.String(), encodedDataLength: Type.Optional(Type.Number()) },
+      open,
+    ),
+  ),
+  "Network.loadingFailed": ev(
+    Type.Object(
+      { requestId: Type.String(), errorText: Type.Optional(Type.String()) },
+      open,
+    ),
+  ),
+
+  "Target.targetCreated": ev(
+    Type.Object(
+      {
+        targetInfo: Type.Object(
+          {
+            targetId: Type.String(),
+            type: Type.String(),
+            openerId: Type.Optional(Type.String()),
+          },
+          open,
+        ),
+      },
+      open,
+    ),
+  ),
+  "Target.targetDestroyed": ev(Type.Object({ targetId: Type.String() }, open)),
+};
+
+export type CdpEventName = keyof typeof EVENTS;
+export type EventParamsOf<E extends CdpEventName> = Static<(typeof EVENTS)[E]["params"]>;
+
+export const isKnownEvent = (name: string): name is CdpEventName => Object.hasOwn(EVENTS, name);
+
+export const decodeEvent = <E extends CdpEventName>(
+  name: E,
+  raw: unknown,
+): Result<EventParamsOf<E>, CdpError> => {
+  const spec = EVENTS[name];
+  if (spec === undefined) {
+    return err(cdpError("invalid_response", "unknown CDP event", name));
+  }
+  if (!spec.validate.Check(raw)) {
+    const why = spec.validate.Errors(raw).map((e) => e.message).join("; ");
+    return err(cdpError("invalid_response", why, name));
+  }
+  return ok(raw as EventParamsOf<E>);
+};

package/extensions/browser-harness/cdp/network-buffer.ts

@@ -0,0 +1,146 @@
+import { decodeEvent, type EventParamsOf } from "./events";
+import { createRecordStore } from "./record-store";
+
+export type NetworkRecord = {
+  requestId: string;
+  method: string;
+  url: string;
+  status?: number;
+  statusText?: string;
+  type: string;
+  mimeType?: string;
+  requestStartedMs: number;
+  durationMs?: number;
+  requestBodySize: number;
+  responseBodySize?: number;
+  failed?: boolean;
+  errorText?: string;
+  body?: string | null;
+};
+
+export type NetworkFilter = {
+  urlPattern?: string;
+  methodFilter?: string[];
+  statusFilter?: { min?: number; max?: number };
+  resourceTypes?: string[];
+  sinceMs?: number;
+  limit?: number;
+};
+
+export type DrainResult = {
+  readonly records: NetworkRecord[];
+  readonly total: number;
+  readonly bufferOverflowed: boolean;
+};
+
+export type NetworkBuffer = {
+  ingestRequestWillBeSent(p: unknown): void;
+  ingestResponseReceived(p: unknown): void;
+  ingestLoadingFinished(p: unknown): void;
+  ingestLoadingFailed(p: unknown): void;
+  drain(filter: NetworkFilter): DrainResult;
+  clear(): void;
+};
+
+const compileUrlMatcher = (pattern: string): ((url: string) => boolean) => {
+  if (pattern.length >= 2 && pattern.startsWith("/") && pattern.endsWith("/")) {
+    try {
+      const re = new RegExp(pattern.slice(1, -1));
+      return (url) => re.test(url);
+    } catch {}
+  }
+  return (url) => url.includes(pattern);
+};
+
+type UpdateEvent = "Network.responseReceived" | "Network.loadingFinished" | "Network.loadingFailed";
+
+export const createNetworkBuffer = (capacity = 500): NetworkBuffer => {
+  const records = createRecordStore<string, NetworkRecord>(capacity);
+
+  // All three follow-up events say the same thing first: decode, find the request they belong to, give up quietly if it is gone.
+  const update = <E extends UpdateEvent>(
+    method: E,
+    p: unknown,
+    apply: (r: NetworkRecord, params: EventParamsOf<E>) => void,
+  ): void => {
+    const decoded = decodeEvent(method, p);
+    if (!decoded.success) return;
+    const id = decoded.data.requestId;
+    if (!id) return;
+    const r = records.get(id);
+    if (!r) return;
+    apply(r, decoded.data);
+  };
+
+  return {
+    ingestRequestWillBeSent(p) {
+      const decoded = decodeEvent("Network.requestWillBeSent", p);
+      const params = decoded.success ? decoded.data : undefined;
+      const id = params?.requestId;
+      const url = params?.request.url;
+      const method = params?.request.method;
+      if (!id || !url || !method) return;
+      records.delete(id);
+      const postData = params.request.postData;
+      records.set(id, {
+        requestId: id,
+        method,
+        url,
+        type: params.type ?? "Other",
+        requestStartedMs: Date.now(),
+        requestBodySize: postData ? Buffer.byteLength(postData, "utf8") : 0,
+      });
+    },
+
+    ingestResponseReceived(p) {
+      update("Network.responseReceived", p, (r, params) => {
+        if (params.response?.status !== undefined) r.status = params.response.status;
+        if (params.response?.statusText !== undefined && params.response.statusText !== "") r.statusText = params.response.statusText;
+        if (params.response?.mimeType !== undefined) r.mimeType = params.response.mimeType;
+        // type is more accurate on responseReceived (CDP sometimes refines it)
+        if (params.type !== undefined) r.type = params.type;
+      });
+    },
+
+    ingestLoadingFinished(p) {
+      update("Network.loadingFinished", p, (r, params) => {
+        if (params.encodedDataLength !== undefined) r.responseBodySize = params.encodedDataLength;
+        r.durationMs = Date.now() - r.requestStartedMs;
+      });
+    },
+
+    ingestLoadingFailed(p) {
+      update("Network.loadingFailed", p, (r, params) => {
+        r.failed = true;
+        if (params.errorText !== undefined) r.errorText = params.errorText;
+        r.durationMs = Date.now() - r.requestStartedMs;
+      });
+    },
+
+    drain(filter) {
+      const matchUrl = filter.urlPattern !== undefined ? compileUrlMatcher(filter.urlPattern) : undefined;
+      const methods = filter.methodFilter ? new Set(filter.methodFilter.map((m) => m.toUpperCase())) : undefined;
+      const types = filter.resourceTypes ? new Set(filter.resourceTypes.map((t) => t.toLowerCase())) : undefined;
+      const minStatus = filter.statusFilter?.min;
+      const maxStatus = filter.statusFilter?.max;
+      const cutoff = filter.sinceMs !== undefined ? Date.now() - filter.sinceMs : undefined;
+
+      const matched: NetworkRecord[] = [];
+      for (const r of records.values()) {
+        if (matchUrl && !matchUrl(r.url)) continue;
+        if (methods && !methods.has(r.method.toUpperCase())) continue;
+        if (types && !types.has(r.type.toLowerCase())) continue;
+        if (cutoff !== undefined && r.requestStartedMs < cutoff) continue;
+        if (minStatus !== undefined && (r.status === undefined || r.status < minStatus)) continue;
+        if (maxStatus !== undefined && (r.status === undefined || r.status > maxStatus)) continue;
+        matched.push({ ...r });
+      }
+
+      return records.page(matched, filter.limit);
+    },
+
+    clear() {
+      records.clear();
+    },
+  };
+};

package/extensions/browser-harness/cdp/ownership.ts

@@ -0,0 +1,73 @@
+export type OwnershipRegistry = {
+  add(targetId: string): void;
+  remove(targetId: string): void;
+  has(targetId: string): boolean;
+  list(): ReadonlyArray<string>;
+  replaceAll(ids: ReadonlyArray<string>): void;
+  setHarnessWindow(targetId: string | undefined): void;
+  harnessWindow(): string | undefined;
+  setHarnessWindowId(windowId: number | undefined): void;
+  harnessWindowId(): number | undefined;
+  onChange(cb: () => void): void;
+};
+
+export const createOwnershipRegistry = (
+  initial?: {
+    readonly ownedTargetIds?: ReadonlyArray<string>;
+    readonly harnessWindowTargetId?: string;
+    readonly harnessWindowId?: number;
+  },
+): OwnershipRegistry => {
+  const owned = new Set<string>(initial?.ownedTargetIds ?? []);
+  let harnessWindow: string | undefined = initial?.harnessWindowTargetId;
+  let harnessWindowId: number | undefined = initial?.harnessWindowId;
+  let listener: (() => void) | null = null;
+
+  const notify = (): void => {
+    if (listener) listener();
+  };
+
+  return {
+    add(targetId) {
+      if (owned.has(targetId)) return;
+      owned.add(targetId);
+      notify();
+    },
+    remove(targetId) {
+      if (!owned.has(targetId) && harnessWindow !== targetId) return;
+      owned.delete(targetId);
+      if (harnessWindow === targetId) harnessWindow = undefined;
+      notify();
+    },
+    has(targetId) {
+      return owned.has(targetId);
+    },
+    list() {
+      return [...owned];
+    },
+    replaceAll(ids) {
+      owned.clear();
+      for (const id of ids) owned.add(id);
+      notify();
+    },
+    setHarnessWindow(targetId) {
+      if (harnessWindow === targetId) return;
+      harnessWindow = targetId;
+      notify();
+    },
+    harnessWindow() {
+      return harnessWindow;
+    },
+    setHarnessWindowId(windowId) {
+      if (harnessWindowId === windowId) return;
+      harnessWindowId = windowId;
+      notify();
+    },
+    harnessWindowId() {
+      return harnessWindowId;
+    },
+    onChange(cb) {
+      listener = cb;
+    },
+  };
+};

package/extensions/browser-harness/cdp/record-store.ts

@@ -0,0 +1,61 @@
+export type DrainPage<T> = {
+  readonly records: T[];
+  readonly total: number;
+  readonly bufferOverflowed: boolean;
+};
+
+export type RecordStore<K, T> = {
+  set(key: K, rec: T): void;
+  get(key: K): T | undefined;
+  delete(key: K): void;
+  values(): IterableIterator<T>;
+  // Takes the overflow flag as it pages, so each drain reports only the loss since the previous one.
+  page(matched: T[], limit: number | undefined): DrainPage<T>;
+  clear(): void;
+};
+
+const MAX_LIMIT = 500;
+const DEFAULT_LIMIT = 50;
+
+export const createRecordStore = <K, T>(capacity: number): RecordStore<K, T> => {
+  const records = new Map<K, T>();
+  let overflowed = false;
+
+  const evictOldestIfFull = (): void => {
+    while (records.size >= capacity) {
+      const oldest = records.keys().next();
+      if (oldest.done) return;
+      records.delete(oldest.value);
+      overflowed = true;
+    }
+  };
+
+  return {
+    set(key, rec) {
+      evictOldestIfFull();
+      records.set(key, rec);
+    },
+    get(key) {
+      return records.get(key);
+    },
+    delete(key) {
+      records.delete(key);
+    },
+    values() {
+      return records.values();
+    },
+    page(matched, limit) {
+      const bufferOverflowed = overflowed;
+      overflowed = false;
+      return {
+        records: matched.slice(-Math.min(limit ?? DEFAULT_LIMIT, MAX_LIMIT)),
+        total: matched.length,
+        bufferOverflowed,
+      };
+    },
+    clear() {
+      records.clear();
+      overflowed = false;
+    },
+  };
+};