Refactor PR to make matcher optional in makeMultiplexedTransport instead of

andreiborza · andreiborza · commit c40b38d359fe · 2025-12-01T23:47:42.000+01:00
exposing new extra api
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,67 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+### Important Changes
+
+- **feat(core): Make `matcher` parameter optional in `makeMultiplexedTransport` ([#10798](https://github.com/getsentry/sentry-javascript/pull/10798))** .
+
+The `matcher` parameter in `makeMultiplexedTransport` is now optional with a sensible default. This makes it much easier to use the multiplexed transport for sending events to multiple DSNs based on runtime configuration.
+
+**Before:**
+
+```javascript
+import { makeFetchTransport, makeMultiplexedTransport } from '@sentry/browser';
+
+const EXTRA_KEY = 'ROUTE_TO';
+
+const transport = makeMultiplexedTransport(makeFetchTransport, args => {
+  const event = args.getEvent();
+  if (event?.extra?.[EXTRA_KEY] && Array.isArray(event.extra[EXTRA_KEY])) {
+    return event.extra[EXTRA_KEY];
+  }
+  return [];
+});
+
+Sentry.init({
+  transport,
+  // ... other options
+});
+
+// Capture events with routing info
+Sentry.captureException(error, {
+  extra: {
+    [EXTRA_KEY]: [
+      { dsn: 'https://key1@sentry.io/project1', release: 'v1.0.0' },
+      { dsn: 'https://key2@sentry.io/project2' },
+    ],
+  },
+});
+```
+
+**After:**
+
+```javascript
+import { makeFetchTransport, makeMultiplexedTransport, MULTIPLEXED_TRANSPORT_EXTRA_KEY } from '@sentry/browser';
+
+// Just pass the transport generator - the default matcher handles the rest!
+Sentry.init({
+  transport: makeMultiplexedTransport(makeFetchTransport),
+  // ... other options
+});
+
+// Capture events with routing info using the exported constant
+Sentry.captureException(error, {
+  extra: {
+    [MULTIPLEXED_TRANSPORT_EXTRA_KEY]: [
+      { dsn: 'https://key1@sentry.io/project1', release: 'v1.0.0' },
+      { dsn: 'https://key2@sentry.io/project2' },
+    ],
+  },
+});
+```
+
+The default matcher looks for routing information in `event.extra[MULTIPLEXED_TRANSPORT_EXTRA_KEY]`. You can still provide a custom matcher function for advanced use cases.
+
 - **feat(nextjs): Support cacheComponents on turbopack ([#18304](https://github.com/getsentry/sentry-javascript/pull/18304))**
 
 This release adds support for `cacheComponents` on turbopack builds. We are working on adding support for this feature in webpack builds as well.
diff --git a/packages/browser/src/index.ts b/packages/browser/src/index.ts
@@ -57,8 +57,7 @@ export {
   getSpanStatusFromHttpCode,
   setHttpStatus,
   makeMultiplexedTransport,
-  makeSimpleMultiplexedTransport,
-  SIMPLE_MULTIPLEXED_TRANSPORT_EXTRA_ROUTING_KEY,
+  MULTIPLEXED_TRANSPORT_EXTRA_KEY,
   moduleMetadataIntegration,
   supabaseIntegration,
   instrumentSupabaseClient,
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -54,11 +54,7 @@ export { ServerRuntimeClient } from './server-runtime-client';
 export { initAndBind, setCurrentClient } from './sdk';
 export { createTransport } from './transports/base';
 export { makeOfflineTransport } from './transports/offline';
-export {
-  makeMultiplexedTransport,
-  makeSimpleMultiplexedTransport,
-  SIMPLE_MULTIPLEXED_TRANSPORT_EXTRA_ROUTING_KEY,
-} from './transports/multiplexed';
+export { makeMultiplexedTransport, MULTIPLEXED_TRANSPORT_EXTRA_KEY } from './transports/multiplexed';
 export { getIntegrationsToSetup, addIntegration, defineIntegration, installedIntegrations } from './integration';
 export {
   _INTERNAL_skipAiProviderWrapping,
diff --git a/packages/core/src/transports/multiplexed.ts b/packages/core/src/transports/multiplexed.ts
@@ -21,6 +21,12 @@ interface MatchParam {
 type RouteTo = { dsn: string; release: string };
 type Matcher = (param: MatchParam) => (string | RouteTo)[];
 
+/**
+ * Key used in event.extra to provide routing information for the multiplexed transport.
+ * Should contain an array of `{ dsn: string, release?: string }` objects.
+ */
+export const MULTIPLEXED_TRANSPORT_EXTRA_KEY = 'MULTIPLEXED_TRANSPORT_EXTRA_KEY';
+
 /**
  * Gets an event from an envelope.
  *
@@ -79,15 +85,33 @@ function overrideDsn(envelope: Envelope, dsn: string): Envelope {
 
 /**
  * Creates a transport that can send events to different DSNs depending on the envelope contents.
+ *
+ * If no matcher is provided, the transport will look for routing information in
+ * `event.extra[MULTIPLEXED_TRANSPORT_EXTRA_KEY]`, which should contain
+ * an array of `{ dsn: string, release?: string }` objects.
  */
 export function makeMultiplexedTransport<TO extends BaseTransportOptions>(
   createTransport: (options: TO) => Transport,
-  matcher: Matcher,
+  matcher?: Matcher,
 ): (options: TO) => Transport {
   return options => {
     const fallbackTransport = createTransport(options);
     const otherTransports: Map<string, Transport> = new Map();
 
+    // Use provided matcher or default to simple multiplexed transport behavior
+    const actualMatcher: Matcher =
+      matcher ||
+      (args => {
+        const event = args.getEvent();
+        if (
+          event?.extra?.[MULTIPLEXED_TRANSPORT_EXTRA_KEY] &&
+          Array.isArray(event.extra[MULTIPLEXED_TRANSPORT_EXTRA_KEY])
+        ) {
+          return event.extra[MULTIPLEXED_TRANSPORT_EXTRA_KEY];
+        }
+        return [];
+      });
+
     function getTransport(dsn: string, release: string | undefined): [string, Transport] | undefined {
       // We create a transport for every unique dsn/release combination as there may be code from multiple releases in
       // use at the same time
@@ -118,7 +142,7 @@ export function makeMultiplexedTransport<TO extends BaseTransportOptions>(
         return eventFromEnvelope(envelope, eventTypes);
       }
 
-      const transports = matcher({ envelope, getEvent })
+      const transports = actualMatcher({ envelope, getEvent })
         .map(result => {
           if (typeof result === 'string') {
             return getTransport(result, undefined);
@@ -151,26 +175,3 @@ export function makeMultiplexedTransport<TO extends BaseTransportOptions>(
     };
   };
 }
-
-export const SIMPLE_MULTIPLEXED_TRANSPORT_EXTRA_ROUTING_KEY = 'SIMPLE_MULTIPLEXED_TRANSPORT_ROUTE_TO';
-
-/**
- * Creates a transport that will send events to all DSNs provided in `event.extra[SIMPLE_MULTIPLEXED_TRANSPORT_EXTRA_ROUTING_KEY]`,
- * which should contain values in the format of `Array<{ dsn: string;, release: string; }>`.
- *
- * If the value is `undefined` or `[]`, the event will be sent to the `dsn` value provided in your Sentry SDK initialization options as a fallback mechanism.
- */
-export function makeSimpleMultiplexedTransport<TO extends BaseTransportOptions>(
-  transportGenerator: (options: TO) => Transport,
-): (options: TO) => Transport {
-  return makeMultiplexedTransport(transportGenerator, args => {
-    const event = args.getEvent();
-    if (
-      event?.extra?.[SIMPLE_MULTIPLEXED_TRANSPORT_EXTRA_ROUTING_KEY] &&
-      Array.isArray(event.extra[SIMPLE_MULTIPLEXED_TRANSPORT_EXTRA_ROUTING_KEY])
-    ) {
-      return event.extra[SIMPLE_MULTIPLEXED_TRANSPORT_EXTRA_ROUTING_KEY];
-    }
-    return [];
-  });
-}
diff --git a/packages/core/test/lib/transports/multiplexed.test.ts b/packages/core/test/lib/transports/multiplexed.test.ts
@@ -8,11 +8,7 @@ import {
   makeMultiplexedTransport,
   parseEnvelope,
 } from '../../../src';
-import {
-  eventFromEnvelope,
-  makeSimpleMultiplexedTransport,
-  SIMPLE_MULTIPLEXED_TRANSPORT_EXTRA_ROUTING_KEY,
-} from '../../../src/transports/multiplexed';
+import { eventFromEnvelope, MULTIPLEXED_TRANSPORT_EXTRA_KEY } from '../../../src/transports/multiplexed';
 import type { ClientReport } from '../../../src/types-hoist/clientreport';
 import type { Envelope, EventEnvelope, EventItem } from '../../../src/types-hoist/envelope';
 import type { TransactionEvent } from '../../../src/types-hoist/event';
@@ -247,11 +243,11 @@ describe('makeMultiplexedTransport', () => {
   });
 });
 
-describe('makeSimpleMultiplexedTransport()', () => {
-  it('sends events to targets provided in event.extra[SIMPLE_MULTIPLEXED_TRANSPORT_EXTRA_ROUTING_KEY]', async () => {
+describe('makeMultiplexedTransport() with default matcher', () => {
+  it('sends events to targets provided in event.extra[MULTIPLEXED_TRANSPORT_EXTRA_KEY]', async () => {
     expect.assertions(2);
 
-    const makeTransport = makeSimpleMultiplexedTransport(
+    const makeTransport = makeMultiplexedTransport(
       createTestTransport(
         url => {
           expect(url).toBe(DSN1_URL);
@@ -268,7 +264,7 @@ describe('makeSimpleMultiplexedTransport()', () => {
         {
           event_id: 'aa3ff046696b4bc6b609ce6d28fde9e2',
           extra: {
-            [SIMPLE_MULTIPLEXED_TRANSPORT_EXTRA_ROUTING_KEY]: [DSN1, DSN2],
+            [MULTIPLEXED_TRANSPORT_EXTRA_KEY]: [DSN1, DSN2],
           },
         },
       ] as EventItem,
@@ -278,10 +274,10 @@ describe('makeSimpleMultiplexedTransport()', () => {
     await transport.send(envelope);
   });
 
-  it('sends events to default DSN if event.extra[SIMPLE_MULTIPLEXED_TRANSPORT_EXTRA_ROUTING_KEY] is not set', async () => {
+  it('sends events to default DSN if event.extra[MULTIPLEXED_TRANSPORT_EXTRA_KEY] is not set', async () => {
     expect.assertions(1);
 
-    const makeTransport = makeSimpleMultiplexedTransport(
+    const makeTransport = makeMultiplexedTransport(
       createTestTransport(url => {
         expect(url).toBe(DSN1_URL);
       }),
@@ -300,10 +296,10 @@ describe('makeSimpleMultiplexedTransport()', () => {
     await transport.send(envelope);
   });
 
-  it('sends events to default DSN if event.extra[SIMPLE_MULTIPLEXED_TRANSPORT_EXTRA_ROUTING_KEY] is an empty array', async () => {
+  it('sends events to default DSN if event.extra[MULTIPLEXED_TRANSPORT_EXTRA_KEY] is an empty array', async () => {
     expect.assertions(1);
 
-    const makeTransport = makeSimpleMultiplexedTransport(
+    const makeTransport = makeMultiplexedTransport(
       createTestTransport(url => {
         expect(url).toBe(DSN1_URL);
       }),
@@ -315,7 +311,7 @@ describe('makeSimpleMultiplexedTransport()', () => {
         {
           event_id: 'aa3ff046696b4bc6b609ce6d28fde9e2',
           extra: {
-            [SIMPLE_MULTIPLEXED_TRANSPORT_EXTRA_ROUTING_KEY]: [],
+            [MULTIPLEXED_TRANSPORT_EXTRA_KEY]: [],
           },
         },
       ] as EventItem,
