feat(flags): Add Unleash browser integration (#15036)

Ref getsentry/team-replay#514. Adds an
integration for tracking Unleash flag evaluations, by patching the
[isEnabled](https://docs.getunleash.io/reference/sdks/javascript-browser#step-4-check-feature-toggle-states)
method prototype.
Ref https://develop.sentry.dev/sdk/expected-features/#feature-flags

PR pointing to v8:
#14948

Author: aliu39

dev-packages/browser-integration-tests/suites/integrations/featureFlags/unleash/badSignature/init.js

@@ -0,0 +1,17 @@
+import * as Sentry from '@sentry/browser';
+
+window.UnleashClient = class {
+  isEnabled(x) {
+    return x;
+  }
+};
+
+window.Sentry = Sentry;
+window.sentryUnleashIntegration = Sentry.unleashIntegration({ unleashClientClass: window.UnleashClient });
+
+Sentry.init({
+  dsn: 'https://[email protected]/1337',
+  sampleRate: 1.0,
+  integrations: [window.sentryUnleashIntegration],
+  debug: true, // Required to test logging.
+});

dev-packages/browser-integration-tests/suites/integrations/featureFlags/unleash/badSignature/test.ts

@@ -0,0 +1,59 @@
+import { expect } from '@playwright/test';
+
+import { sentryTest } from '../../../../../utils/fixtures';
+
+import { shouldSkipFeatureFlagsTest } from '../../../../../utils/helpers';
+
+sentryTest('Logs and returns if isEnabled does not match expected signature', async ({ getLocalTestUrl, page }) => {
+  if (shouldSkipFeatureFlagsTest()) {
+    sentryTest.skip();
+  }
+  const bundleKey = process.env.PW_BUNDLE || '';
+  const hasDebug = !bundleKey.includes('_min');
+
+  await page.route('https://dsn.ingest.sentry.io/**/*', route => {
+    return route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ id: 'test-id' }),
+    });
+  });
+
+  const url = await getLocalTestUrl({ testDir: __dirname, skipDsnRouteHandler: true });
+  await page.goto(url);
+
+  const errorLogs: string[] = [];
+  page.on('console', msg => {
+    if (msg.type() == 'error') {
+      errorLogs.push(msg.text());
+    }
+  });
+
+  const results = await page.evaluate(() => {
+    const unleash = new (window as any).UnleashClient();
+    const res1 = unleash.isEnabled('my-feature');
+    const res2 = unleash.isEnabled(999);
+    const res3 = unleash.isEnabled({});
+    return [res1, res2, res3];
+  });
+
+  // Test that the expected results are still returned. Note isEnabled is identity function for this test.
+  expect(results).toEqual(['my-feature', 999, {}]);
+
+  // Expected error logs.
+  if (hasDebug) {
+    expect(errorLogs).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining(
+          '[Feature Flags] UnleashClient.isEnabled does not match expected signature. arg0: my-feature (string), result: my-feature (string)',
+        ),
+        expect.stringContaining(
+          '[Feature Flags] UnleashClient.isEnabled does not match expected signature. arg0: 999 (number), result: 999 (number)',
+        ),
+        expect.stringContaining(
+          '[Feature Flags] UnleashClient.isEnabled does not match expected signature. arg0: [object Object] (object), result: [object Object] (object)',
+        ),
+      ]),
+    );
+  }
+});

dev-packages/browser-integration-tests/suites/integrations/featureFlags/unleash/basic/test.ts

@@ -0,0 +1,58 @@
+import { expect } from '@playwright/test';
+
+import { sentryTest } from '../../../../../utils/fixtures';
+
+import { envelopeRequestParser, shouldSkipFeatureFlagsTest, waitForErrorRequest } from '../../../../../utils/helpers';
+
+const FLAG_BUFFER_SIZE = 100; // Corresponds to constant in featureFlags.ts, in browser utils.
+
+sentryTest('Basic test with eviction, update, and no async tasks', async ({ getLocalTestUrl, page }) => {
+  if (shouldSkipFeatureFlagsTest()) {
+    sentryTest.skip();
+  }
+
+  await page.route('https://dsn.ingest.sentry.io/**/*', route => {
+    return route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ id: 'test-id' }),
+    });
+  });
+
+  const url = await getLocalTestUrl({ testDir: __dirname, skipDsnRouteHandler: true });
+  await page.goto(url);
+
+  await page.evaluate(bufferSize => {
+    const client = new (window as any).UnleashClient();
+
+    client.isEnabled('feat1');
+    client.isEnabled('strFeat');
+    client.isEnabled('noPayloadFeat');
+    client.isEnabled('jsonFeat');
+    client.isEnabled('noVariantFeat');
+    client.isEnabled('disabledFeat');
+
+    for (let i = 7; i <= bufferSize; i++) {
+      client.isEnabled(`feat${i}`);
+    }
+    client.isEnabled(`feat${bufferSize + 1}`); // eviction
+    client.isEnabled('noPayloadFeat'); // update (move to tail)
+  }, FLAG_BUFFER_SIZE);
+
+  const reqPromise = waitForErrorRequest(page);
+  await page.locator('#error').click();
+  const req = await reqPromise;
+  const event = envelopeRequestParser(req);
+
+  const expectedFlags = [{ flag: 'strFeat', result: true }];
+  expectedFlags.push({ flag: 'jsonFeat', result: true });
+  expectedFlags.push({ flag: 'noVariantFeat', result: true });
+  expectedFlags.push({ flag: 'disabledFeat', result: false });
+  for (let i = 7; i <= FLAG_BUFFER_SIZE; i++) {
+    expectedFlags.push({ flag: `feat${i}`, result: false });
+  }
+  expectedFlags.push({ flag: `feat${FLAG_BUFFER_SIZE + 1}`, result: false });
+  expectedFlags.push({ flag: 'noPayloadFeat', result: true });
+
+  expect(event.contexts?.flags?.values).toEqual(expectedFlags);
+});

