feat(core): Add async context abstraction

packages/core/src/hub.ts

@@ -50,6 +50,14 @@ export const API_VERSION = 4;
  */
 const DEFAULT_BREADCRUMBS = 100;
 
+/**
+ * Strategy used to track async context.
+ */
+export interface AsyncContextStrategy {
+  getCurrentHub: () => Hub | undefined;
+  runWithAsyncContext<T, A>(callback: (hub: Hub, ...args: A[]) => T, ...args: A[]): T;
+}
+
 /**
  * A layer in the process stack.
  * @hidden
@@ -66,6 +74,7 @@ export interface Layer {
 export interface Carrier {
   __SENTRY__?: {
     hub?: Hub;
+    asyncContextStrategy?: AsyncContextStrategy;
     /**
      * Extra Hub properties injected by various SDKs
      */
@@ -519,6 +528,14 @@ export function getCurrentHub(): Hub {
   // Get main carrier (global for every environment)
   const registry = getMainCarrier();
 
+  if (registry.__SENTRY__ && registry.__SENTRY__.asyncContextStrategy) {
+    const hub = registry.__SENTRY__.asyncContextStrategy.getCurrentHub();
+
+    if (hub) {
+      return hub;
+    }
+  }
+
   // If there's no hub, or its an old API, assign a new one
   if (!hasHubOnCarrier(registry) || getHubFromCarrier(registry).isOlderThan(API_VERSION)) {
     setHubOnCarrier(registry, new Hub());
@@ -532,6 +549,30 @@ export function getCurrentHub(): Hub {
   return getHubFromCarrier(registry);
 }
 
+/**
+ * Sets the global async context strategy
+ */
+export function setAsyncContextStrategy(strategy: AsyncContextStrategy): void {
+  // Get main carrier (global for every environment)
+  const registry = getMainCarrier();
+  registry.__SENTRY__ = registry.__SENTRY__ || {};
+  registry.__SENTRY__.asyncContextStrategy = strategy;
+}
+
+/**
+ * Runs the given callback function with the global async context strategy
+ */
+export function runWithAsyncContext<T, A>(callback: (hub: Hub, ...args: A[]) => T, ...args: A[]): T {
+  const registry = getMainCarrier();
+
+  if (registry.__SENTRY__ && registry.__SENTRY__.asyncContextStrategy) {
+    return registry.__SENTRY__.asyncContextStrategy.runWithAsyncContext(callback, ...args);
+  }
+
+  // if there was no asyncContextStrategy, fallback to just calling the callback
+  return callback(getCurrentHub(), ...args);
+}
+
 /**
  * Try to read the hub from an active domain, and fallback to the registry if one doesn't exist
  * @returns discovered hub

packages/core/src/index.ts

@@ -1,5 +1,5 @@
 export type { ClientClass } from './sdk';
-export type { Carrier, Layer } from './hub';
+export type { AsyncContextStrategy, Carrier, Layer } from './hub';
 export type { OfflineStore, OfflineTransportOptions } from './transports/offline';
 
 export * from './tracing';
@@ -18,7 +18,15 @@ export {
   setUser,
   withScope,
 } from './exports';
-export { getCurrentHub, getHubFromCarrier, Hub, makeMain, getMainCarrier, setHubOnCarrier } from './hub';
+export {
+  getCurrentHub,
+  getHubFromCarrier,
+  Hub,
+  makeMain,
+  getMainCarrier,
+  setHubOnCarrier,
+  runWithAsyncContext,
+} from './hub';
 export { makeSession, closeSession, updateSession } from './session';
 export { SessionFlusher } from './sessionflusher';
 export { addGlobalEventProcessor, Scope } from './scope';