Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

12.6 KB
Raw Blame
import type { ExecutionOptions } from "../../application/AnalysisProvider.js";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
import { AnalysisTimeoutError } from "../../domain/analysisErrorCore.js";
import { BrowserObservationError } from "../../domain/browserObservationError.js";
import type { BrowserObservationOperation } from "../../domain/browserObservationErrors.js";
import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js";
import {
  cdpCleanupGraceExpired,
  cdpCommandDeadlineRecovery,
  selectedCdpCommandTimeoutMs,
} from "../../domain/browserDeadline.js";
import { CdpTargetSessionOwner } from "../CdpTargetSessionOwner.js";
import {
  classifyCdpFrameUrl,
  observeMainFrameUrl,
} from "../CdpCaptureDocuments.js";
import {
  WEB_RUNTIME_LIMITS,
  type webRuntimeTargetSchema,
} from "../../domain/webRuntime.js";
import type { z } from "zod";
import { authorizeCdpTarget } from "../CdpAuthorizedTarget.js";
import { authorizedMainFrame } from "../CdpAuthorizedMainFrame.js";
import {
  discoverCdpEndpoint,
  type CdpEndpointDiscovery,
} from "../CdpEndpoint.js";
import {
  openCdpTargetSession,
  type CdpTargetSession,
} from "../CdpTargetSession.js";
import { runtimeFrameTreeSchema } from "./CdpRuntimeProtocol.js";

type Scope = {
  readonly cdp_endpoint: string;
  readonly target_id: string;
  readonly allowed_origins: readonly string[];
  readonly command_timeout_ms?: number | undefined;
};

/** Owned transport and instrumentation; the selected browser/page remain externally owned. */
export class CdpRuntimeSession {
  readonly enabledDomains: string[] = [];
  preciseCoverageMayBeActive = false;
  #completion: AbortController | undefined;
  #completionTimer: NodeJS.Timeout | undefined;
  constructor(
    readonly transport: CdpTargetSession,
    readonly discovery: CdpEndpointDiscovery,
    readonly target: z.infer<typeof webRuntimeTargetSchema>,
    readonly allowedOrigins: ReadonlySet<string>,
    readonly operation: BrowserObservationOperation,
    readonly options: ExecutionOptions,
    readonly owner: CdpTargetSessionOwner,
    readonly commandTimeoutMs: number,
  ) {}

  /** Acquire a validated target; failed setup releases its owned socket. */
  static async open(
    input: Scope,
    operation: BrowserObservationOperation,
    options: ExecutionOptions,
    owner: CdpTargetSessionOwner,
  ): Promise<CdpRuntimeSession> {
    const commandTimeoutMs = selectedCdpCommandTimeoutMs(
      input.command_timeout_ms,
    );
    // HTTP discovery keeps its own fixed deadline. The WebSocket handshake
    // and a browser-level Target.attachToTarget each get commandTimeoutMs.
    // One deadline around both would expire a valid attach after a slow handshake.
    const discovery = await discoverCdpEndpoint(
      input.cdp_endpoint,
      operation,
      options.signal,
    );
    const { target, allowedOrigins } = authorizeCdpTarget(
      discovery,
      input,
      operation,
    );
    const transport = await openCdpTargetSession(
      discovery,
      target,
      operation,
      options.signal,
      {
        maxPayloadBytes: WEB_RUNTIME_LIMITS.protocolBytes,
        commandTimeoutMs,
      },
      owner,
    );
    try {
      const frame = runtimeMainFrame(
        await runtimeDeadline(
          operation,
          options.signal,
          (signal) =>
            authorizedMainFrame({
              ...transport,
              allowedOrigins,
              signal,
              operation,
            }),
          commandTimeoutMs,
          "command",
          "Page.getFrameTree",
        ),
        allowedOrigins,
      );
      const url = runtimeFrameUrl(frame, operation);
      return new CdpRuntimeSession(
        transport,
        discovery,
        {
          target_id: target.id,
          initial_url: url.url,
          origin: url.origin,
          frame_id: frame.id,
          loader_id: frame.loaderId ?? null,
        },
        allowedOrigins,
        operation,
        options,
        owner,
        commandTimeoutMs,
      );
    } catch (cause: unknown) {
      try {
        await owner.finish(transport.connection);
      } catch (cleanupCause: unknown) {
        if (
          cause instanceof AnalysisError &&
          cleanupCause instanceof AnalysisError
        )
          throw analysisErrorWithCleanupFailure(cause, cleanupCause, operation);
        throw new AggregateError(
          [cause, cleanupCause],
          `CDP runtime setup ${operation} failed and cleanup remains incomplete.`,
          { cause },
        );
      }
      throw cause;
    }
  }

