fix(core): Break TurboModule aggregator self-flush loop

The periodic flush's own `captureEvent` travels through the wrapped
`RNSentry.captureEnvelope`, which records back into the aggregator and,
because the map was just drained, re-armed the flush timer forever in
otherwise-idle sessions. Suppress the empty→non-empty callback around
the flush's `captureEvent`, deferring the release to the next macrotask
so the async record fired from the transport's `.then()` also lands
inside the suppression window.

Author: alwx

packages/core/src/js/integrations/turboModuleContext.ts

@@ -4,7 +4,9 @@ import { debug } from '@sentry/core';
 
 import { createSpanJSON } from '../tracing/utils';
 import {
+  beginSuppressFirstTurboModuleRecordCallback,
   drainTurboModuleAggregate,
+  endSuppressFirstTurboModuleRecordCallback,
   HISTOGRAM_BUCKET_LABELS,
   hasTurboModuleAggregateData,
   setIgnoredTurboModules,
@@ -263,6 +265,14 @@ function attachAggregateToTransactionEvent(event: TransactionEvent): void {
  * Emits the current aggregate as a custom Sentry event so long-running
  * sessions without a transaction still produce a signal. No-op when there's
  * nothing to flush.
+ *
+ * The `captureEvent` call travels through `RNSentry.captureEnvelope`, which
+ * is itself a wrapped TurboModule call. Without the suppression scope below,
+ * the resulting empty→non-empty transition on the aggregator would re-arm
+ * the flush timer indefinitely in an otherwise-idle session. The release is
+ * deferred to the next macrotask so the async record fired from the
+ * transport's `.then()` (after the native side resolves) also lands inside
+ * the suppression window.
  */
 function flushPeriodicAggregate(client: Client): void {
   if (!hasTurboModuleAggregateData()) {
@@ -272,20 +282,25 @@ function flushPeriodicAggregate(client: Client): void {
   const totals = summarise(snapshot);
   const topByTotalMs = [...snapshot].sort((a, b) => b.totalDurationMs - a.totalDurationMs);
 
-  client.captureEvent?.({
-    message: 'TurboModule aggregate (periodic)',
-    level: 'info',
-    tags: {
-      'event.kind': 'turbo_modules.aggregate',
-    },
-    extra: {
-      total_call_count: totals.callCount,
-      total_error_count: totals.errorCount,
-      total_duration_ms: roundMs(totals.totalDurationMs),
-      unique_methods: snapshot.length,
-      modules: topByTotalMs.slice(0, MAX_AGGREGATE_ATTRIBUTE_ROWS).map(serialiseRowAsObject),
-    },
-  });
+  beginSuppressFirstTurboModuleRecordCallback();
+  try {
+    client.captureEvent?.({
+      message: 'TurboModule aggregate (periodic)',
+      level: 'info',
+      tags: {
+        'event.kind': 'turbo_modules.aggregate',
+      },
+      extra: {
+        total_call_count: totals.callCount,
+        total_error_count: totals.errorCount,
+        total_duration_ms: roundMs(totals.totalDurationMs),
+        unique_methods: snapshot.length,
+        modules: topByTotalMs.slice(0, MAX_AGGREGATE_ATTRIBUTE_ROWS).map(serialiseRowAsObject),
+      },
+    });
+  } finally {
+    setTimeout(endSuppressFirstTurboModuleRecordCallback, 0);
+  }
 }
 
 function summarise(snapshot: ReadonlyArray<TurboModuleAggregate>): {

packages/core/src/js/turbomodule/index.ts

@@ -6,7 +6,9 @@ export {
 } from './turboModuleTracker';
 export type { TurboModuleCall, TurboModuleCallKind } from './turboModuleTracker';
 export {
+  beginSuppressFirstTurboModuleRecordCallback,
   drainTurboModuleAggregate,
+  endSuppressFirstTurboModuleRecordCallback,
   HISTOGRAM_BUCKET_LABELS,
   HISTOGRAM_BUCKETS_MS,
   hasTurboModuleAggregateData,

packages/core/src/js/turbomodule/turboModuleAggregator.ts

@@ -57,6 +57,10 @@ interface MutableAggregate extends TurboModuleAggregate {
 const aggregates = new Map<string, MutableAggregate>();
 const ignoredModules = new Set<string>();
 let onFirstRecordAfterEmpty: (() => void) | undefined;
+// Non-zero disables the empty→non-empty callback. The periodic flush uses
+// this to prevent the SDK's own transport call (which records itself into
+// the aggregator) from re-arming the timer in an idle session.
+let suppressFirstRecordCallbackDepth = 0;
 
 function makeKey(name: string, method: string, kind: TurboModuleCallKind): string {
   return `${name}|${method}|${kind}`;
@@ -150,7 +154,7 @@ export function recordTurboModuleCall(args: {
   // exists to satisfy `noUncheckedIndexedAccess`.
   entry.buckets[bucket] = (entry.buckets[bucket] ?? 0) + 1;
 
-  if (wasEmpty && onFirstRecordAfterEmpty) {
+  if (wasEmpty && onFirstRecordAfterEmpty && suppressFirstRecordCallbackDepth === 0) {
     // Don't let a misbehaving observer corrupt the aggregate.
     try {
       onFirstRecordAfterEmpty();
@@ -160,6 +164,30 @@ export function recordTurboModuleCall(args: {
   }
 }
 
+/**
+ * Opens a suppression scope: while at least one is open, the empty→non-empty
+ * callback registered via {@link setOnFirstTurboModuleRecord} is NOT invoked.
+ * Records still land in the aggregate as normal.
+ *
+ * Used by the periodic flush to break a self-recursion loop: the flush's own
+ * `captureEvent` call travels through `RNSentry.captureEnvelope`, which is a
+ * wrapped TurboModule call and would otherwise re-arm the flush timer forever
+ * in an otherwise-idle session.
+ */
+export function beginSuppressFirstTurboModuleRecordCallback(): void {
+  suppressFirstRecordCallbackDepth += 1;
+}
+
+/**
+ * Closes a suppression scope opened by
+ * {@link beginSuppressFirstTurboModuleRecordCallback}. Idempotent at zero.
+ */
+export function endSuppressFirstTurboModuleRecordCallback(): void {
+  if (suppressFirstRecordCallbackDepth > 0) {
+    suppressFirstRecordCallbackDepth -= 1;
+  }
+}
+
 /**
  * Registers a callback fired exactly once when the aggregator transitions
  * from empty to non-empty — i.e. when the first record after a drain (or
@@ -215,4 +243,5 @@ export function _resetTurboModuleAggregator(): void {
   aggregates.clear();
   ignoredModules.clear();
   onFirstRecordAfterEmpty = undefined;
+  suppressFirstRecordCallbackDepth = 0;
 }

packages/core/test/integrations/turboModuleContext.test.ts

@@ -196,5 +196,40 @@ describe('turboModuleContextIntegration', () => {
         tags: { 'event.kind': 'turbo_modules.aggregate' },
       });
     });
+
+    it('does not re-arm the periodic flush when captureEvent triggers its own TurboModule record', () => {
+      // Reproduces the self-recursion: `flushPeriodicAggregate` calls
+      // `client.captureEvent`, whose transport ultimately calls the wrapped
+      // `RNSentry.captureEnvelope`. That call records back into the
+      // aggregator; without suppression the empty→non-empty transition
+      // re-arms the timer, and an idle session loops forever.
+      jest.useFakeTimers();
+      const integration = turboModuleContextIntegration();
+      integration.setupOnce?.();
+      const client = makeMockClient();
+      // Simulate the transport wiring: every captureEvent replays the
+      // TurboModule call the RN transport would have made.
+      client.captureEvent.mockImplementation(() => {
+        recordTurboModuleCall({
+          name: 'RNSentry',
+          method: 'captureEnvelope',
+          kind: 'async',
+          durationMs: 3,
+          errored: false,
+        });
+        return 'event-id';
+      });
+      integration.setup?.(client);
+
+      recordTurboModuleCall({ name: 'User', method: 'work', kind: 'sync', durationMs: 1, errored: false });
+      jest.advanceTimersByTime(DEFAULT_AGGREGATE_FLUSH_INTERVAL_MS);
+      expect(client.captureEvent).toHaveBeenCalledTimes(1);
+
+      // Release the deferred suppression and let any additional timers run.
+      // If the self-noise had re-armed the flush, a second capture would land
+      // after another interval; the loop would then never terminate.
+      jest.advanceTimersByTime(DEFAULT_AGGREGATE_FLUSH_INTERVAL_MS * 10);
+      expect(client.captureEvent).toHaveBeenCalledTimes(1);
+    });
   });
 });

packages/core/test/turbomodule/turboModuleAggregator.test.ts

@@ -1,8 +1,11 @@
 import {
   _resetTurboModuleAggregator,
+  beginSuppressFirstTurboModuleRecordCallback,
   drainTurboModuleAggregate,
+  endSuppressFirstTurboModuleRecordCallback,
   recordTurboModuleCall,
   setIgnoredTurboModules,
+  setOnFirstTurboModuleRecord,
 } from '../../src/js/turbomodule/turboModuleAggregator';
 
 describe('turboModuleAggregator', () => {
@@ -56,4 +59,24 @@ describe('turboModuleAggregator', () => {
     expect(snapshot).toHaveLength(1);
     expect(snapshot[0]?.name).toBe('Other');
   });
+
+  it('does not fire the empty→non-empty callback while suppressed', () => {
+    const cb = jest.fn();
+    setOnFirstTurboModuleRecord(cb);
+
+    beginSuppressFirstTurboModuleRecordCallback();
+    recordTurboModuleCall({
+      name: 'RNSentry',
+      method: 'captureEnvelope',
+      kind: 'async',
+      durationMs: 1,
+      errored: false,
+    });
+    expect(cb).not.toHaveBeenCalled();
+
+    endSuppressFirstTurboModuleRecordCallback();
+    drainTurboModuleAggregate();
+    recordTurboModuleCall({ name: 'User', method: 'work', kind: 'sync', durationMs: 1, errored: false });
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
 });