dev-packages/browser-integration-tests/suites/integrations/featureFlags/unleash/init.js

@@ -0,0 +1,50 @@
+import * as Sentry from '@sentry/browser';
+
+window.UnleashClient = class {
+  constructor() {
+    this._featureToVariant = {
+      strFeat: { name: 'variant1', enabled: true, feature_enabled: true, payload: { type: 'string', value: 'test' } },
+      noPayloadFeat: { name: 'eu-west', enabled: true, feature_enabled: true },
+      jsonFeat: {
+        name: 'paid-orgs',
+        enabled: true,
+        feature_enabled: true,
+        payload: {
+          type: 'json',
+          value: '{"foo": {"bar": "baz"}, "hello": [1, 2, 3]}',
+        },
+      },
+
+      // Enabled feature with no configured variants.
+      noVariantFeat: { name: 'disabled', enabled: false, feature_enabled: true },
+
+      // Disabled feature.
+      disabledFeat: { name: 'disabled', enabled: false, feature_enabled: false },
+    };
+
+    // Variant returned for features that don't exist.
+    // `feature_enabled` may be defined in prod, but we want to test the undefined case.
+    this._fallbackVariant = {
+      name: 'disabled',
+      enabled: false,
+    };
+  }
+
+  isEnabled(toggleName) {
+    const variant = this._featureToVariant[toggleName] || this._fallbackVariant;
+    return variant.feature_enabled || false;
+  }
+
+  getVariant(toggleName) {
+    return this._featureToVariant[toggleName] || this._fallbackVariant;
+  }
+};
+
+window.Sentry = Sentry;
+window.sentryUnleashIntegration = Sentry.unleashIntegration({ unleashClientClass: window.UnleashClient });
+
+Sentry.init({
+  dsn: 'https://[email protected]/1337',
+  sampleRate: 1.0,
+  integrations: [window.sentryUnleashIntegration],
+});

dev-packages/browser-integration-tests/suites/integrations/featureFlags/unleash/subject.js

@@ -0,0 +1,3 @@
+document.getElementById('error').addEventListener('click', () => {
+  throw new Error('Button triggered error');
+});

dev-packages/browser-integration-tests/suites/integrations/featureFlags/unleash/template.html

@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+  </head>
+  <body>
+    <button id="error">Throw Error</button>
+  </body>
+</html>

dev-packages/browser-integration-tests/suites/integrations/featureFlags/unleash/withScope/test.ts

@@ -0,0 +1,65 @@
+import { expect } from '@playwright/test';
+
+import { sentryTest } from '../../../../../utils/fixtures';
+
+import { envelopeRequestParser, shouldSkipFeatureFlagsTest, waitForErrorRequest } from '../../../../../utils/helpers';
+
+import type { Scope } from '@sentry/browser';
+
+sentryTest('Flag evaluations in forked scopes are stored separately.', async ({ getLocalTestUrl, page }) => {
+  if (shouldSkipFeatureFlagsTest()) {
+    sentryTest.skip();
+  }
+
+  await page.route('https://dsn.ingest.sentry.io/**/*', route => {
+    return route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ id: 'test-id' }),
+    });
+  });
+
+  const url = await getLocalTestUrl({ testDir: __dirname, skipDsnRouteHandler: true });
+  await page.goto(url);
+
+  const forkedReqPromise = waitForErrorRequest(page, event => !!event.tags && event.tags.isForked === true);
+  const mainReqPromise = waitForErrorRequest(page, event => !!event.tags && event.tags.isForked === false);
+
+  await page.evaluate(() => {
+    const Sentry = (window as any).Sentry;
+    const errorButton = document.querySelector('#error') as HTMLButtonElement;
+    const unleash = new (window as any).UnleashClient();
+
+    unleash.isEnabled('strFeat');
+
+    Sentry.withScope((scope: Scope) => {
+      unleash.isEnabled('disabledFeat');
+      unleash.isEnabled('strFeat');
+      scope.setTag('isForked', true);
+      if (errorButton) {
+        errorButton.click();
+      }
+    });
+
+    unleash.isEnabled('noPayloadFeat');
+    Sentry.getCurrentScope().setTag('isForked', false);
+    errorButton.click();
+    return true;
+  });
+
+  const forkedReq = await forkedReqPromise;
+  const forkedEvent = envelopeRequestParser(forkedReq);
+
+  const mainReq = await mainReqPromise;
+  const mainEvent = envelopeRequestParser(mainReq);
+
+  expect(forkedEvent.contexts?.flags?.values).toEqual([
+    { flag: 'disabledFeat', result: false },
+    { flag: 'strFeat', result: true },
+  ]);
+
+  expect(mainEvent.contexts?.flags?.values).toEqual([
+    { flag: 'strFeat', result: true },
+    { flag: 'noPayloadFeat', result: true },
+  ]);
+});

