@webex/internal-plugin-metrics 3.12.0-llmrefactor.2 → 3.12.0-llmrefactor.4

package/src/unhandled-exception-telemetry/index.ts

@@ -0,0 +1,403 @@
+/* eslint-disable require-jsdoc, valid-jsdoc */
+
+import {safeSetTimeout} from '@webex/common-timers';
+import uuid from 'uuid';
+
+import {
+  createFingerprint,
+  removeUrlDetails,
+  removeUrlDetailsFromText,
+  sanitizeResourceUrl,
+  stringifyReason,
+  truncate,
+} from './utils';
+
+export const UNHANDLED_EXCEPTION_METRIC_NAME = 'JS_SDK_OBSERVED_CLIENT_UNHANDLED_EXCEPTION';
+
+const DEDUPE_WINDOW_MS = 1_000;
+const MAX_ERROR_MESSAGE_LENGTH = 4_096;
+const MAX_ERROR_NAME_LENGTH = 256;
+const MAX_METADATA_LENGTH = 32_000;
+const MAX_STACK_LENGTH = 8_192;
+
+const TELEMETRY_LOG_IDENTIFIER = 'Unhandled Exception Telemetry -->';
+
+type ErrorDetails = {
+  column?: number;
+  filename?: string;
+  kind: 'error' | 'unhandledrejection' | 'resource_error';
+  line?: number;
+  message?: string;
+  name: string;
+  /** Uppercase DOM tag name, such as SCRIPT, LINK, or IMG; RESOURCE when unavailable. */
+  resourceType?: string;
+  resourceUrl?: string;
+  stack?: string;
+};
+
+export type UnhandledExceptionEvent = {
+  schemaVersion: 1;
+  capturedAt: number;
+  eventId: string;
+  occurrenceCount: number;
+  common: {
+    appName: string;
+    appVersion?: string;
+    runtime: 'browser';
+    sdkVersion?: string;
+  };
+  error: ErrorDetails & {fingerprint: string};
+  metadata?: Record<string, unknown>;
+  metadataCaptureStatus?: 'invalid_type' | 'provider_error' | 'too_large';
+};
+
+type WebexForUnhandledExceptionTelemetry = {
+  canAuthorize?: boolean;
+  version?: string;
+  config?: {
+    appName?: string;
+    appVersion?: string;
+    sdkType?: string;
+    metrics?: {
+      unhandledExceptionTelemetry?: {
+        enabled?: boolean;
+        getMetadata?: () => Record<string, unknown> | undefined;
+      };
+    };
+  };
+  internal?: {
+    metrics?: {
+      submitClientMetrics?: (name: string, properties: object, preLoginId?: string) => unknown;
+    };
+  };
+  logger?: {
+    error?: (...args: unknown[]) => unknown;
+  };
+};
+
+function logTelemetryFailure(webex: WebexForUnhandledExceptionTelemetry, message: string): void {
+  try {
+    webex.logger?.error?.(TELEMETRY_LOG_IDENTIFIER, message);
+  } catch {
+    // Logging must not turn a telemetry failure into an application failure.
+  }
+}
+
+/**
+ * SDK-owned browser exception reporter with a single in-memory deduplication window.
+ */
+class UnhandledExceptionTelemetry {
+  private readonly pendingEvents = new Map<string, UnhandledExceptionEvent>();
+  private readonly eventTarget: Window;
+  private readonly errorListener = (event: ErrorEvent) => this.captureError(event);
+  private readonly preLoginId: string;
+  private readonly rejectionListener = (event: PromiseRejectionEvent) =>
+    this.captureRejection(event);
+
+  private readonly webex: WebexForUnhandledExceptionTelemetry;
+  private flushTimer?: number | NodeJS.Timeout;
+
+  /**
+   * Registers browser listeners after the SDK is ready.
+   * @param webex SDK instance used for configuration and submission.
+   * @param eventTarget Browser window.
+   */
+  constructor(webex: WebexForUnhandledExceptionTelemetry, eventTarget: Window) {
+    this.webex = webex;
+    this.eventTarget = eventTarget;
+    this.preLoginId = uuid.v4();
+    eventTarget.addEventListener('error', this.errorListener, {capture: true});
+    eventTarget.addEventListener('unhandledrejection', this.rejectionListener, {capture: true});
+  }
+
+  /**
+   * Removes global listeners and either flushes or discards pending events.
+   * @param flushPending Whether to submit pending telemetry before teardown.
+   * @returns {void}
+   */
+  stop(flushPending: boolean): void {
+    this.eventTarget.removeEventListener('error', this.errorListener, {capture: true});
+    this.eventTarget.removeEventListener('unhandledrejection', this.rejectionListener, {
+      capture: true,
+    });
+    this.clearFlushTimer();
+
+    if (flushPending) {
+      this.pendingEvents.forEach((event) => this.submit(event));
+    }
+
+    this.pendingEvents.clear();
+  }
+
+  private captureError(event: ErrorEvent): void {
+    try {
+      const resourceTarget = event.target;
+      const currentSrc = resourceTarget ? Reflect.get(resourceTarget, 'currentSrc') : undefined;
+      const src = resourceTarget ? Reflect.get(resourceTarget, 'src') : undefined;
+      const href = resourceTarget ? Reflect.get(resourceTarget, 'href') : undefined;
+      const rawResourceUrl =
+        (typeof currentSrc === 'string' && currentSrc.length > 0 && currentSrc) ||
+        (typeof src === 'string' && src.length > 0 && src) ||
+        (typeof href === 'string' && href.length > 0 && href) ||
+        undefined;
+
+      if (rawResourceUrl) {
+        const resourceUrl = sanitizeResourceUrl(rawResourceUrl);
+
+        if (!resourceUrl) {
+          return;
+        }
+
+        const resourceType = String(
+          (resourceTarget && Reflect.get(resourceTarget, 'tagName')) ?? 'RESOURCE'
+        ).toUpperCase();
+
+        this.capture({
+          kind: 'resource_error',
+          message: `Failed to load ${resourceType} resource`,
+          name: 'ResourceError',
+          resourceType,
+          resourceUrl,
+        });
+
+        return;
+      }
+
+      const {error} = event;
+      let message = 'Unknown uncaught error';
+
+      if (typeof error?.message === 'string') {
+        message = error.message;
+      } else if (typeof event.message === 'string') {
+        message = event.message;
+      }
+
+      this.capture({
+        column: event.colno,
+        filename: removeUrlDetails(event.filename),
+        kind: 'error',
+        line: event.lineno,
+        message,
+        name: typeof error?.name === 'string' ? error.name : 'Error',
+        stack: typeof error?.stack === 'string' ? error.stack : undefined,
+      });
+    } catch {
+      logTelemetryFailure(this.webex, 'Failed to extract an uncaught error.');
+    }
+  }
+
+  private captureRejection(event: PromiseRejectionEvent): void {
+    try {
+      const {reason} = event;
+
+      this.capture({
+        kind: 'unhandledrejection',
+        message: typeof reason?.message === 'string' ? reason.message : stringifyReason(reason),
+        name: typeof reason?.name === 'string' ? reason.name : 'UnhandledRejection',
+        stack: typeof reason?.stack === 'string' ? reason.stack : undefined,
+      });
+    } catch {
+      logTelemetryFailure(this.webex, 'Failed to extract an unhandled rejection.');
+    }
+  }
+
+  private capture(details: ErrorDetails): void {
+    try {
+      const error = {
+        ...details,
+        name: truncate(removeUrlDetailsFromText(details.name), MAX_ERROR_NAME_LENGTH) ?? 'Error',
+        message: truncate(removeUrlDetailsFromText(details.message), MAX_ERROR_MESSAGE_LENGTH),
+        stack: truncate(removeUrlDetailsFromText(details.stack), MAX_STACK_LENGTH),
+      };
+      const fingerprint = createFingerprint(
+        [
+          error.kind,
+          error.name,
+          error.message,
+          error.stack,
+          error.filename,
+          error.line,
+          error.column,
+          error.resourceUrl,
+        ].join('|')
+      );
+      const capturedAt = new Date().getTime();
+      const existingEvent = this.pendingEvents.get(fingerprint);
+
+      if (existingEvent) {
+        const isWithinDedupeWindow = capturedAt - existingEvent.capturedAt < DEDUPE_WINDOW_MS;
+
+        if (isWithinDedupeWindow) {
+          existingEvent.occurrenceCount += 1;
+
+          return;
+        }
+
+        // A throttled timer can leave an expired event pending. Its completed window must be
+        // submitted before this fingerprint is replaced with a new event and a new window.
+        this.pendingEvents.delete(fingerprint);
+        this.submit(existingEvent);
+      }
+
+      const event: UnhandledExceptionEvent = {
+        schemaVersion: 1,
+        capturedAt,
+        eventId: uuid.v4(),
+        occurrenceCount: 1,
+        common: {
+          appName: this.webex.config?.appName ?? this.webex.config?.sdkType ?? 'webex-js-sdk',
+          appVersion: this.webex.config?.appVersion,
+          runtime: 'browser',
+          sdkVersion: this.webex.version,
+        },
+        error: {...error, fingerprint},
+      };
+
+      this.addMetadata(event);
+      this.pendingEvents.set(fingerprint, event);
+
+      if (this.flushTimer === undefined) {
+        this.flushTimer = safeSetTimeout(() => this.flush(), DEDUPE_WINDOW_MS);
+      }
+    } catch {
+      logTelemetryFailure(this.webex, 'Failed to capture an exception.');
+    }
+  }
+
+  private addMetadata(event: UnhandledExceptionEvent): void {
+    const getMetadata = this.webex.config?.metrics?.unhandledExceptionTelemetry?.getMetadata;
+
+    if (!getMetadata) {
+      return;
+    }
+
+    try {
+      const metadata = getMetadata();
+
+      if (metadata === undefined) {
+        return;
+      }
+
+      const serializedMetadata = JSON.stringify(metadata);
+
+      if (serializedMetadata === undefined || serializedMetadata.length > MAX_METADATA_LENGTH) {
+        event.metadataCaptureStatus =
+          serializedMetadata === undefined ? 'invalid_type' : 'too_large';
+
+        return;
+      }
+
+      const parsedMetadata = JSON.parse(serializedMetadata);
+
+      if (
+        parsedMetadata === null ||
+        typeof parsedMetadata !== 'object' ||
+        Array.isArray(parsedMetadata)
+      ) {
+        event.metadataCaptureStatus = 'invalid_type';
+
+        return;
+      }
+
+      event.metadata = parsedMetadata;
+    } catch {
+      event.metadataCaptureStatus = 'provider_error';
+    }
+  }
+
+  private flush(): void {
+    const now = new Date().getTime();
+    let nextFlushInMs: number | undefined;
+
+    this.clearFlushTimer();
+    this.pendingEvents.forEach((event, fingerprint) => {
+      const remainingWindowMs = DEDUPE_WINDOW_MS - (now - event.capturedAt);
+
+      if (remainingWindowMs <= 0) {
+        this.pendingEvents.delete(fingerprint);
+        this.submit(event);
+
+        return;
+      }
+
+      nextFlushInMs = Math.min(nextFlushInMs ?? remainingWindowMs, remainingWindowMs);
+    });
+
+    if (nextFlushInMs !== undefined) {
+      this.flushTimer = safeSetTimeout(() => this.flush(), nextFlushInMs);
+    }
+  }
+
+  private submit(event: UnhandledExceptionEvent): void {
+    const submitClientMetrics = this.webex.internal?.metrics?.submitClientMetrics;
+
+    if (!submitClientMetrics) {
+      logTelemetryFailure(this.webex, 'submitClientMetrics is unavailable.');
+
+      return;
+    }
+
+    try {
+      Promise.resolve(
+        submitClientMetrics.call(
+          this.webex.internal?.metrics,
+          UNHANDLED_EXCEPTION_METRIC_NAME,
+          {
+            tags: {
+              app_name: event.common.appName,
+              exception_kind: event.error.kind,
+              runtime: event.common.runtime,
+            },
+            fields: {
+              captured_at: event.capturedAt,
+              error_fingerprint: event.error.fingerprint,
+              error_name: event.error.name,
+              event_id: event.eventId,
+              occurrence_count: event.occurrenceCount,
+            },
+            eventPayload: event,
+          },
+          this.webex.canAuthorize === true ? undefined : this.preLoginId
+        )
+      ).catch(() => {
+        logTelemetryFailure(this.webex, 'Failed to submit exception telemetry.');
+      });
+    } catch {
+      logTelemetryFailure(this.webex, 'Failed to submit exception telemetry.');
+    }
+  }
+
+  private clearFlushTimer(): void {
+    if (this.flushTimer !== undefined) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = undefined;
+    }
+  }
+}
+
+let activeTelemetry: UnhandledExceptionTelemetry | undefined;
+
+/**
+ * Starts browser exception telemetry after SDK readiness.
+ * @param webex Initialized SDK instance.
+ * @returns {void}
+ */
+export function startUnhandledExceptionTelemetry(webex: WebexForUnhandledExceptionTelemetry): void {
+  const shouldStart =
+    webex.config?.metrics?.unhandledExceptionTelemetry?.enabled === true &&
+    typeof window !== 'undefined' &&
+    typeof window.addEventListener === 'function';
+
+  activeTelemetry?.stop(shouldStart);
+  activeTelemetry = undefined;
+
+  if (!shouldStart) {
+    return;
+  }
+
+  try {
+    activeTelemetry = new UnhandledExceptionTelemetry(webex, window);
+  } catch {
+    logTelemetryFailure(webex, 'Failed to start exception telemetry.');
+  }
+}

