feat(core): Add withIsolationScope (#10141)

Author: Luca Forstner

packages/astro/src/index.server.ts

@@ -46,6 +46,7 @@ export {
   // eslint-disable-next-line deprecation/deprecation
   trace,
   withScope,
+  withIsolationScope,
   autoDiscoverNodePerformanceMonitoringIntegrations,
   makeNodeTransport,
   defaultIntegrations,

packages/browser/src/exports.ts

@@ -60,6 +60,7 @@ export {
   setTags,
   setUser,
   withScope,
+  withIsolationScope,
   FunctionToString,
   InboundFilters,
   metrics,

packages/bun/src/index.ts

@@ -66,6 +66,7 @@ export {
   // eslint-disable-next-line deprecation/deprecation
   trace,
   withScope,
+  withIsolationScope,
   captureCheckIn,
   withMonitor,
   setMeasurement,

packages/core/src/exports.ts

@@ -25,6 +25,7 @@ import { GLOBAL_OBJ, isThenable, logger, timestampInSeconds, uuid4 } from '@sent
 import { DEFAULT_ENVIRONMENT } from './constants';
 import { DEBUG_BUILD } from './debug-build';
 import type { Hub } from './hub';
+import { runWithAsyncContext } from './hub';
 import { getCurrentHub, getIsolationScope } from './hub';
 import type { Scope } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
@@ -35,7 +36,7 @@ import { parseEventHintOrCaptureContext } from './utils/prepareEvent';
  * Captures an exception event and sends it to Sentry.
  *
  * @param exception The exception to capture.
- * @param hint Optinal additional data to attach to the Sentry event.
+ * @param hint Optional additional data to attach to the Sentry event.
  * @returns the id of the captured Sentry event.
  */
 export function captureException(
@@ -208,6 +209,26 @@ export function withScope<T>(
   return getCurrentHub().withScope(rest[0]);
 }
 
+/**
+ * Attempts to fork the current isolation scope and the current scope based on the current async context strategy. If no
+ * async context strategy is set, the isolation scope and the current scope will not be forked (this is currently the
+ * case, for example, in the browser).
+ *
+ * Usage of this function in environments without async context strategy is discouraged and may lead to unexpected behaviour.
+ *
+ * This function is intended for Sentry SDK and SDK integration development. It is not recommended to be used in "normal"
+ * applications directly because it comes with pitfalls. Use at your own risk!
+ *
+ * @param callback The callback in which the passed isolation scope is active. (Note: In environments without async
+ * context strategy, the currently active isolation scope may change within execution of the callback.)
+ * @returns The same value that `callback` returns.
+ */
+export function withIsolationScope<T>(callback: (isolationScope: Scope) => T): T {
+  return runWithAsyncContext(() => {
+    return callback(getIsolationScope());
+  });
+}
+
 /**
  * Starts a new `Transaction` and returns it. This is the entry point to manual tracing instrumentation.
  *

packages/core/src/index.ts

@@ -29,6 +29,7 @@ export {
   setTags,
   setUser,
   withScope,
+  withIsolationScope,
   getClient,
   getCurrentScope,
   startSession,

packages/core/test/lib/async-context.test.ts

@@ -0,0 +1,13 @@
+import { getCurrentHub, runWithAsyncContext } from '../../src';
+
+describe('runWithAsyncContext()', () => {
+  it('without strategy hubs should be equal', () => {
+    runWithAsyncContext(() => {
+      const hub1 = getCurrentHub();
+      runWithAsyncContext(() => {
+        const hub2 = getCurrentHub();
+        expect(hub1).toBe(hub2);
+      });
+    });
+  });
+});

packages/core/test/lib/scope.test.ts

@@ -1,5 +1,5 @@
 import type { Attachment, Breadcrumb, Client, Event } from '@sentry/types';
-import { applyScopeDataToEvent } from '../../src';
+import { applyScopeDataToEvent, getCurrentScope, getIsolationScope, withIsolationScope } from '../../src';
 import { Scope, getGlobalScope, setGlobalScope } from '../../src/scope';
 
 describe('Scope', () => {
@@ -465,3 +465,41 @@ describe('Scope', () => {
     });
   });
 });
+
+describe('isolation scope', () => {
+  describe('withIsolationScope()', () => {
+    it('will pass an isolation scope without Sentry.init()', done => {
+      expect.assertions(1);
+      withIsolationScope(scope => {
+        expect(scope).toBeDefined();
+        done();
+      });
+    });
+
+    it('will make the passed isolation scope the active isolation scope within the callback', done => {
+      expect.assertions(1);
+      withIsolationScope(scope => {
+        expect(getIsolationScope()).toBe(scope);
+        done();
+      });
+    });
+
+    it('will pass an isolation scope that is different from the current active scope', done => {
+      expect.assertions(1);
+      withIsolationScope(scope => {
+        expect(getCurrentScope()).not.toBe(scope);
+        done();
+      });
+    });
+
+    it('will always make the inner most passed scope the current scope when nesting calls', done => {
+      expect.assertions(1);
+      withIsolationScope(_scope1 => {
+        withIsolationScope(scope2 => {
+          expect(getIsolationScope()).toBe(scope2);
+          done();
+        });
+      });
+    });
+  });
+});

packages/deno/src/index.ts

@@ -65,6 +65,7 @@ export {
   // eslint-disable-next-line deprecation/deprecation
   trace,
   withScope,
+  withIsolationScope,
   captureCheckIn,
   withMonitor,
   setMeasurement,

packages/node/src/index.ts

@@ -65,6 +65,7 @@ export {
   // eslint-disable-next-line deprecation/deprecation
   trace,
   withScope,
+  withIsolationScope,
   captureCheckIn,
   withMonitor,
   setMeasurement,