  /** Bound each command separately from the caller-selected observation duration. */
  async command(
    method: string,
    params: Readonly<Record<string, unknown>> = {},
  ): Promise<unknown> {
    const signals = [this.options.signal, this.#completion?.signal].filter(
      (signal): signal is AbortSignal => signal !== undefined,
    );
    try {
      return await runtimeDeadline(
        this.operation,
        signals.length === 0 ? undefined : AbortSignal.any(signals),
        (signal) =>
          this.transport.connection.send(
            method,
            params,
            this.transport.sessionId,
            signal,
          ),
        this.commandTimeoutMs,
        "command",
        method,
      );
    } catch (cause: unknown) {
      if (this.#completion?.signal.aborted && !this.options.signal?.aborted) {
        const recovery = cdpCommandDeadlineRecovery(
          this.commandTimeoutMs,
          "source-join",
        );
        throw new AnalysisTimeoutError(
          this.operation,
          this.commandTimeoutMs,
          recovery,
        );
      }
      throw cause;
    }
  }

  /** Bound the complete inspection/source-join phase as well as each individual command. */
  beginCompletion(): void {
    if (this.#completion !== undefined) return;
    this.#completion = new AbortController();
    this.#completionTimer = setTimeout(
      () => this.#completion?.abort(),
      this.commandTimeoutMs,
    );
  }

  /** Register cleanup before sending: cancellation can occur after producer acceptance. */
  async enable(domain: string): Promise<void> {
    this.enabledDomains.push(domain);
    await this.command(`${domain}.enable`);
  }

  /** Check document identity before joining any live node or final coverage evidence. */
  async assertDocument(): Promise<void> {
    const frame = runtimeMainFrame(
      await this.command("Page.getFrameTree"),
      this.allowedOrigins,
    );
    if (
      frame.id !== this.target.frame_id ||
      (frame.loaderId ?? null) !== this.target.loader_id ||
      (this.target.loader_id === null &&
        ((frame.url !== undefined && frame.url !== this.target.initial_url) ||
          frame.scope === "outside_policy" ||
          frame.scope === "unsupported"))
    )
      throw new BrowserObservationError(this.operation, "target_changed", {
        detail: `Selected target ${this.target.target_id} changed document during ${this.operation}.`,
      });
    runtimeFrameUrl(
      frame,
      this.operation,
      `Selected target ${this.target.target_id} moved to an unselected origin during ${this.operation}.`,
    );
  }