package/src/unhandled-exception-telemetry/utils.ts

@@ -0,0 +1,101 @@
+/* eslint-disable require-jsdoc */
+
+const MAX_RESOURCE_URL_LENGTH = 2_048;
+
+export function truncate(value: string | undefined, maxLength: number): string | undefined {
+  return value?.slice(0, maxLength);
+}
+
+export function removeUrlDetails(value: unknown): string | undefined {
+  if (typeof value !== 'string' || value.length === 0) {
+    return undefined;
+  }
+
+  const withoutQueryOrFragment = value.split(/[?#]/, 1)[0];
+
+  // Strip URL userinfo from the authority. For example,
+  // https://userinfo@host/path becomes https://host/path.
+  return withoutQueryOrFragment.replace(/^((?:[a-z][a-z0-9+.-]*:)?\/\/)[^/?#]*@/i, '$1');
+}
+
+// Keep HTTP(S) and relative resource URLs, remove credentials/query/fragment details, and cap them.
+// For example, https://host/app.js?token=x becomes https://host/app.js, while
+// data:image/svg+xml,<svg>...</svg> is rejected because its scheme is not HTTP(S).
+export function sanitizeResourceUrl(value: unknown): string | undefined {
+  if (typeof value !== 'string' || value.length === 0) {
+    return undefined;
+  }
+
+  const url = value.trim();
+  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(url)?.[1]?.toLowerCase();
+
+  if (scheme && scheme !== 'http' && scheme !== 'https') {
+    return undefined;
+  }
+
+  return truncate(removeUrlDetails(url), MAX_RESOURCE_URL_LENGTH);
+}
+
+export function removeUrlDetailsFromText(value: string | undefined): string | undefined {
+  // Redact non-HTTP(S) schemes and strip credentials, queries, and fragments from other URLs.
+  // Examples: data:text/plain,secret -> [redacted-url], https://host/api?token=x ->
+  // https://host/api, api/messages?token=x -> api/messages, and GET app.js?token=x -> GET app.js.
+  return (
+    value
+      // Handles root and dot-relative paths such as /api?token=x and ../app.js#fragment.
+      // These run before the scheme matcher so query values such as x:10 are not treated as URLs.
+      ?.replace(
+        /(^|[\s("'=[{])((?:\/|\.\.?\/)[^\s)"'\]}]+)/g,
+        (_, prefix, url) => `${prefix}${removeUrlDetails(url) ?? url}`
+      )
+      .replace(
+        // Handles bare paths with a slash or file extension, such as api/messages?x=1 or app.js#x.
+        /(^|[\s("'=[{])((?:(?:[a-z0-9._~%-]+\/)+(?:[a-z0-9._~%-]+)?|[a-z0-9._~%-]+\.[a-z0-9._~%-]+)[?#][^\s)"'\]}]+)/gi,
+        (_, prefix, url) => `${prefix}${removeUrlDetails(url) ?? url}`
+      )
+      .replace(
+        // Handles extensionless single-segment paths after an HTTP method, such as GET api?token=x.
+        /\b(DELETE|GET|HEAD|OPTIONS|PATCH|POST|PUT)(\s+)([a-z0-9._~%-]+[?#][^\s)"'\]}]+)/gi,
+        (_, method, spacing, url) => `${method}${spacing}${removeUrlDetails(url) ?? url}`
+      )
+      .replace(
+        // Handles URLs with a scheme, including assigned values such as url=https://host/path?x=1.
+        // HTTP(S) details are stripped; data:, blob:, and other schemes are fully redacted.
+        /(^|[\s("'=[{,;])(([a-z][a-z0-9+.-]*):[^\s)"'\]}]+)/gi,
+        (_, prefix, url, scheme) =>
+          `${prefix}${
+            ['http', 'https'].includes(scheme.toLowerCase())
+              ? removeUrlDetails(url) ?? url
+              : '[redacted-url]'
+          }`
+      )
+  );
+}
+
+export function createFingerprint(value: string): string {
+  // DJB2-style hash: multiply by 33, add each UTF-16 code unit, and constrain the result to 32 bits.
+  // It provides a small stable deduplication key; it is not intended for cryptographic use.
+  let hash = 5381;
+
+  for (let index = 0; index < value.length; index += 1) {
+    hash = (hash * 33 + value.charCodeAt(index)) % 4_294_967_296;
+  }
+
+  return hash.toString(16).padStart(8, '0');
+}
+
+export function stringifyReason(reason: unknown): string {
+  if (typeof reason === 'string') {
+    return reason;
+  }
+
+  try {
+    return JSON.stringify(reason) ?? String(reason);
+  } catch {
+    try {
+      return String(reason);
+    } catch {
+      return 'Unserializable rejection reason';
+    }
+  }
+}

package/test/unit/spec/new-metrics.ts

@@ -8,11 +8,14 @@ import {
 import MockWebex from '@webex/test-helper-mock-webex';
 import sinon from 'sinon';
 
+import SourceNewMetrics from '@webex/internal-plugin-metrics/src/new-metrics';
+import * as Telemetry from '@webex/internal-plugin-metrics/src/unhandled-exception-telemetry';
+
 describe('internal-plugin-metrics', () => {
-  const mockWebex = () =>
+  const mockWebex = (NewMetricsPlugin = NewMetrics) =>
     new MockWebex({
       children: {
-        newMetrics: NewMetrics,
+        newMetrics: NewMetricsPlugin,
       },
       meetings: {
         getBasicMeetingInformation: sinon.stub().callsFake((meetingId) => ({
@@ -73,6 +76,10 @@ describe('internal-plugin-metrics', () => {
   });
 
   describe('new-metrics contstructor', () => {
+    afterEach(() => {
+      sinon.restore();
+    });
+
     it('checks callDiagnosticLatencies is defined before ready emit', () => {
       const webex = mockWebex();
 
@@ -87,10 +94,12 @@ describe('internal-plugin-metrics', () => {
 
     it('can call buildClientEventFetchRequestOptions before ready', async () => {
       const webex = mockWebex();
-      const stub = sinon.stub(
-        webex.internal.newMetrics.callDiagnosticMetrics,
-        'buildClientEventFetchRequestOptions'
-      ).resolves({url: 'https://metrics.example.com'});
+      const stub = sinon
+        .stub(
+          webex.internal.newMetrics.callDiagnosticMetrics,
+          'buildClientEventFetchRequestOptions'
+        )
+        .resolves({url: 'https://metrics.example.com'});
 
       const result = await webex.internal.newMetrics.buildClientEventFetchRequestOptions({
         name: 'client.alert.displayed',
@@ -104,6 +113,17 @@ describe('internal-plugin-metrics', () => {
       });
       assert.deepEqual(result, {url: 'https://metrics.example.com'});
     });
+
+    it('starts unhandled exception telemetry when webex is ready', () => {
+      const start = sinon.stub(Telemetry, 'startUnhandledExceptionTelemetry');
+      const webex = mockWebex(SourceNewMetrics);
+
+      assert.notCalled(start);
+
+      webex.emit('ready');
+
+      assert.calledOnceWithExactly(start, webex);
+    });
   });
 
   describe('new-metrics', () => {

package/test/unit/spec/unhandled-exception-telemetry/utils.ts

@@ -0,0 +1,109 @@
+import {assert} from '@webex/test-helper-chai';
+
+import {
+  createFingerprint,
+  removeUrlDetails,
+  removeUrlDetailsFromText,
+  sanitizeResourceUrl,
+  stringifyReason,
+  truncate,
+} from '@webex/internal-plugin-metrics/src/unhandled-exception-telemetry/utils';
+
+const TEST_USERINFO = ['fixture-user', 'fixture-value'].join(':');
+
+describe('Unhandled exception telemetry utilities', () => {
+  describe('#truncate()', () => {
+    it('truncates strings to the requested length', () => {
+      assert.equal(truncate('abcdef', 3), 'abc');
+      assert.equal(truncate('abc', 3), 'abc');
+      assert.isUndefined(truncate(undefined, 3));
+    });
+  });
+
+  describe('#removeUrlDetails()', () => {
+    [
+      {
+        input: `https://${TEST_USERINFO}@example.test/path?secret=x#fragment`,
+        expected: 'https://example.test/path',
+      },
+      {input: `//${TEST_USERINFO}@example.test/path#fragment`, expected: '//example.test/path'},
+      {input: '/api/messages?secret=x', expected: '/api/messages'},
+      {input: '', expected: undefined},
+      {input: 42, expected: undefined},
+    ].forEach(({input, expected}) => {
+      it(`sanitizes ${JSON.stringify(input)}`, () => {
+        assert.strictEqual(removeUrlDetails(input), expected);
+      });
+    });
+  });
+
+  describe('#sanitizeResourceUrl()', () => {
+    [
+      {
+        input: ` https://${TEST_USERINFO}@example.test/app.js?secret=x `,
+        expected: 'https://example.test/app.js',
+      },
+      {input: '/assets/app.js?secret=x', expected: '/assets/app.js'},
+      {input: 'data:text/plain,secret', expected: undefined},
+      {input: 'blob:https://example.test/id', expected: undefined},
+      {input: undefined, expected: undefined},
+    ].forEach(({input, expected}) => {
+      it(`sanitizes ${JSON.stringify(input)}`, () => {
+        assert.strictEqual(sanitizeResourceUrl(input), expected);
+      });
+    });
+
+    it('caps resource URLs at 2048 characters', () => {
+      assert.lengthOf(sanitizeResourceUrl(`/${'x'.repeat(3_000)}`) as string, 2_048);
+    });
+  });
+
+  describe('#removeUrlDetailsFromText()', () => {
+    [
+      {
+        input: `url=https://${TEST_USERINFO}@example.test/path?secret=x`,
+        expected: 'url=https://example.test/path',
+      },
+      {input: 'payload=data:text/plain,secret', expected: 'payload=[redacted-url]'},
+      {input: 'GET /api/messages?secret=x', expected: 'GET /api/messages'},
+      {input: 'at load (../app.js#fragment:10:20)', expected: 'at load (../app.js)'},
+      {input: 'retry api/messages?secret=x', expected: 'retry api/messages'},
+      {input: 'at load (app.js?secret=x:10:20)', expected: 'at load (app.js)'},
+      {input: 'GET api?secret=x', expected: 'GET api'},
+    ].forEach(({input, expected}) => {
+      it(`sanitizes ${input}`, () => {
+        assert.equal(removeUrlDetailsFromText(input), expected);
+      });
+    });
+  });
+
+  describe('#createFingerprint()', () => {
+    it('returns a stable eight-character key that changes with its input', () => {
+      const fingerprint = createFingerprint('same error');
+
+      assert.lengthOf(fingerprint, 8);
+      assert.equal(createFingerprint('same error'), fingerprint);
+      assert.notEqual(createFingerprint('different error'), fingerprint);
+    });
+  });
+
+  describe('#stringifyReason()', () => {
+    it('serializes strings and objects', () => {
+      assert.equal(stringifyReason('failed'), 'failed');
+      assert.equal(stringifyReason({message: 'failed'}), '{"message":"failed"}');
+    });
+
+    it('falls back safely when conversion hooks throw', () => {
+      const reason = new Proxy(
+        {},
+        {
+          get() {
+            throw new Error('unreadable');
+          },
+        }
+      );
+
+      assert.equal(stringifyReason(reason), 'Unserializable rejection reason');
+    });
+  });
+});