react-native-network-lens 0.0.0-stage → 0.1.1

package/src/core/NetworkRequest.ts

@@ -0,0 +1,216 @@
+import type {
+  FailureReason,
+  Headers,
+  NetworkRequestRow,
+  ParsedBody,
+  RequestMethod,
+  RequestState,
+  StatusGroup,
+} from '../types';
+import { parseRequestBody, parseResponseBody } from '../utils/body';
+import { parseUrl, type UrlParts } from '../utils/url';
+
+const getHeader = (headers: Headers, name: string): string | undefined => {
+  const lower = name.toLowerCase();
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() === lower) return headers[key];
+  }
+  return undefined;
+};
+
+export const statusGroupOf = (
+  status: number,
+  state: RequestState
+): StatusGroup => {
+  if (state === 'failed') return 'failed';
+  if (state === 'pending' || status <= 0) return 'pending';
+  if (status < 200) return '1xx';
+  if (status < 300) return '2xx';
+  if (status < 400) return '3xx';
+  if (status < 500) return '4xx';
+  return '5xx';
+};
+
+export default class NetworkRequest {
+  readonly id: string;
+  readonly type = 'XMLHttpRequest';
+  readonly method: RequestMethod;
+  readonly url: string;
+  status = -1;
+  state: RequestState = 'pending';
+  failureReason?: FailureReason;
+  requestHeaders: Headers = {};
+  responseHeaders: Headers = {};
+  dataSent: unknown = null;
+  response: unknown = null;
+  responseType = '';
+  responseURL = '';
+  responseContentType = '';
+  responseSize = 0;
+  timeout = 0;
+  startTime = 0;
+  endTime = 0;
+  gqlOperation?: string;
+  updatedAt: number;
+
+  private urlParts?: UrlParts;
+  private requestBodyCache?: ParsedBody;
+  private responseBodyCache?: Promise<ParsedBody>;
+  private responseBodyVersion = -1;
+
+  constructor(id: string, method: RequestMethod, url: string) {
+    this.id = id;
+    this.method = (method || 'GET').toUpperCase();
+    this.url = url;
+    this.updatedAt = Date.now();
+  }
+
+  get duration(): number {
+    if (!this.startTime) return -1;
+    if (!this.endTime) return -1;
+    return this.endTime - this.startTime;
+  }
+
+  get parsedUrl(): UrlParts {
+    if (!this.urlParts) this.urlParts = parseUrl(this.url);
+    return this.urlParts;
+  }
+
+  get host(): string {
+    return this.parsedUrl.host;
+  }
+
+  get path(): string {
+    return this.parsedUrl.path;
+  }
+
+  get statusGroup(): StatusGroup {
+    return statusGroupOf(this.status, this.state);
+  }
+
+  get requestContentType(): string | undefined {
+    return getHeader(this.requestHeaders, 'content-type');
+  }
+
+  update(values: Partial<NetworkRequest>): void {
+    Object.assign(this, values);
+    if ('dataSent' in values) {
+      this.requestBodyCache = undefined;
+      const body = this.getRequestBody();
+      if (
+        body.kind === 'json' &&
+        body.value &&
+        typeof body.value === 'object'
+      ) {
+        const op = (body.value as { operationName?: unknown }).operationName;
+        if (typeof op === 'string') this.gqlOperation = op;
+      }
+    }
+    this.updatedAt = Date.now();
+  }
+
+  getRequestBody(): ParsedBody {
+    if (!this.requestBodyCache) {
+      this.requestBodyCache = parseRequestBody(
+        this.dataSent,
+        this.requestContentType
+      );
+    }
+    return this.requestBodyCache;
+  }
+
+  /**
+   * Resolves the response body. Blob responses are read asynchronously, hence the promise.
+   * Result is cached until the response changes.
+   */
+  getResponseBody(): Promise<ParsedBody> {
+    if (
+      !this.responseBodyCache ||
+      this.responseBodyVersion !== this.updatedAt
+    ) {
+      this.responseBodyVersion = this.updatedAt;
+      this.responseBodyCache = parseResponseBody(
+        this.response,
+        this.responseType,
+        this.responseContentType
+      ).catch(
+        () =>
+          ({
+            kind: 'text',
+            text: '[Unable to read response body]',
+          }) as ParsedBody
+      );
+    }
+    return this.responseBodyCache;
+  }
+
+  get curl(): string {
+    const parts = ['curl'];
+    if (this.method !== 'GET') parts.push(`-X ${this.method}`);
+    for (const [key, value] of Object.entries(this.requestHeaders)) {
+      parts.push(`-H ${shellQuote(`${key}: ${value}`)}`);
+    }
+    const body = this.getRequestBody();
+    if (body.kind === 'json' || body.kind === 'text') {
+      parts.push(
+        `--data-raw ${shellQuote(body.kind === 'json' ? JSON.stringify(body.value) : body.text)}`
+      );
+    } else if (body.kind === 'form') {
+      for (const [key, value] of Object.entries(body.value)) {
+        parts.push(`-F ${shellQuote(`${key}=${value}`)}`);
+      }
+    }
+    parts.push(shellQuote(this.url));
+    return parts.join(' \\\n  ');
+  }
+
+  toRow(): NetworkRequestRow {
+    return {
+      id: this.id,
+      method: this.method,
+      url: this.url,
+      host: this.host,
+      path: this.path,
+      status: this.status,
+      state: this.state,
+      statusGroup: this.statusGroup,
+      failureReason: this.failureReason,
+      duration: this.duration,
+      startTime: this.startTime,
+      responseSize: this.responseSize,
+      gqlOperation: this.gqlOperation,
+      updatedAt: this.updatedAt,
+    };
+  }
+
+  async toJSON(): Promise<Record<string, unknown>> {
+    const response = await this.getResponseBody();
+    const request = this.getRequestBody();
+    return {
+      id: this.id,
+      method: this.method,
+      url: this.url,
+      status: this.status,
+      state: this.state,
+      failureReason: this.failureReason,
+      startTime: this.startTime,
+      endTime: this.endTime,
+      duration: this.duration,
+      requestHeaders: this.requestHeaders,
+      requestBody:
+        request.kind === 'json' || request.kind === 'form'
+          ? request.value
+          : request.text,
+      responseHeaders: this.responseHeaders,
+      responseBody:
+        response.kind === 'json' || response.kind === 'form'
+          ? response.value
+          : response.text,
+      responseSize: this.responseSize,
+      responseContentType: this.responseContentType,
+    };
+  }
+}
+
+export const shellQuote = (value: string): string =>
+  `'${value.replace(/'/g, `'\\''`)}'`;

package/src/core/XHRInterceptor.ts

@@ -0,0 +1,179 @@
+/**
+ * Patches the global XMLHttpRequest so every request made from JavaScript can
+ * be observed. `fetch` in React Native is built on XMLHttpRequest, so this also
+ * covers fetch, axios, Apollo and friends.
+ *
+ * Every callback is wrapped in try/catch: the inspector must never break the
+ * app's networking.
+ */
+
+export interface InterceptedXHR {
+  __lensId?: number;
+  __lensSeenHeaders?: boolean;
+  __lensSeenDone?: boolean;
+}
+
+type XHRInstance = XMLHttpRequest & InterceptedXHR;
+
+export interface InterceptorCallbacks {
+  onOpen: (method: string, url: string, xhr: XHRInstance) => void;
+  onRequestHeader: (header: string, value: string, xhr: XHRInstance) => void;
+  onSend: (body: unknown, xhr: XHRInstance) => void;
+  onHeadersReceived: (
+    status: number,
+    contentType: string,
+    contentLength: number,
+    headers: Record<string, string>,
+    xhr: XHRInstance
+  ) => void;
+  onResponse: (
+    status: number,
+    timeout: number,
+    response: unknown,
+    responseURL: string,
+    responseType: string,
+    xhr: XHRInstance
+  ) => void;
+  onFailure: (reason: 'error' | 'timeout' | 'abort', xhr: XHRInstance) => void;
+}
+
+// XMLHttpRequest readyState values (fixed by the spec).
+const HEADERS_RECEIVED = 2;
+const DONE = 4;
+
+type Originals = Pick<XMLHttpRequest, 'open' | 'send' | 'setRequestHeader'>;
+
+const noop = () => {};
+const noopCallbacks: InterceptorCallbacks = {
+  onOpen: noop,
+  onRequestHeader: noop,
+  onSend: noop,
+  onHeadersReceived: noop,
+  onResponse: noop,
+  onFailure: noop,
+};
+
+let callbacks = noopCallbacks;
+let originals: Originals | undefined;
+
+const safely = (fn: () => void) => {
+  try {
+    fn();
+  } catch {
+    // never let inspector code break a request
+  }
+};
+
+export const parseResponseHeaders = (raw: string): Record<string, string> => {
+  const headers: Record<string, string> = {};
+  for (const line of raw.split(/[\r\n]+/)) {
+    const index = line.indexOf(':');
+    if (index <= 0) continue;
+    const key = line.slice(0, index).trim();
+    const value = line.slice(index + 1).trim();
+    headers[key] = key in headers ? `${headers[key]}, ${value}` : value;
+  }
+  return headers;
+};
+
+export const isInterceptorEnabled = (): boolean => originals !== undefined;
+
+export const setCallbacks = (next: InterceptorCallbacks) => {
+  callbacks = next;
+};
+
+const readResponse = (xhr: XMLHttpRequest): unknown => {
+  if (xhr.responseType === '' || xhr.responseType === 'text') {
+    try {
+      return xhr.responseText;
+    } catch {
+      // responseText throws for some response types on some platforms
+    }
+  }
+  return xhr.response;
+};
+
+export const enableInterception = (): void => {
+  if (originals || typeof XMLHttpRequest === 'undefined') return;
+
+  const proto = XMLHttpRequest.prototype;
+  const saved: Originals = {
+    open: proto.open,
+    send: proto.send,
+    setRequestHeader: proto.setRequestHeader,
+  };
+  originals = saved;
+
+  proto.open = function open(
+    this: XHRInstance,
+    method: string,
+    url: string | URL,
+    ...rest: unknown[]
+  ) {
+    safely(() => callbacks.onOpen(method, String(url), this));
+    return (saved.open as (...args: unknown[]) => void).call(
+      this,
+      method,
+      url,
+      ...rest
+    );
+  } as XMLHttpRequest['open'];
+
+  proto.setRequestHeader = function setRequestHeader(
+    this: XHRInstance,
+    header: string,
+    value: string
+  ) {
+    safely(() => callbacks.onRequestHeader(header, value, this));
+    return saved.setRequestHeader.call(this, header, value);
+  };
+
+  proto.send = function send(this: XHRInstance, body?: unknown) {
+    // eslint-disable-next-line consistent-this -- the listeners below outlive `this`
+    const xhr = this;
+    safely(() => callbacks.onSend(body, xhr));
+
+    xhr.addEventListener('readystatechange', () => {
+      if (xhr.readyState === HEADERS_RECEIVED && !xhr.__lensSeenHeaders) {
+        xhr.__lensSeenHeaders = true;
+        safely(() => {
+          const length = Number(xhr.getResponseHeader('content-length'));
+          callbacks.onHeadersReceived(
+            xhr.status,
+            xhr.getResponseHeader('content-type') ?? '',
+            Number.isFinite(length) ? length : 0,
+            parseResponseHeaders(xhr.getAllResponseHeaders()),
+            xhr
+          );
+        });
+      }
+      if (xhr.readyState === DONE && !xhr.__lensSeenDone) {
+        xhr.__lensSeenDone = true;
+        safely(() =>
+          callbacks.onResponse(
+            xhr.status,
+            xhr.timeout,
+            readResponse(xhr),
+            xhr.responseURL,
+            xhr.responseType,
+            xhr
+          )
+        );
+      }
+    });
+    for (const reason of ['error', 'timeout', 'abort'] as const) {
+      xhr.addEventListener(reason, () =>
+        safely(() => callbacks.onFailure(reason, xhr))
+      );
+    }
+
+    return saved.send.call(this, body as Parameters<XMLHttpRequest['send']>[0]);
+  };
+};
+
+export const disableInterception = (): void => {
+  if (!originals) return;
+  Object.assign(XMLHttpRequest.prototype, originals);
+  originals = undefined;
+  callbacks = noopCallbacks;
+};

package/src/core/har.ts

@@ -0,0 +1,71 @@
+import type NetworkRequest from './NetworkRequest';
+
+const headersToArray = (headers: Record<string, string>) =>
+  Object.entries(headers).map(([name, value]) => ({ name, value }));
+
+const createHarEntry = async (request: NetworkRequest) => {
+  const requestBody = request.getRequestBody();
+  const responseBody = await request.getResponseBody();
+  return {
+    startedDateTime: new Date(request.startTime || Date.now()).toISOString(),
+    time: Math.max(request.duration, 0),
+    request: {
+      method: request.method,
+      url: request.url.replace(/\s/g, '%20'),
+      httpVersion: 'HTTP/1.1',
+      headers: headersToArray(request.requestHeaders),
+      queryString: Object.entries(request.parsedUrl.query).map(
+        ([name, value]) => ({
+          name,
+          value,
+        })
+      ),
+      cookies: [],
+      headersSize: -1,
+      bodySize: -1,
+      ...(requestBody.kind !== 'empty'
+        ? {
+            postData: {
+              mimeType: request.requestContentType ?? 'text/plain',
+              text: requestBody.text,
+            },
+          }
+        : {}),
+    },
+    response: {
+      status: Math.max(request.status, 0),
+      statusText: '',
+      httpVersion: 'HTTP/1.1',
+      headers: headersToArray(request.responseHeaders),
+      cookies: [],
+      content: {
+        size: request.responseSize || -1,
+        mimeType: request.responseContentType || 'text/plain',
+        text: responseBody.text,
+      },
+      redirectURL: '',
+      headersSize: -1,
+      bodySize: -1,
+    },
+    cache: {},
+    timings: {
+      blocked: -1,
+      dns: -1,
+      ssl: -1,
+      connect: -1,
+      send: 0,
+      wait: Math.max(request.duration, 0),
+      receive: 0,
+    },
+  };
+};
+
+/** Minimal HAR 1.2 document that Chrome/Charles/Proxyman can import. */
+export const createHar = async (requests: NetworkRequest[]) => ({
+  log: {
+    version: '1.2',
+    creator: { name: 'react-native-network-lens', version: '1.0' },
+    pages: [],
+    entries: await Promise.all(requests.map(createHarEntry)),
+  },
+});

package/src/core/loggerSingleton.ts

@@ -0,0 +1,14 @@
+import Logger from './Logger';
+
+const KEY = '__reactNativeNetworkLens__';
+
+type GlobalWithLogger = typeof globalThis & { [KEY]?: Logger };
+
+/**
+ * One logger per JS runtime. It lives on `globalThis` so that Fast Refresh
+ * (which re-evaluates modules) keeps the same instance and the same patched
+ * XMLHttpRequest instead of silently creating a fresh, disabled one.
+ */
+const logger: Logger = ((globalThis as GlobalWithLogger)[KEY] ??= new Logger());
+
+export default logger;

package/src/hooks.ts

@@ -0,0 +1,51 @@
+import { useEffect, useState, useSyncExternalStore } from 'react';
+import logger from './core/loggerSingleton';
+import type NetworkRequest from './core/NetworkRequest';
+
+/** Live list of captured requests, newest first. */
+export const useNetworkRequests = (): NetworkRequest[] =>
+  useSyncExternalStore(
+    logger.subscribe,
+    logger.getSnapshot,
+    logger.getSnapshot
+  );
+
+const getEnabled = () => logger.enabled;
+const getPaused = () => logger.isPaused();
+
+export const useLoggerEnabled = (): boolean =>
+  useSyncExternalStore(logger.subscribe, getEnabled, getEnabled);
+
+export const useLoggerPaused = (): boolean =>
+  useSyncExternalStore(logger.subscribe, getPaused, getPaused);
+
+/** Resolves a promise factory, re-running whenever `deps` change. */
+export const useAsyncValue = <T>(
+  factory: () => Promise<T>,
+  deps: readonly unknown[]
+): { value: T | undefined; loading: boolean } => {
+  const [state, setState] = useState<{
+    value: T | undefined;
+    loading: boolean;
+  }>({
+    value: undefined,
+    loading: true,
+  });
+  useEffect(() => {
+    let cancelled = false;
+    setState((prev) => (prev.loading ? prev : { ...prev, loading: true }));
+    factory().then(
+      (value) => {
+        if (!cancelled) setState({ value, loading: false });
+      },
+      () => {
+        if (!cancelled) setState({ value: undefined, loading: false });
+      }
+    );
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+  return state;
+};

package/src/index.tsx

@@ -0,0 +1,56 @@
+import logger from './core/loggerSingleton';
+import type { NetworkLensOptions } from './types';
+
+export { default as NetworkLens, default } from './components/NetworkLens';
+export type {
+  NetworkLensProps,
+  NetworkLensHandle,
+} from './components/NetworkLens';
+export { default as NetworkLensOverlay } from './components/NetworkLensOverlay';
+export type { NetworkLensOverlayProps } from './components/NetworkLensOverlay';
+export { default as JsonTreeView } from './components/JsonTree/JsonTreeView';
+export type { JsonTreeHandle } from './components/JsonTree/JsonTreeView';
+
+export { default as NetworkRequest } from './core/NetworkRequest';
+export { createHar } from './core/har';
+export { getBackHandler } from './backHandler';
+export { useNetworkRequests, useLoggerEnabled, useLoggerPaused } from './hooks';
+export { lightTheme, darkTheme } from './theme';
+export type { Theme, ThemeName, ThemeInput } from './theme';
+export type {
+  NetworkLensOptions,
+  StartNetworkLoggingOptions,
+  NetworkRequestRow,
+  ParsedBody,
+  RequestMethod,
+  RequestState,
+  FailureReason,
+  StatusGroup,
+  Headers,
+} from './types';
+
+/**
+ * Start capturing requests. Call it once, as early as possible (e.g. in your
+ * `index.js`). Pass `enabled: false` to turn the whole thing into a no-op.
+ *
+ * ```ts
+ * startNetworkLogging({ enabled: __DEV__, maxRequests: 500 });
+ * ```
+ */
+export const startNetworkLogging = (options?: NetworkLensOptions): void =>
+  logger.start(options);
+
+/** Stop capturing, restore XMLHttpRequest and drop every captured request. */
+export const stopNetworkLogging = (): void => logger.stop();
+
+/** Whether requests are currently being captured. */
+export const isNetworkLoggingEnabled = (): boolean => logger.enabled;
+
+/** Snapshot of captured requests, newest first. */
+export const getRequests = () => logger.getRequests();
+
+export const clearRequests = (): void => logger.clear();
+
+/** Pause or resume publishing new requests to the UI. Capturing continues while paused. */
+export const setNetworkLoggingPaused = (paused: boolean): void =>
+  logger.setPaused(paused);