add basic implementation for populating and retrieving versioned carrier

Author: Lms24

packages/core/src/carrier.ts

@@ -1,5 +1,6 @@
-import type { Integration } from '@sentry/types';
+import type { Integration, VersionString } from '@sentry/types';
 import { GLOBAL_OBJ } from '@sentry/utils';
+import type { AsyncContextStack } from './asyncContext/stackStrategy';
 import type { AsyncContextStrategy } from './asyncContext/types';
 import { SDK_VERSION } from './version';
 
@@ -11,10 +12,10 @@ export interface Carrier {
   __SENTRY__?: VersionedCarrier;
 }
 
-interface VersionedCarrier {
-  version: typeof SDK_VERSION;
-  [SDK_VERSION]: SentryCarrier;
-}
+type VersionedCarrier = {
+  [key: VersionString]: SentryCarrier;
+  version?: VersionString;
+};
 
 interface SentryCarrier {
   acs?: AsyncContextStrategy;
@@ -27,6 +28,7 @@ interface SentryCarrier {
     // eslint-disable-next-line @typescript-eslint/ban-types
     [key: string]: Function;
   };
+  stack?: AsyncContextStack;
 }
 
 /**
@@ -45,11 +47,19 @@ export function getMainCarrier(): Carrier {
 /** Will either get the existing sentry carrier, or create a new one. */
 export function getSentryCarrier(carrier: Carrier): SentryCarrier {
   if (!carrier.__SENTRY__) {
-    carrier.__SENTRY__ = {
-      version: SDK_VERSION,
-      [SDK_VERSION]: {
-        extensions: {},
-      },
+    carrier.__SENTRY__ = {};
+  }
+
+  // For now: First SDK that sets the .version property wins
+  if (!carrier.__SENTRY__.version) {
+    carrier.__SENTRY__.version = SDK_VERSION;
+  }
+
+  // Intentionally populating and returning the version of "this" SDK instance
+  // rather than what's set in .version so that "this" SDK always gets its carrier
+  if (!carrier.__SENTRY__[SDK_VERSION]) {
+    carrier.__SENTRY__[SDK_VERSION] = {
+      extensions: {},
     };
   }
   return carrier.__SENTRY__[SDK_VERSION];

packages/core/src/sdk.ts

@@ -2,7 +2,6 @@ import type { Client, ClientOptions } from '@sentry/types';
 import { consoleSandbox, logger } from '@sentry/utils';
 import { getCurrentScope } from './currentScopes';
 
-import type { AsyncContextStack } from './asyncContext/stackStrategy';
 import { getMainCarrier, getSentryCarrier } from './carrier';
 import { DEBUG_BUILD } from './debug-build';
 
@@ -50,13 +49,13 @@ export function setCurrentClient(client: Client): void {
 /**
  * Unfortunately, we still have to manually bind the client to the "hub" property set on the global
  * Sentry carrier object. This is because certain scripts (e.g. our loader script) obtain
- * the client via `window.__SENTRY__.hub.getClient()`.
+ * the client via `window.__SENTRY__[version].stack.getClient()`.
  *
  * @see {@link ./asyncContext/stackStrategy.ts getAsyncContextStack}
  */
 function registerClientOnGlobalHub(client: Client): void {
-  const sentryGlobal = getSentryCarrier(getMainCarrier()) as { hub?: AsyncContextStack };
-  if (sentryGlobal.hub && typeof sentryGlobal.hub.getStackTop === 'function') {
-    sentryGlobal.hub.getStackTop().client = client;
+  const sentryGlobal = getSentryCarrier(getMainCarrier());
+  if (sentryGlobal.stack && typeof sentryGlobal.stack.getStackTop === 'function') {
+    sentryGlobal.stack.getStackTop().client = client;
   }
 }

packages/core/test/lib/carrier.test.ts

@@ -0,0 +1,98 @@
+import { getSentryCarrier } from '../../src/carrier';
+import { SDK_VERSION } from '../../src/version';
+
+describe('getSentryCarrier', () => {
+  describe('base case (one SDK)', () => {
+    it('populates the default sentry carrier object if it does not exist', () => {
+      const globalObject = {};
+      const sentryCarrier = getSentryCarrier(globalObject);
+
+      expect(sentryCarrier).toEqual({
+        extensions: {},
+      });
+
+      expect(globalObject).toEqual({
+        __SENTRY__: {
+          version: SDK_VERSION,
+          [SDK_VERSION]: {
+            extensions: {},
+          },
+        },
+      });
+    });
+
+    it('returns the existing sentry carrier object if it already exists', () => {
+      const originalGlobalObject = {
+        __SENTRY__: {
+          version: SDK_VERSION,
+          [SDK_VERSION]: {
+            integrations: [() => {}],
+          },
+        },
+      };
+
+      const globalObject = { ...originalGlobalObject };
+      // @ts-expect-error - TS complains because the object spread makes the version key become type string
+      const sentryCarrier = getSentryCarrier(globalObject);
+
+      expect(sentryCarrier).toEqual({
+        integrations: [expect.any(Function)],
+      });
+
+      expect(globalObject).toStrictEqual(originalGlobalObject);
+    });
+  });
+
+  describe('multiple (older) SDKs', () => {
+    it("returns the version of the sentry carrier object of the SDK's version rather than the one set in .version", () => {
+      const sentryCarrier = getSentryCarrier({
+        __SENTRY__: {
+          version: '8.0.0' as const, // another SDK set this
+          '8.0.0': {
+            // and this object
+            extensions: {},
+          },
+          [SDK_VERSION]: {
+            integrations: [() => {}],
+          },
+          // @ts-expect-error - this is just a test object, no need to pass a hub
+          hub: {},
+        },
+      });
+
+      expect(sentryCarrier).toEqual({
+        integrations: [expect.any(Function)],
+      });
+    });
+
+    it("doesn't overwrite the .version property if it's already set and creates a new global sentry carrier for the SDK version if not set yet", () => {
+      const globalObject = {
+        __SENTRY__: {
+          version: '8.0.0' as const,
+          '8.0.0': {
+            // and this object
+            integrations: [() => {}],
+          },
+        },
+      };
+
+      const sentryCarrier = getSentryCarrier(globalObject);
+
+      expect(sentryCarrier).toEqual({
+        extensions: {},
+      });
+
+      expect(globalObject).toEqual({
+        __SENTRY__: {
+          version: '8.0.0',
+          '8.0.0': {
+            integrations: [expect.any(Function)],
+          },
+          [SDK_VERSION]: {
+            extensions: {},
+          },
+        },
+      });
+    });
+  });
+});

packages/types/src/index.ts

@@ -57,7 +57,7 @@ export type { Extra, Extras } from './extra';
 export type { Hub } from './hub';
 export type { Integration, IntegrationClass, IntegrationFn } from './integration';
 export type { Mechanism } from './mechanism';
-export type { ExtractedNodeRequestData, HttpHeaderValue, Primitive, WorkerLocation } from './misc';
+export type { ExtractedNodeRequestData, HttpHeaderValue, Primitive, WorkerLocation, VersionString } from './misc';
 export type { ClientOptions, Options } from './options';
 export type { Package } from './package';
 export type { PolymorphicEvent, PolymorphicRequest } from './polymorphics';

packages/types/src/misc.ts

@@ -65,3 +65,8 @@ export interface WorkerLocation {
 export type Primitive = number | string | boolean | bigint | symbol | null | undefined;
 
 export type HttpHeaderValue = string | string[] | number | null;
+
+/**
+ * Type representing a semver version string
+ */
+export type VersionString = `${number}.${number}.${number}${`-${string}${string}` | ''}`;

packages/utils/src/worldwide.ts

@@ -12,7 +12,7 @@
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
-import type { Client, MetricsAggregator, Scope } from '@sentry/types';
+import type { Client, MetricsAggregator, Scope, VersionString } from '@sentry/types';
 
 import type { SdkSource } from './env';
 
@@ -44,6 +44,17 @@ export interface InternalGlobal {
    */
   _sentryDebugIds?: Record<string, string>;
   __SENTRY__: {
+    [key: VersionString]: {
+      acs?: any;
+      integrations?: any[];
+      extensions?: {
+        /** Extra Hub properties injected by various SDKs */
+        // eslint-disable-next-line @typescript-eslint/ban-types
+        [key: string]: Function;
+      };
+      stack?: any;
+    };
+    version: VersionString;
     hub: any;
     logger: any;
     extensions?: {