feat(integrations): Add Spotlight integration (#3550)

Author: krystofwoldrich

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+### Features
+
+- Add [`@spotlightjs/spotlight`](https://spotlightjs.com/) support ([#3550](https://github.com/getsentry/sentry-react-native/pull/3550))
+
+  Download the `Spotlight` desktop application and add the integration to your `Sentry.init`.
+
+  ```javascript
+  import * as Sentry from '@sentry/react-native';
+
+  Sentry.init({
+    dsn: '___DSN___',
+    enableSpotlight: __DEV__,
+  });
+  ```
+
 ### Fixes
 
 - Prevent pod install crash when visionos is not present ([#3548](https://github.com/getsentry/sentry-react-native/pull/3548))

jest.config.js

@@ -1,7 +1,7 @@
 module.exports = {
   collectCoverage: true,
   preset: 'react-native',
-  setupFilesAfterEnv: ['jest-extended/all', '<rootDir>/test/mockConsole.ts'],
+  setupFilesAfterEnv: ['jest-extended/all', '<rootDir>/test/mockConsole.ts', '<rootDir>/test/mockFetch.ts'],
   globals: {
     __DEV__: true,
     'ts-jest': {

package.json

@@ -96,6 +96,7 @@
     "expo-module-scripts": "^3.1.0",
     "jest": "^29.6.2",
     "jest-environment-jsdom": "^29.6.2",
+    "jest-fetch-mock": "^3.0.3",
     "jest-extended": "^4.0.2",
     "madge": "^6.1.0",
     "metro": "0.76",

samples/expo/app/(tabs)/index.tsx

@@ -62,6 +62,7 @@ Sentry.init({
   _experiments: {
     profilesSampleRate: 0,
   },
+  enableSpotlight: true,
 });
 
 export default function TabOneScreen() {

samples/react-native/src/App.tsx

@@ -93,6 +93,7 @@ Sentry.init({
   _experiments: {
     profilesSampleRate: 0,
   },
+  enableSpotlight: true,
 });
 
 const Stack = createStackNavigator();

src/js/integrations/default.ts

@@ -18,6 +18,7 @@ import { Release } from './release';
 import { createReactNativeRewriteFrames } from './rewriteframes';
 import { Screenshot } from './screenshot';
 import { SdkInfo } from './sdkinfo';
+import { Spotlight } from './spotlight';
 import { ViewHierarchy } from './viewhierarchy';
 
 /**
@@ -94,5 +95,13 @@ export function getDefaultIntegrations(options: ReactNativeClientOptions): Integ
     integrations.push(new ExpoContext());
   }
 
+  if (options.enableSpotlight) {
+    integrations.push(
+      Spotlight({
+        sidecarUrl: options.spotlightSidecarUrl,
+      }),
+    );
+  }
+
   return integrations;
 }

src/js/integrations/index.ts

@@ -7,3 +7,4 @@ export { SdkInfo } from './sdkinfo';
 export { ReactNativeInfo } from './reactnativeinfo';
 export { ModulesLoader } from './modulesloader';
 export { HermesProfiling } from '../profiling/integration';
+export { Spotlight } from './spotlight';

src/js/integrations/spotlight.ts

@@ -0,0 +1,98 @@
+import type { Client, Envelope, EventProcessor, Integration } from '@sentry/types';
+import { logger, serializeEnvelope } from '@sentry/utils';
+
+import { makeUtf8TextEncoder } from '../transports/TextEncoder';
+import { ReactNativeLibraries } from '../utils/rnlibraries';
+
+type SpotlightReactNativeIntegrationOptions = {
+  /**
+   * The URL of the Sidecar instance to connect and forward events to.
+   * If not set, Spotlight will try to connect to the Sidecar running on localhost:8969.
+   *
+   * @default "http://localhost:8969/stream"
+   */
+  sidecarUrl?: string;
+};
+
+/**
+ * Use this integration to send errors and transactions to Spotlight.
+ *
+ * Learn more about spotlight at https://spotlightjs.com
+ */
+export function Spotlight({
+  sidecarUrl = getDefaultSidecarUrl(),
+}: SpotlightReactNativeIntegrationOptions = {}): Integration {
+  logger.info('[Spotlight] Using Sidecar URL', sidecarUrl);
+
+  return {
+    name: 'Spotlight',
+
+    setupOnce(_: (callback: EventProcessor) => void, getCurrentHub) {
+      const client = getCurrentHub().getClient();
+      if (client) {
+        setup(client, sidecarUrl);
+      } else {
+        logger.warn('[Spotlight] Could not initialize Sidecar integration due to missing Client');
+      }
+    },
+  };
+}
+
+function setup(client: Client, sidecarUrl: string): void {
+  sendEnvelopesToSidecar(client, sidecarUrl);
+}
+
+function sendEnvelopesToSidecar(client: Client, sidecarUrl: string): void {
+  if (!client.on) {
+    return;
+  }
+
+  client.on('beforeEnvelope', (originalEnvelope: Envelope) => {
+    // TODO: This is a workaround for spotlight/sidecar not supporting images
+    const spotlightEnvelope: Envelope = [...originalEnvelope];
+    const envelopeItems = [...originalEnvelope[1]].filter(
+      item => typeof item[0].content_type !== 'string' || !item[0].content_type.startsWith('image'),
+    );
+
+    spotlightEnvelope[1] = envelopeItems as Envelope[1];
+
+    fetch(sidecarUrl, {
+      method: 'POST',
+      body: serializeEnvelope(spotlightEnvelope, makeUtf8TextEncoder()),
+      headers: {
+        'Content-Type': 'application/x-sentry-envelope',
+      },
+      mode: 'cors',
+    }).catch(err => {
+      logger.error(
+        "[Spotlight] Sentry SDK can't connect to Spotlight is it running? See https://spotlightjs.com to download it.",
+        err,
+      );
+    });
+  });
+}
+
+function getDefaultSidecarUrl(): string {
+  try {
+    const { url } = ReactNativeLibraries.Devtools?.getDevServer();
+    return `http://${getHostnameFromString(url)}:8969/stream`;
+  } catch (_oO) {
+    // We can't load devserver URL
+  }
+  return 'http://localhost:8969/stream';
+}
+
+/**
+ * React Native implementation of the URL class is missing the `hostname` property.
+ */
+function getHostnameFromString(urlString: string): string | null {
+  const regex = /^(?:\w+:)?\/\/([^/:]+)(:\d+)?(.*)$/;
+  const matches = urlString.match(regex);
+
+  if (matches && matches[1]) {
+    return matches[1];
+  } else {
+    // Invalid URL format
+    return null;
+  }
+}

src/js/options.ts

@@ -159,6 +159,27 @@ export interface BaseReactNativeOptions {
    * @default false
    */
   enableCaptureFailedRequests?: boolean;
+
+  /**
+   * This option will enable forwarding captured Sentry events to Spotlight.
+   *
+   * More details: https://spotlightjs.com/
+   *
+   * IMPORTANT: Only set this option to `true` while developing, not in production!
+   */
+  enableSpotlight?: boolean;
+
+  /**
+   * This option changes the default Spotlight Sidecar URL.
+   *
+   * By default, the SDK expects the Sidecar to be running
+   * on the same host as React Native Metro Dev Server.
+   *
+   * More details: https://spotlightjs.com/
+   *
+   * @default "http://localhost:8969/stream"
+   */
+  spotlightSidecarUrl?: string;
 }
 
 export interface ReactNativeTransportOptions extends BrowserTransportOptions {

test/integrations/spotlight.test.ts

@@ -0,0 +1,97 @@
+import type { Envelope, Hub } from '@sentry/types';
+import fetchMock from 'jest-fetch-mock';
+
+import { Spotlight } from '../../src/js/integrations/spotlight';
+
+describe('spotlight', () => {
+  it('should not change the original envelope', () => {
+    const mockHub = createMockHub();
+
+    const spotlight = Spotlight();
+    spotlight.setupOnce(
+      () => {},
+      () => mockHub as unknown as Hub,
+    );
+
+    const spotlightBeforeEnvelope = mockHub.getClient().on.mock.calls[0]?.[1] as
+      | ((envelope: Envelope) => void)
+      | undefined;
+
+    const originalEnvelopeReference = createMockEnvelope();
+    spotlightBeforeEnvelope?.(originalEnvelopeReference);
+
+    expect(spotlightBeforeEnvelope).toBeDefined();
+    expect(originalEnvelopeReference).toEqual(createMockEnvelope());
+  });
+
+  it('should remove image attachments from spotlight envelope', () => {
+    fetchMock.mockOnce();
+    const mockHub = createMockHub();
+
+    const spotlight = Spotlight();
+    spotlight.setupOnce(
+      () => {},
+      () => mockHub as unknown as Hub,
+    );
+
+    const spotlightBeforeEnvelope = mockHub.getClient().on.mock.calls[0]?.[1] as
+      | ((envelope: Envelope) => void)
+      | undefined;
+
+    spotlightBeforeEnvelope?.(createMockEnvelope());
+
+    expect(spotlightBeforeEnvelope).toBeDefined();
+    expect(fetchMock.mock.lastCall?.[1]?.body?.toString().includes('image/png')).toBe(false);
+  });
+});
+
+function createMockHub() {
+  const client = {
+    on: jest.fn(),
+  };
+
+  return {
+    getClient: jest.fn().mockReturnValue(client),
+  };
+}
+
+function createMockEnvelope(): Envelope {
+  return [
+    {
+      event_id: 'event_id',
+      sent_at: 'sent_at',
+      sdk: {
+        name: 'sdk_name',
+        version: 'sdk_version',
+      },
+    },
+    [
+      [
+        {
+          type: 'event',
+          length: 0,
+        },
+        {
+          event_id: 'event_id',
+        },
+      ],
+      [
+        {
+          type: 'attachment',
+          length: 10,
+          filename: 'filename',
+        },
+        'attachment',
+      ],
+      [
+        {
+          type: 'attachment',
+          length: 8,
+          filename: 'filename2',
+          content_type: 'image/png',
+        },
+        Uint8Array.from([137, 80, 78, 71, 13, 10, 26, 10]), // PNG header
+      ],
+    ],
+  ];
+}