refactor: make improvements to NetworkObserver (#1074)

Author: daniel-graham-amplitude

packages/analytics-core/src/index.ts

@@ -60,5 +60,6 @@ export {
 } from './types/browser-config';
 export { BrowserClient } from './types/browser-client';
 
-export { NetworkRequestEvent, NetworkEventCallback, networkObserver } from './network-observer';
+export { NetworkEventCallback, networkObserver } from './network-observer';
+export { NetworkRequestEvent } from './network-request-event';
 export { NetworkTrackingOptions, NetworkCaptureRule } from './types/network-tracking';

packages/analytics-core/src/network-observer.ts

@@ -1,76 +1,13 @@
-import { getGlobalScope } from './global-scope';
+import { getGlobalScope } from './';
 import { UUID } from './utils/uuid';
 import { ILogger } from '.';
+import { NetworkRequestEvent, RequestWrapper, ResponseWrapper } from './network-request-event';
 
-const MAXIMUM_ENTRIES = 100;
-export interface NetworkRequestEvent {
-  type: string;
-  method: string;
-  url: string;
-  timestamp: number;
-  status?: number;
-  duration?: number;
-  requestBodySize?: number;
-  requestHeaders?: Record<string, string>;
-  responseBodySize?: number;
-  responseHeaders?: Record<string, string>;
-  error?: {
-    name: string;
-    message: string;
-  };
-  startTime?: number;
-  endTime?: number;
-}
-
-// using this type instead of the DOM's ttp so that it's Node compatible
-type FormDataEntryValueBrowser = string | Blob | null;
-export interface FormDataBrowser {
-  entries(): IterableIterator<[string, FormDataEntryValueBrowser]>;
-}
-
-export type FetchRequestBody = string | Blob | ArrayBuffer | FormDataBrowser | URLSearchParams | null | undefined;
-
-export function getRequestBodyLength(body: FetchRequestBody | null | undefined): number | undefined {
-  const global = getGlobalScope();
-  if (!global?.TextEncoder) {
-    return;
-  }
-  const { TextEncoder } = global;
-
-  if (typeof body === 'string') {
-    return new TextEncoder().encode(body).length;
-  } else if (body instanceof Blob) {
-    return body.size;
-  } else if (body instanceof URLSearchParams) {
-    return new TextEncoder().encode(body.toString()).length;
-  } else if (body instanceof ArrayBuffer) {
-    return body.byteLength;
-  } else if (ArrayBuffer.isView(body)) {
-    return body.byteLength;
-  } else if (body instanceof FormData) {
-    // Estimating only for text parts; not accurate for files
-    const formData = body as FormDataBrowser;
-
-    let total = 0;
-    let count = 0;
-    for (const [key, value] of formData.entries()) {
-      total += key.length;
-      if (typeof value === 'string') {
-        total += new TextEncoder().encode(value).length;
-      } else if ((value as Blob).size) {
-        // if we encounter a "File" type, we should not count it and just return undefined
-        total += (value as Blob).size;
-      }
-      // terminate if we reach the maximum number of entries
-      // to avoid performance issues in case of very large FormDataß
-      if (++count >= MAXIMUM_ENTRIES) {
-        return;
-      }
-    }
-    return total;
-  }
-  // Stream or unknown
-  return;
+/**
+ * Typeguard function checks if an input is a Request object.
+ */
+function isRequest(requestInfo: any): requestInfo is Request {
+  return typeof requestInfo === 'object' && requestInfo !== null && 'url' in requestInfo && 'method' in requestInfo;
 }
 
 export type NetworkEventCallbackFn = (event: NetworkRequestEvent) => void;
@@ -80,12 +17,11 @@ export class NetworkEventCallback {
 }
 
 export class NetworkObserver {
-  private originalFetch?: typeof fetch;
   private eventCallbacks: Map<string, NetworkEventCallback> = new Map();
-  private isObserving = false;
   // eslint-disable-next-line no-restricted-globals
   private globalScope?: typeof globalThis;
   private logger?: ILogger;
+  private isObserving = false;
   constructor(logger?: ILogger) {
     this.logger = logger;
     const globalScope = getGlobalScope();
@@ -94,8 +30,6 @@ export class NetworkObserver {
       return;
     }
     this.globalScope = globalScope;
-    /* istanbul ignore next */
-    this.originalFetch = this.globalScope?.fetch;
   }
 
   static isSupported(): boolean {
@@ -109,91 +43,159 @@ export class NetworkObserver {
     }
     this.eventCallbacks.set(eventCallback.id, eventCallback);
     if (!this.isObserving) {
-      this.observeFetch();
+      /* istanbul ignore next */
+      const originalFetch = this.globalScope?.fetch;
+      /* istanbul ignore next */
+      if (!originalFetch) {
+        return;
+      }
+      /* istanbul ignore next */
       this.isObserving = true;
+      this.observeFetch(originalFetch);
     }
   }
 
   unsubscribe(eventCallback: NetworkEventCallback) {
     this.eventCallbacks.delete(eventCallback.id);
-    if (this.originalFetch && this.globalScope && this.eventCallbacks.size === 0 && this.isObserving) {
-      this.globalScope.fetch = this.originalFetch;
-      this.isObserving = false;
-    }
   }
 
   protected triggerEventCallbacks(event: NetworkRequestEvent) {
     this.eventCallbacks.forEach((callback) => {
       try {
         callback.callback(event);
       } catch (err) {
+        // if the callback throws an error, we should catch it
+        // to avoid breaking the fetch promise chain
         /* istanbul ignore next */
         this.logger?.debug('an unexpected error occurred while triggering event callbacks', err);
       }
     });
   }
 
-  private observeFetch() {
+  private handleNetworkRequestEvent(
+    requestInfo: RequestInfo | URL | undefined,
+    requestWrapper: RequestWrapper | undefined,
+    responseWrapper: ResponseWrapper | undefined,
+    typedError: Error | undefined,
+    startTime?: number,
+    durationStart?: number,
+  ) {
     /* istanbul ignore next */
-    if (!this.globalScope || !this.originalFetch) {
+    if (startTime === undefined || durationStart === undefined) {
+      // if we reach this point, it means that the performance API is not supported
+      // so we can't construct a NetworkRequestEvent
       return;
     }
-    const originalFetch = this.globalScope.fetch;
-
-    this.globalScope.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
-      const startTime = Date.now();
-      const durationStart = performance.now();
-      const requestEvent: NetworkRequestEvent = {
-        timestamp: startTime,
-        startTime,
-        type: 'fetch',
-        method: init?.method || 'GET', // Fetch API defaulted to GET when no method is provided
-        url: input.toString(),
-        requestHeaders: init?.headers as Record<string, string>,
-        requestBodySize: getRequestBodyLength(init?.body as FetchRequestBody),
+
+    // parse the URL and Method
+    let url: string | undefined;
+    let method = 'GET';
+    if (isRequest(requestInfo)) {
+      url = requestInfo['url'];
+      method = requestInfo['method'];
+    } else {
+      url = requestInfo?.toString?.();
+    }
+    method = requestWrapper?.method || method;
+
+    let status, error;
+    if (responseWrapper) {
+      status = responseWrapper.status;
+    }
+
+    if (typedError) {
+      error = {
+        name: typedError.name || 'UnknownError',
+        message: typedError.message || 'An unknown error occurred',
       };
+      status = 0;
+    }
 
+    const duration = Math.floor(performance.now() - durationStart);
+    const endTime = Math.floor(startTime + duration);
+
+    const requestEvent = new NetworkRequestEvent(
+      'fetch',
+      method,
+      startTime, // timestamp and startTime are aliases
+      startTime,
+      url,
+      requestWrapper,
+      status,
+      duration,
+      responseWrapper,
+      error,
+      endTime,
+    );
+
+    this.triggerEventCallbacks(requestEvent);
+  }
+
+  getTimestamps() {
+    /* istanbul ignore next */
+    return {
+      startTime: Date.now?.(),
+      durationStart: performance?.now?.(),
+    };
+  }
+
+  private observeFetch(
+    originalFetch: (requestInfo: RequestInfo | URL, requestInit?: RequestInit) => Promise<Response>,
+  ) {
+    /* istanbul ignore next */
+    if (!this.globalScope || !originalFetch) {
+      return;
+    }
+    /**
+     * IMPORTANT: This overrides window.fetch in browsers.
+     * You probably never need to make changes to this function.
+     * If you do, please be careful to preserve the original functionality of fetch
+     * and make sure another developer who is an expert reviews this change throughly
+     */
+    this.globalScope.fetch = async (requestInfo?: RequestInfo | URL, requestInit?: RequestInit) => {
+      // 1: capture the start time and duration start time before the fetch call
+      let timestamps;
       try {
-        const response = await originalFetch(input, init);
-
-        requestEvent.status = response.status;
-        requestEvent.duration = Math.floor(performance.now() - durationStart);
-        requestEvent.startTime = startTime;
-        requestEvent.endTime = Math.floor(startTime + requestEvent.duration);
-
-        // Convert Headers
-        const headers: Record<string, string> = {};
-        let contentLength: number | undefined = undefined;
-        response.headers.forEach((value: string, key: string) => {
-          headers[key] = value;
-          if (key === 'content-length') {
-            contentLength = parseInt(value, 10) || undefined;
-          }
-        });
-        requestEvent.responseHeaders = headers;
-        requestEvent.responseBodySize = contentLength;
-
-        this.triggerEventCallbacks(requestEvent);
-        return response;
+        timestamps = this.getTimestamps();
       } catch (error) {
-        const endTime = Date.now();
-        requestEvent.duration = endTime - startTime;
+        /* istanbul ignore next */
+        this.logger?.debug('an unexpected error occurred while retrieving timestamps', error);
+      }
 
+      // 2. make the call to the original fetch and preserve the response or error
+      let originalResponse, originalError;
+      try {
+        originalResponse = await originalFetch(requestInfo as RequestInfo | URL, requestInit);
+      } catch (err) {
         // Capture error information
-        const typedError = error as Error;
-
-        requestEvent.error = {
-          name: typedError.name || 'UnknownError',
-          message: typedError.message || 'An unknown error occurred',
-        };
+        originalError = err;
+      }
 
-        if (typedError.name === 'AbortError') {
-          requestEvent.error.name = 'AbortError';
-          requestEvent.status = 0;
-        }
+      // 3. call the handler after the fetch call is done
+      try {
+        this.handleNetworkRequestEvent(
+          requestInfo,
+          requestInit ? new RequestWrapper(requestInit) : undefined,
+          originalResponse ? new ResponseWrapper(originalResponse) : undefined,
+          originalError as Error,
+          /* istanbul ignore next */
+          timestamps?.startTime,
+          /* istanbul ignore next */
+          timestamps?.durationStart,
+        );
+      } catch (err) {
+        // this catch shouldn't be reachable, but keep it here for safety
+        // because we're overriding the fetch function and better to be safe than sorry
+        /* istanbul ignore next */
+        this.logger?.debug('an unexpected error occurred while handling fetch', err);
+      }
 
-        this.triggerEventCallbacks(requestEvent);
-        throw error;
+      // 4. return the original response or throw the original error
+      if (originalResponse) {
+        // if the response is not undefined, return it
+        return originalResponse;
+      } else {
+        throw originalError;
       }
     };
   }