Skip to content

Chrome DevTools for coding agents

11.9 KB
Raw Blame
/**
 * @license
 * Copyright 2025 Google LLC
 * SPDX-License-Identifier: Apache-2.0
 * */

import {isUtf8} from 'node:buffer';

import {
  DevTools,
  type HTTPRequest,
  type HTTPResponse,
} from '../third_party/index.js';
import {truncateText, truncateUrl} from '../utils/text.js';

const BODY_CONTEXT_SIZE_LIMIT = 10000;
/**
 * How long to wait for a response body. Puppeteer reads a body only after the
 * response finished loading, with no timeout of its own, and a response that
 * never finishes (e.g. a `Cache-Control: no-store` response the page did not
 * read) would otherwise hold the tool mutex forever.
 */
export const RESPONSE_BODY_TIMEOUT_MS = 5000;

class ResponseBodyTimeoutError extends Error {
  readonly timeout: number;

  constructor(timeout: number) {
    super(`Response body timed out after ${timeout} ms`);
    this.timeout = timeout;
  }
}

function responseBodyTimeoutMessage(error: ResponseBodyTimeoutError): string {
  return `<Response body not available: the response did not finish loading within ${error.timeout} ms>`;
}

export interface NetworkFormatterOptions {
  requestId?: number | string;
  selectedInDevToolsUI?: boolean;
  requestIdResolver?: (request: HTTPRequest) => number | string;
  fetchData?: boolean;
  requestFilePath?: string;
  responseFilePath?: string;
  saveFile?: (
    data: Uint8Array<ArrayBufferLike>,
    filename: string,
    extension: '.network-request' | '.network-response',
  ) => Promise<{filename: string}>;
  redactNetworkHeaders: boolean;
  /** Defaults to `RESPONSE_BODY_TIMEOUT_MS`. */
  responseBodyTimeout?: number;
}

interface NetworkRequestConcise {
  requestId?: number | string;
  method: string;
  url: string;
  status: string;
  selectedInDevToolsUI?: boolean;
}

interface NetworkRequestDetailed extends NetworkRequestConcise {
  requestHeaders: Record<string, string>;
  requestBody?: string;
  requestBodyFilePath?: string;
  responseHeaders?: Record<string, string>;
  responseBody?: string;
  responseBodyFilePath?: string;
  failure?: string;
  redirectChain?: NetworkRequestConcise[];
}

export class NetworkFormatter {
  #request: HTTPRequest;
  #options: NetworkFormatterOptions;
  #requestBody?: string;
  #responseBody?: string;
  #requestBodyFilePath?: string;
  #responseBodyFilePath?: string;

  private constructor(request: HTTPRequest, options: NetworkFormatterOptions) {
    this.#request = request;
    this.#options = options;
  }

  static async from(
    request: HTTPRequest,
    options: NetworkFormatterOptions,
  ): Promise<NetworkFormatter> {
    const instance = new NetworkFormatter(request, options);
    if (options.fetchData) {
      await instance.#loadDetailedData();
    }
    return instance;
  }