  /** Cleanup uses its own deadline after caller cancellation, then closes REA's transport. */
  async close(
    previousError: AnalysisError | undefined,
    objectGroup?: string,
  ): Promise<ProviderCleanupError | undefined> {
    if (this.#completionTimer !== undefined)
      clearTimeout(this.#completionTimer);
    const controller = new AbortController();
    const timer = setTimeout(
      () => controller.abort(),
      WEB_RUNTIME_LIMITS.cleanupTimeoutMs,
    );
    // Switch before the first restoration send. A short command_timeout_ms
    // would otherwise expire the connection timer and report cleanup_failed.
    this.transport.connection.beginCleanupGrace(
      WEB_RUNTIME_LIMITS.cleanupTimeoutMs,
    );
    const failures: string[] = [];
    let transportFailure: AnalysisError | undefined;
    const send = async (
      method: string,
      params: Readonly<Record<string, unknown>> = {},
    ): Promise<void> => {
      try {
        await this.transport.connection.send(
          method,
          params,
          this.transport.sessionId,
          controller.signal,
        );
      } catch (cause: unknown) {
        failures.push(
          `${method}: ${cause instanceof AnalysisError ? (cause.userMessage ?? cause.message) : cause instanceof Error ? cause.message : String(cause)}`,
        );
      }
    };
    try {
      if (this.preciseCoverageMayBeActive)
        await send("Profiler.stopPreciseCoverage");
      if (objectGroup !== undefined)
        await send("Runtime.releaseObjectGroup", { objectGroup });
      for (const domain of [...this.enabledDomains].reverse())
        await send(`${domain}.disable`);
      if (this.transport.sessionId !== undefined) {
        try {
          await this.transport.connection.send(
            "Target.detachFromTarget",
            { sessionId: this.transport.sessionId },
            undefined,
            controller.signal,
          );
        } catch (cause: unknown) {
          failures.push(
            `Target.detachFromTarget: ${cause instanceof AnalysisError ? (cause.userMessage ?? cause.message) : cause instanceof Error ? cause.message : String(cause)}`,
          );
        }
      }
    } finally {
      clearTimeout(timer);
      if (controller.signal.aborted) failures.push(cdpCleanupGraceExpired());
      try {
        await this.owner.finish(this.transport.connection);
      } catch (cause: unknown) {
        transportFailure =
          cause instanceof AnalysisError
            ? cause
            : new ProviderCleanupError(
                "rea-cdp-browser",
                [this.target.target_id],
                {
                  reason:
                    cause instanceof Error ? cause.message : String(cause),
                },
                { operation: this.operation, cause },
              );
        failures.push(
          `CDP WebSocket close: ${transportFailure.userMessage ?? transportFailure.message}`,
        );
      }
    }
    return failures.length === 0
      ? undefined
      : new ProviderCleanupError(
          "rea-cdp-browser",
          [this.target.target_id, "runtime-instrumentation"],
          {
            target_id: this.target.target_id,
            cleanup_failures: failures,
            previous_error:
              previousError?.userMessage ?? previousError?.message ?? null,
          },
          {
            operation: this.operation,
            ...(transportFailure === undefined
              ? {}
              : { cause: transportFailure }),
          },
        );
  }
}

/** Runtime validates document IDs; CDP owns URL and scope interpretation. */
const runtimeMainFrame = (
  result: unknown,
  allowedOrigins: ReadonlySet<string>,
) => ({
  ...runtimeFrameTreeSchema.parse(result).frameTree.frame,
  ...classifyCdpFrameUrl(observeMainFrameUrl(result), allowedOrigins),
});

const runtimeFrameUrl = (
  frame: ReturnType<typeof runtimeMainFrame>,
  operation: BrowserObservationOperation,
  detail?: string,
) => {
  if (frame.scope === "outside_policy" || frame.scope === "unsupported")
    throw new BrowserObservationError(
      operation,
      "target_not_allowed",
      detail === undefined ? {} : { detail },
    );
  if (frame.url === undefined || frame.origin === null)
    throw new BrowserObservationError(operation, "protocol_error");
  return { url: frame.url, origin: frame.origin };
};

/** Apply a disposable command deadline without turning timeout into caller cancellation. */
export const runtimeDeadline = async <T>(
  operation: BrowserObservationOperation,
  signal: AbortSignal | undefined,
  run: (signal: AbortSignal) => Promise<T>,
  timeoutMs: number = selectedCdpCommandTimeoutMs(undefined),
  phase: "handshake" | "command" = "command",
  method?: string,
): Promise<T> => {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);
  try {
    return await run(
      signal === undefined
        ? controller.signal
        : AbortSignal.any([signal, controller.signal]),
    );
  } catch (cause: unknown) {
    if (controller.signal.aborted && signal?.aborted !== true) {
      if (cause instanceof AnalysisError && cause.userMessage !== undefined)
        throw cause;
      const recovery = cdpCommandDeadlineRecovery(
        timeoutMs,
        phase,
        method ?? (phase === "handshake" ? undefined : "session setup"),
      );
      throw new AnalysisTimeoutError(operation, timeoutMs, recovery);
    }
    throw cause;
  } finally {
    clearTimeout(timer);
  }
};