packages/browser/src/index.ts

@@ -67,3 +67,4 @@ export {
 } from './integrations/featureFlags';
 export { launchDarklyIntegration, buildLaunchDarklyFlagUsedHandler } from './integrations/featureFlags/launchdarkly';
 export { openFeatureIntegration, OpenFeatureIntegrationHook } from './integrations/featureFlags/openfeature';
+export { unleashIntegration } from './integrations/featureFlags/unleash';

packages/browser/src/integrations/featureFlags/unleash/index.ts

@@ -0,0 +1 @@
+export { unleashIntegration } from './integration';

packages/browser/src/integrations/featureFlags/unleash/integration.ts

@@ -0,0 +1,73 @@
+import type { Client, Event, EventHint, IntegrationFn } from '@sentry/core';
+
+import { defineIntegration, fill, logger } from '@sentry/core';
+import { DEBUG_BUILD } from '../../../debug-build';
+import { copyFlagsFromScopeToEvent, insertFlagToScope } from '../../../utils/featureFlags';
+import type { UnleashClient, UnleashClientClass } from './types';
+
+/**
+ * Sentry integration for capturing feature flag evaluations from the Unleash SDK.
+ *
+ * See the [feature flag documentation](https://develop.sentry.dev/sdk/expected-features/#feature-flags) for more information.
+ *
+ * @example
+ * ```
+ * import { UnleashClient } from 'unleash-proxy-client';
+ * import * as Sentry from '@sentry/browser';
+ *
+ * Sentry.init({
+ *   dsn: '___PUBLIC_DSN___',
+ *   integrations: [Sentry.unleashIntegration({unleashClientClass: UnleashClient})],
+ * });
+ *
+ * const unleash = new UnleashClient(...);
+ * unleash.start();
+ *
+ * unleash.isEnabled('my-feature');
+ * unleash.getVariant('other-feature');
+ * Sentry.captureException(new Error('something went wrong'));
+ * ```
+ */
+export const unleashIntegration = defineIntegration(
+  ({ unleashClientClass }: { unleashClientClass: UnleashClientClass }) => {
+    return {
+      name: 'Unleash',
+
+      processEvent(event: Event, _hint: EventHint, _client: Client): Event {
+        return copyFlagsFromScopeToEvent(event);
+      },
+
+      setupOnce() {
+        const unleashClientPrototype = unleashClientClass.prototype as UnleashClient;
+        fill(unleashClientPrototype, 'isEnabled', _wrappedIsEnabled);
+      },
+    };
+  },
+) satisfies IntegrationFn;
+
+/**
+ * Wraps the UnleashClient.isEnabled method to capture feature flag evaluations. Its only side effect is writing to Sentry scope.
+ *
+ * This wrapper is safe for all isEnabled signatures. If the signature does not match (this: UnleashClient, toggleName: string, ...args: unknown[]) => boolean,
+ * we log an error and return the original result.
+ *
+ * @param original - The original method.
+ * @returns Wrapped method. Results should match the original.
+ */
+function _wrappedIsEnabled(
+  original: (this: UnleashClient, ...args: unknown[]) => unknown,
+): (this: UnleashClient, ...args: unknown[]) => unknown {
+  return function (this: UnleashClient, ...args: unknown[]): unknown {
+    const toggleName = args[0];
+    const result = original.apply(this, args);
+
+    if (typeof toggleName === 'string' && typeof result === 'boolean') {
+      insertFlagToScope(toggleName, result);
+    } else if (DEBUG_BUILD) {
+      logger.error(
+        `[Feature Flags] UnleashClient.isEnabled does not match expected signature. arg0: ${toggleName} (${typeof toggleName}), result: ${result} (${typeof result})`,
+      );
+    }
+    return result;
+  };
+}

packages/browser/src/integrations/featureFlags/unleash/types.ts

@@ -0,0 +1,23 @@
+export interface IVariant {
+  name: string;
+  enabled: boolean;
+  feature_enabled?: boolean;
+  payload?: {
+    type: string;
+    value: string;
+  };
+}
+
+export interface UnleashClient {
+  isEnabled(this: UnleashClient, featureName: string): boolean;
+  getVariant(this: UnleashClient, featureName: string): IVariant;
+}
+
+export interface IConfig {
+  [key: string]: unknown;
+  appName: string;
+  clientKey: string;
+  url: URL | string;
+}
+
+export type UnleashClientClass = new (config: IConfig) => UnleashClient;