  async #loadDetailedData(): Promise<void> {
    // Load Request Body
    if (this.#request.hasPostData()) {
      let data;
      try {
        data =
          this.#request.postData() ?? (await this.#request.fetchPostData());
      } catch {
        // Ignore parsing errors
      }
      const requestBodyNotAvailableMessage =
        '<Request body not available anymore>';
      if (this.#options.requestFilePath) {
        if (!this.#options.saveFile) {
          throw new Error(
            'Unable to save the request body to a file: no saveFile callback was configured.',
          );
        }
        // postData() is UTF-8 decoded, so binary bodies lose bytes; content()
        // returns the raw bytes.
        let bytes: Uint8Array | undefined;
        try {
          bytes = await this.#request.content();
        } catch {
          // Fall back to the decoded string below.
        }
        const body = bytes?.length
          ? bytes
          : data
            ? Buffer.from(data)
            : undefined;
        if (body) {
          const result = await this.#options.saveFile(
            body,
            this.#options.requestFilePath,
            '.network-request',
          );
          this.#requestBodyFilePath = result.filename;
        } else {
          this.#requestBody = requestBodyNotAvailableMessage;
        }
      } else if (data) {
        this.#requestBody = getSizeLimitedString(data, BODY_CONTEXT_SIZE_LIMIT);
      } else {
        this.#requestBody = requestBodyNotAvailableMessage;
      }
    }

    // Load Response Body
    const response = this.#request.response();
    if (response) {
      const responseBodyNotAvailableMessage =
        '<Response body not available anymore>';
      if (this.#options.responseFilePath) {
        let buffer: Uint8Array | undefined;
        try {
          buffer = await this.#readResponseBody(response);
        } catch (error) {
          this.#responseBody =
            error instanceof ResponseBodyTimeoutError
              ? responseBodyTimeoutMessage(error)
              : responseBodyNotAvailableMessage;
        }

        if (buffer) {
          if (!this.#options.saveFile) {
            throw new Error(
              'Unable to save the response body to a file: no saveFile callback was configured.',
            );
          }
          const result = await this.#options.saveFile(
            buffer,
            this.#options.responseFilePath,
            '.network-response',
          );
          this.#responseBodyFilePath = result.filename;
        }
      } else {
        this.#responseBody = await this.#getFormattedResponseBody(
          response,
          BODY_CONTEXT_SIZE_LIMIT,
        );
      }
    }
  }

  toString(): string {
    return convertNetworkRequestConciseToString(this.toJSON());
  }

  toStringDetailed(): string {
    return convertNetworkRequestDetailedToStringDetailed(this.toJSONDetailed());
  }

  toJSON(): NetworkRequestConcise {
    return {
      requestId: this.#options.requestId,
      method: this.#request.method(),
      url: this.#request.url(),
      status: this.#getStatusFromRequest(this.#request),
      selectedInDevToolsUI: this.#options.selectedInDevToolsUI,
    };
  }

  #redactNetworkHeaders(
    headers: Record<string, string>,
  ): Record<string, string> {
    const headersList = Object.entries(headers).map(item => {
      return {name: item[0], value: item[1]};
    });
    const redacted =
      DevTools.NetworkRequestFormatter.sanitizeHeaders(headersList);
    return redacted.reduce<Record<string, string>>((acc, item) => {
      acc[item.name] = item.value;
      return acc;
    }, {});
  }

  toJSONDetailed(): NetworkRequestDetailed {
    // Puppeteer shares one redirect chain array between all hops of a
    // redirect, so earlier hops also list themselves and the hops after them.
    // Keep only the requests that redirected to this one.
    const fullChain = this.#request.redirectChain();
    const ownIndex = fullChain.indexOf(this.#request);
    const redirectChain =
      ownIndex === -1 ? fullChain : fullChain.slice(0, ownIndex);
    const formattedRedirectChain = redirectChain.reverse().map(request => {
      const id = this.#options.requestIdResolver
        ? this.#options.requestIdResolver(request)
        : undefined;
      const formatter = new NetworkFormatter(request, {
        requestId: id,
        saveFile: this.#options.saveFile,
        redactNetworkHeaders: this.#options.redactNetworkHeaders,
      });
      return formatter.toJSON();
    });

    const responseHeaders = this.#request.response()?.headers();

    return {
      ...this.toJSON(),
      requestHeaders: this.#options.redactNetworkHeaders
        ? this.#redactNetworkHeaders(this.#request.headers())
        : this.#request.headers(),
      requestBody: this.#requestBody,
      requestBodyFilePath: this.#requestBodyFilePath,
      responseHeaders:
        this.#options.redactNetworkHeaders && responseHeaders
          ? this.#redactNetworkHeaders(responseHeaders)
          : this.#request.response()?.headers(),
      responseBody: this.#responseBody,
      responseBodyFilePath: this.#responseBodyFilePath,
      failure: this.#request.failure()?.errorText,
      redirectChain: formattedRedirectChain.length
        ? formattedRedirectChain
        : undefined,
    };
  }

  #getStatusFromRequest(request: HTTPRequest): string {
    const httpResponse = request.response();
    const failure = request.failure();
    let status: string;
    if (httpResponse) {
      status = httpResponse.status().toString();
    } else if (failure) {
      status = failure.errorText;
    } else {
      status = 'pending';
    }
    return status;
  }

  async #getFormattedResponseBody(
    httpResponse: HTTPResponse,
    sizeLimit = BODY_CONTEXT_SIZE_LIMIT,
  ): Promise<string | undefined> {
    try {
      const responseBuffer = await this.#readResponseBody(httpResponse);

      if (isUtf8(responseBuffer)) {
        const responseAsTest = responseBuffer.toString('utf-8');

        if (responseAsTest.length === 0) {
          return '<empty response>';
        }

        return getSizeLimitedString(responseAsTest, sizeLimit);
      }

      return '<binary data>';
    } catch (error) {
      if (error instanceof ResponseBodyTimeoutError) {
        return responseBodyTimeoutMessage(error);
      }
      return '<not available anymore>';
    }
  }

  async #readResponseBody(httpResponse: HTTPResponse): Promise<Buffer> {
    const timeout =
      this.#options.responseBodyTimeout ?? RESPONSE_BODY_TIMEOUT_MS;
    let timeoutId: ReturnType<typeof setTimeout> | undefined;
    try {
      return await Promise.race([
        httpResponse.buffer(),
        new Promise<never>((_, reject) => {
          timeoutId = setTimeout(() => {
            reject(new ResponseBodyTimeoutError(timeout));
          }, timeout);
        }),
      ]);
    } finally {
      clearTimeout(timeoutId);
    }
  }
}

