fix(next): Wrap all Random APIs with a safe runner (#18700)

Currently the cache components feature in Next.js prevents us from using
any random value APIs like:

- `Date.now`
- `performance.now`
- `Math.random`
- `crypto.*`

We tried resolving this by patching several span methods, but then we
have plenty of other instances where we use those APIs, like in trace
propagation, timestamp generation for logs, and more.

Running around and patching them one by one in the Next.js SDK isn't a
viable solution since most of those functionalities are strictly
internal and cannot be patched from the outside, and adding escape
hatches for each of them is not maintainable.

So I'm testing out the other way around, by hunting those APIs down and
wrapping them with a safe runner that acts as an escape hatch. Some of
the Vercel engineers suggested doing that, but we need to do it for
~almost every call~ (see Josh
[comment](#18700 (comment))
below).

The idea is an SDK can "turn on" the safe runner by injecting a global
function that executes a callback and returns its results. I

### How does this fix it for Next.js?

The Next.js SDK case, a safe runner would be an `AsyncLocalStorage`
snapshot which is captured at the server runtime init, way before any
rendering is done.

```ts
const sym = Symbol.for('__SENTRY_SAFE_RANDOM_ID_WRAPPER__');
const globalWithSymbol: typeof GLOBAL_OBJ & { [sym]?: SafeRandomContextRunner } = GLOBAL_OBJ;

globalWithSymbol[sym] = AsyncLocalStorage.snapshot();

// core SDK then offers a fn to run any random gen function
export function withRandomSafeContext<T>(cb: () => T): T {
  // Looks for the global symbol and if it is set it uses the runner
  // otherwise just runs the callback normally.
}
```

I kept the API internal as much as possible to avoid users messing up
with it, but the `@sentry/opentelemetry` SDK also needed this
functionality so I exported the API with `_INTERNAL` prefix as we
already do.

---

I tested this in a simple Next.js app and it no longer errors out, and
all current tests pass. I still need to take a look at the traces and
see how would they look in cached component cases.

Charly is already working on this and may have a proper solution, but I
thought to just see if we can ship a stopgap until then.

On the bright side, this seems to fix it as well for Webpack.

closes #18392 
closes #18340

Author: logaretm

.size-limit.js

@@ -82,7 +82,7 @@ module.exports = [
     path: 'packages/browser/build/npm/esm/prod/index.js',
     import: createImport('init', 'browserTracingIntegration', 'replayIntegration', 'replayCanvasIntegration'),
     gzip: true,
-    limit: '85 KB',
+    limit: '85.5 KB',
   },
   {
     name: '@sentry/browser (incl. Tracing, Replay, Feedback)',
@@ -243,7 +243,7 @@ module.exports = [
     import: createImport('init'),
     ignore: ['$app/stores'],
     gzip: true,
-    limit: '42 KB',
+    limit: '42.5 KB',
   },
   // Node-Core SDK (ESM)
   {
@@ -261,7 +261,7 @@ module.exports = [
     import: createImport('init'),
     ignore: [...builtinModules, ...nodePrefixedBuiltinModules],
     gzip: true,
-    limit: '162 KB',
+    limit: '162.5 KB',
   },
   {
     name: '@sentry/node - without tracing',

dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/metadata-async/page.tsx

@@ -0,0 +1,37 @@
+import * as Sentry from '@sentry/nextjs';
+
+function fetchPost() {
+  return Promise.resolve({ id: '1', title: 'Post 1' });
+}
+
+export async function generateMetadata() {
+  const { id } = await fetchPost();
+  const product = `Product: ${id}`;
+
+  return {
+    title: product,
+  };
+}
+
+export default function Page() {
+  return (
+    <>
+      <h1>This will be pre-rendered</h1>
+      <DynamicContent />
+    </>
+  );
+}
+
+async function DynamicContent() {
+  const getTodos = async () => {
+    return Sentry.startSpan({ name: 'getTodos', op: 'get.todos' }, async () => {
+      'use cache';
+      await new Promise(resolve => setTimeout(resolve, 100));
+      return [1, 2, 3, 4, 5];
+    });
+  };
+
+  const todos = await getTodos();
+
+  return <div id="todos-fetched">Todos fetched: {todos.length}</div>;
+}

dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/metadata/page.tsx

@@ -0,0 +1,35 @@
+import * as Sentry from '@sentry/nextjs';
+
+/**
+ * Tests generateMetadata function with cache components, this calls the propagation context to be set
+ * Which will generate and set a trace id in the propagation context, which should trigger the random API error if unpatched
+ * See: https://github.com/getsentry/sentry-javascript/issues/18392
+ */
+export function generateMetadata() {
+  return {
+    title: 'Cache Components Metadata Test',
+  };
+}
+
+export default function Page() {
+  return (
+    <>
+      <h1>This will be pre-rendered</h1>
+      <DynamicContent />
+    </>
+  );
+}
+
+async function DynamicContent() {
+  const getTodos = async () => {
+    return Sentry.startSpan({ name: 'getTodos', op: 'get.todos' }, async () => {
+      'use cache';
+      await new Promise(resolve => setTimeout(resolve, 100));
+      return [1, 2, 3, 4, 5];
+    });
+  };
+
+  const todos = await getTodos();
+
+  return <div id="todos-fetched">Todos fetched: {todos.length}</div>;
+}

dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/tests/cacheComponents.spec.ts

@@ -26,3 +26,29 @@ test('Should render suspense component', async ({ page }) => {
   expect(serverTx.spans?.filter(span => span.op === 'get.todos').length).toBeGreaterThan(0);
   await expect(page.locator('#todos-fetched')).toHaveText('Todos fetched: 5');
 });
+
+test('Should generate metadata', async ({ page }) => {
+  const serverTxPromise = waitForTransaction('nextjs-16-cacheComponents', async transactionEvent => {
+    return transactionEvent.contexts?.trace?.op === 'http.server';
+  });
+
+  await page.goto('/metadata');
+  const serverTx = await serverTxPromise;
+
+  expect(serverTx.spans?.filter(span => span.op === 'get.todos')).toHaveLength(0);
+  await expect(page.locator('#todos-fetched')).toHaveText('Todos fetched: 5');
+  await expect(page).toHaveTitle('Cache Components Metadata Test');
+});
+
+test('Should generate metadata async', async ({ page }) => {
+  const serverTxPromise = waitForTransaction('nextjs-16-cacheComponents', async transactionEvent => {
+    return transactionEvent.contexts?.trace?.op === 'http.server';
+  });
+
+  await page.goto('/metadata-async');
+  const serverTx = await serverTxPromise;
+
+  expect(serverTx.spans?.filter(span => span.op === 'get.todos')).toHaveLength(0);
+  await expect(page.locator('#todos-fetched')).toHaveText('Todos fetched: 5');
+  await expect(page).toHaveTitle('Product: 1');
+});

packages/core/.eslintrc.js

@@ -1,4 +1,15 @@
 module.exports = {
   extends: ['../../.eslintrc.js'],
   ignorePatterns: ['rollup.npm.config.mjs'],
+  rules: {
+    '@sentry-internal/sdk/no-unsafe-random-apis': 'error',
+  },
+  overrides: [
+    {
+      files: ['test/**/*.ts', 'test/**/*.tsx'],
+      rules: {
+        '@sentry-internal/sdk/no-unsafe-random-apis': 'off',
+      },
+    },
+  ],
 };

packages/core/src/client.ts

@@ -45,6 +45,7 @@ import { checkOrSetAlreadyCaught, uuid4 } from './utils/misc';
 import { parseSampleRate } from './utils/parseSampleRate';
 import { prepareEvent } from './utils/prepareEvent';
 import { makePromiseBuffer, type PromiseBuffer, SENTRY_BUFFER_FULL_ERROR } from './utils/promisebuffer';
+import { safeMathRandom } from './utils/randomSafeContext';
 import { reparentChildSpans, shouldIgnoreSpan } from './utils/should-ignore-span';
 import { showSpanDropWarning } from './utils/spanUtils';
 import { rejectedSyncPromise } from './utils/syncpromise';
@@ -1288,7 +1289,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
     // 0.0 === 0% events are sent
     // Sampling for transaction happens somewhere else
     const parsedSampleRate = typeof sampleRate === 'undefined' ? undefined : parseSampleRate(sampleRate);
-    if (isError && typeof parsedSampleRate === 'number' && Math.random() > parsedSampleRate) {
+    if (isError && typeof parsedSampleRate === 'number' && safeMathRandom() > parsedSampleRate) {
       this.recordDroppedEvent('sample_rate', 'error');
       return rejectedSyncPromise(
         _makeDoNotSendEventError(

packages/core/src/index.ts

@@ -515,3 +515,9 @@ export type {
   UnstableRollupPluginOptions,
   UnstableWebpackPluginOptions,
 } from './build-time-plugins/buildTimeOptionsBase';
+export {
+  withRandomSafeContext as _INTERNAL_withRandomSafeContext,
+  type RandomSafeContextRunner as _INTERNAL_RandomSafeContextRunner,
+  safeMathRandom as _INTERNAL_safeMathRandom,
+  safeDateNow as _INTERNAL_safeDateNow,
+} from './utils/randomSafeContext';

packages/core/src/integrations/mcp-server/correlation.ts

@@ -46,6 +46,7 @@ export function storeSpanForRequest(transport: MCPTransport, requestId: RequestI
   spanMap.set(requestId, {
     span,
     method,
+    // eslint-disable-next-line @sentry-internal/sdk/no-unsafe-random-apis
     startTime: Date.now(),
   });
 }

packages/core/src/scope.ts

@@ -22,6 +22,7 @@ import { isPlainObject } from './utils/is';
 import { merge } from './utils/merge';
 import { uuid4 } from './utils/misc';
 import { generateTraceId } from './utils/propagationContext';
+import { safeMathRandom } from './utils/randomSafeContext';
 import { _getSpanForScope, _setSpanForScope } from './utils/spanOnScope';
 import { truncate } from './utils/string';
 import { dateTimestampInSeconds } from './utils/time';
@@ -168,7 +169,7 @@ export class Scope {
     this._sdkProcessingMetadata = {};
     this._propagationContext = {
       traceId: generateTraceId(),
-      sampleRand: Math.random(),
+      sampleRand: safeMathRandom(),
     };
   }
 
@@ -550,7 +551,10 @@ export class Scope {
     this._session = undefined;
     _setSpanForScope(this, undefined);
     this._attachments = [];
-    this.setPropagationContext({ traceId: generateTraceId(), sampleRand: Math.random() });
+    this.setPropagationContext({
+      traceId: generateTraceId(),
+      sampleRand: safeMathRandom(),
+    });
 
     this._notifyScopeListeners();
     return this;

packages/core/src/tracing/trace.ts

@@ -17,6 +17,7 @@ import { handleCallbackErrors } from '../utils/handleCallbackErrors';
 import { hasSpansEnabled } from '../utils/hasSpansEnabled';
 import { parseSampleRate } from '../utils/parseSampleRate';
 import { generateTraceId } from '../utils/propagationContext';
+import { safeMathRandom } from '../utils/randomSafeContext';
 import { _getSpanForScope, _setSpanForScope } from '../utils/spanOnScope';
 import { addChildSpanToSpan, getRootSpan, spanIsSampled, spanTimeInputToSeconds, spanToJSON } from '../utils/spanUtils';
 import { propagationContextFromHeaders, shouldContinueTrace } from '../utils/tracing';
@@ -293,7 +294,7 @@ export function startNewTrace<T>(callback: () => T): T {
   return withScope(scope => {
     scope.setPropagationContext({
       traceId: generateTraceId(),
-      sampleRand: Math.random(),
+      sampleRand: safeMathRandom(),
     });
     DEBUG_BUILD && debug.log(`Starting a new trace with id ${scope.getPropagationContext().traceId}`);
     return withActiveSpan(null, callback);