function getSizeLimitedString(text: string, sizeLimit: number): string {
  return truncateText(text, sizeLimit, {ellipsis: '... <truncated>'});
}

function convertNetworkRequestConciseToString(
  data: NetworkRequestConcise,
): string {
  // Long URLs (e.g., data: URLs) bloat the concise list output. The full URL
  // remains available via the detailed view and the structured content.
  const url = truncateUrl(data.url);
  return `reqid=${data.requestId} ${data.method} ${url} [${data.status}]${data.selectedInDevToolsUI ? ` [selected in the DevTools Network panel]` : ''}`;
}

function formatHeaders(headers: Record<string, string>): string[] {
  const response: string[] = [];
  for (const [name, value] of Object.entries(headers)) {
    response.push(`- ${name}:${value}`);
  }
  return response;
}

function convertNetworkRequestDetailedToStringDetailed(
  data: NetworkRequestDetailed,
): string {
  const response: string[] = [];
  response.push(`## Request ${data.url}`);
  response.push(`Status: ${data.status}`);
  response.push(`### Request Headers`);
  for (const line of formatHeaders(data.requestHeaders)) {
    response.push(line);
  }

  if (data.requestBody) {
    response.push(`### Request Body`);
    response.push(data.requestBody);
  } else if (data.requestBodyFilePath) {
    response.push(`### Request Body`);
    response.push(`Saved to ${data.requestBodyFilePath}.`);
  }

  if (data.responseHeaders) {
    response.push(`### Response Headers`);
    for (const line of formatHeaders(data.responseHeaders)) {
      response.push(line);
    }
  }

  if (data.responseBody) {
    response.push(`### Response Body`);
    response.push(data.responseBody);
  } else if (data.responseBodyFilePath) {
    response.push(`### Response Body`);
    response.push(`Saved to ${data.responseBodyFilePath}.`);
  }

  if (data.failure) {
    response.push(`### Request failed with`);
    response.push(data.failure);
  }

  const redirectChain = data.redirectChain;
  if (redirectChain?.length) {
    response.push(`### Redirect chain`);
    let indent = 0;
    // `redirectChain` is already ordered by toJSONDetailed(); don't reverse it
    // again here or the text output contradicts structuredContent (the JSON).
    for (const request of redirectChain) {
      response.push(
        `${'  '.repeat(indent)}${convertNetworkRequestConciseToString(request)}`,
      );
      indent++;
    }
  }
  return response.join('\n');
}