feat(core): Add shared flushIfServerless function

dev-packages/e2e-tests/test-applications/nuxt-3/server/plugins/customNitroErrorHandler.ts

@@ -1,4 +1,4 @@
-import { Context, GLOBAL_OBJ, flush, debug, vercelWaitUntil } from '@sentry/core';
+import { Context, flushIfServerless } from '@sentry/core';
 import * as SentryNode from '@sentry/node';
 import { H3Error } from 'h3';
 import type { CapturedErrorContext } from 'nitropack';
@@ -53,31 +53,3 @@ function extractErrorContext(errorContext: CapturedErrorContext): Context {
 
   return ctx;
 }
-
-async function flushIfServerless(): Promise<void> {
-  const isServerless =
-    !!process.env.FUNCTIONS_WORKER_RUNTIME || // Azure Functions
-    !!process.env.LAMBDA_TASK_ROOT || // AWS Lambda
-    !!process.env.VERCEL ||
-    !!process.env.NETLIFY;
-
-  // @ts-expect-error This is not typed
-  if (GLOBAL_OBJ[Symbol.for('@vercel/request-context')]) {
-    vercelWaitUntil(flushWithTimeout());
-  } else if (isServerless) {
-    await flushWithTimeout();
-  }
-}
-
-async function flushWithTimeout(): Promise<void> {
-  const sentryClient = SentryNode.getClient();
-  const isDebug = sentryClient ? sentryClient.getOptions().debug : false;
-
-  try {
-    isDebug && debug.log('Flushing events...');
-    await flush(2000);
-    isDebug && debug.log('Done flushing events');
-  } catch (e) {
-    isDebug && debug.log('Error while flushing events:\n', e);
-  }
-}

packages/astro/src/server/middleware.ts

@@ -1,17 +1,15 @@
 import type { RequestEventData, Scope, SpanAttributes } from '@sentry/core';
 import {
   addNonEnumerableProperty,
-  debug,
   extractQueryParamsFromUrl,
+  flushIfServerless,
   objectify,
   stripUrlQueryAndFragment,
-  vercelWaitUntil,
   winterCGRequestToRequestData,
 } from '@sentry/core';
 import {
   captureException,
   continueTrace,
-  flush,
   getActiveSpan,
   getClient,
   getCurrentScope,
@@ -233,16 +231,7 @@ async function instrumentRequest(
         );
         return res;
       } finally {
-        vercelWaitUntil(
-          (async () => {
-            // Flushes pending Sentry events with a 2-second timeout and in a way that cannot create unhandled promise rejections.
-            try {
-              await flush(2000);
-            } catch (e) {
-              debug.log('Error while flushing events:\n', e);
-            }
-          })(),
-        );
+        await flushIfServerless();
       }
       // TODO: flush if serverless (first extract function)
     },

packages/cloudflare/src/handler.ts

@@ -1,6 +1,6 @@
 import {
   captureException,
-  flush,
+  flushIfServerless,
   SEMANTIC_ATTRIBUTE_SENTRY_OP,
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
   SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
@@ -74,7 +74,6 @@ export function withSentry<Env = unknown, QueueHandlerMessage = unknown, CfHostM
           const [event, env, context] = args;
           return withIsolationScope(isolationScope => {
             const options = getFinalOptions(optionsCallback(env), env);
-            const waitUntil = context.waitUntil.bind(context);
 
             const client = init({ ...options, ctx: context });
             isolationScope.setClient(client);
@@ -100,7 +99,7 @@ export function withSentry<Env = unknown, QueueHandlerMessage = unknown, CfHostM
                   captureException(e, { mechanism: { handled: false, type: 'cloudflare' } });
                   throw e;
                 } finally {
-                  waitUntil(flush(2000));
+                  await flushIfServerless({ cloudflareCtx: context });
                 }
               },
             );
@@ -117,7 +116,6 @@ export function withSentry<Env = unknown, QueueHandlerMessage = unknown, CfHostM
           const [emailMessage, env, context] = args;
           return withIsolationScope(isolationScope => {
             const options = getFinalOptions(optionsCallback(env), env);
-            const waitUntil = context.waitUntil.bind(context);
 
             const client = init({ ...options, ctx: context });
             isolationScope.setClient(client);
@@ -141,7 +139,7 @@ export function withSentry<Env = unknown, QueueHandlerMessage = unknown, CfHostM
                   captureException(e, { mechanism: { handled: false, type: 'cloudflare' } });
                   throw e;
                 } finally {
-                  waitUntil(flush(2000));
+                  await flushIfServerless({ cloudflareCtx: context });
                 }
               },
             );
@@ -159,7 +157,6 @@ export function withSentry<Env = unknown, QueueHandlerMessage = unknown, CfHostM
 
           return withIsolationScope(isolationScope => {
             const options = getFinalOptions(optionsCallback(env), env);
-            const waitUntil = context.waitUntil.bind(context);
 
             const client = init({ ...options, ctx: context });
             isolationScope.setClient(client);
@@ -191,7 +188,7 @@ export function withSentry<Env = unknown, QueueHandlerMessage = unknown, CfHostM
                   captureException(e, { mechanism: { handled: false, type: 'cloudflare' } });
                   throw e;
                 } finally {
-                  waitUntil(flush(2000));
+                  await flushIfServerless({ cloudflareCtx: context });
                 }
               },
             );
@@ -210,8 +207,6 @@ export function withSentry<Env = unknown, QueueHandlerMessage = unknown, CfHostM
           return withIsolationScope(async isolationScope => {
             const options = getFinalOptions(optionsCallback(env), env);
 
-            const waitUntil = context.waitUntil.bind(context);
-
             const client = init({ ...options, ctx: context });
             isolationScope.setClient(client);
 
@@ -223,7 +218,7 @@ export function withSentry<Env = unknown, QueueHandlerMessage = unknown, CfHostM
               captureException(e, { mechanism: { handled: false, type: 'cloudflare' } });
               throw e;
             } finally {
-              waitUntil(flush(2000));
+              await flushIfServerless({ cloudflareCtx: context });
             }
           });
         },

packages/core/src/index.ts

@@ -269,6 +269,7 @@ export { callFrameToStackFrame, watchdogTimer } from './utils/anr';
 export { LRUMap } from './utils/lru';
 export { generateTraceId, generateSpanId } from './utils/propagationContext';
 export { vercelWaitUntil } from './utils/vercelWaitUntil';
+export { flushIfServerless } from './utils/flushIfServerless';
 export { SDK_VERSION } from './utils/version';
 export { getDebugImagesForResources, getFilenameToDebugIdMap } from './utils/debug-ids';
 export { escapeStringForRegex } from './vendor/escapeStringForRegex';

packages/core/src/utils/flushIfServerless.ts

@@ -0,0 +1,72 @@
+import { flush } from '../exports';
+import { debug } from './debug-logger';
+import { vercelWaitUntil } from './vercelWaitUntil';
+import { GLOBAL_OBJ } from './worldwide';
+
+type MinimalCloudflareContext = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  waitUntil(promise: Promise<any>): void;
+};
+
+async function flushWithTimeout(timeout: number): Promise<void> {
+  try {
+    debug.log('Flushing events...');
+    await flush(timeout);
+    debug.log('Done flushing events');
+  } catch (e) {
+    debug.log('Error while flushing events:\n', e);
+  }
+}
+
+/**
+ *  Flushes the event queue with a timeout in serverless environments to ensure that events are sent to Sentry before the
+ *  serverless function execution ends.
+ *
+ * The function is async, but in environments that support a `waitUntil` mechanism, it will run synchronously.
+ *
+ * This function is aware of the following serverless platforms:
+ * - Cloudflare: If a Cloudflare context is provided, it will use `ctx.waitUntil()` to flush events.
+ * - Vercel: It detects the Vercel environment and uses Vercel's `waitUntil` function.
+ * - Other Serverless (AWS Lambda, Google Cloud, etc.): It detects the environment via environment variables
+ *   and uses a regular `await flush()`.
+ *
+ *  @internal This function is supposed for internal Sentry SDK usage only.
+ *  @hidden
+ */
+export async function flushIfServerless(
+  params: {
+    timeout?: number;
+    cloudflareCtx?: MinimalCloudflareContext;
+  } = {},
+): Promise<void> {
+  const { timeout = 2000, cloudflareCtx } = params;
+
+  if (cloudflareCtx && typeof cloudflareCtx.waitUntil === 'function') {
+    cloudflareCtx.waitUntil(flushWithTimeout(timeout));
+    return;
+  }
+
+  // @ts-expect-error This is not typed
+  if (GLOBAL_OBJ[Symbol.for('@vercel/request-context')]) {
+    // Vercel has a waitUntil equivalent that works without execution context
+    vercelWaitUntil(flushWithTimeout(timeout));
+    return;
+  }
+
+  if (typeof process === 'undefined') {
+    return;
+  }
+
+  const isServerless =
+    !!process.env.FUNCTIONS_WORKER_RUNTIME || // Azure Functions
+    !!process.env.LAMBDA_TASK_ROOT || // AWS Lambda
+    !!process.env.K_SERVICE || // Google Cloud Run
+    !!process.env.CF_PAGES || // Cloudflare Pages
+    !!process.env.VERCEL ||
+    !!process.env.NETLIFY;
+
+  if (isServerless) {
+    // Use regular flush for environments without a generic waitUntil mechanism
+    await flushWithTimeout(timeout);
+  }
+}

packages/core/test/lib/utils/flushIfServerless.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import * as flushModule from '../../../src/exports';
+import { flushIfServerless } from '../../../src/utils/flushIfServerless';
+import * as vercelWaitUntilModule from '../../../src/utils/vercelWaitUntil';
+import { GLOBAL_OBJ } from '../../../src/utils/worldwide';
+
+describe('flushIfServerless', () => {
+  let originalProcess: typeof process;
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+    originalProcess = global.process;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test('should bind context (preserve `this`) when calling waitUntil', async () => {
+    const flushMock = vi.spyOn(flushModule, 'flush').mockResolvedValue(true);
+
+    // Mock Cloudflare context with `waitUntil` (which should be called if `this` is bound correctly)
+    const mockCloudflareCtx = {
+      contextData: 'test-data',
+      waitUntil: function (promise: Promise<unknown>) {
+        // This will fail if 'this' is not bound correctly
+        expect(this.contextData).toBe('test-data');
+        return promise;
+      },
+    };
+
+    const waitUntilSpy = vi.spyOn(mockCloudflareCtx, 'waitUntil');
+
+    await flushIfServerless({ cloudflareCtx: mockCloudflareCtx });
+
+    expect(waitUntilSpy).toHaveBeenCalledTimes(1);
+    expect(flushMock).toHaveBeenCalledWith(2000);
+  });
+
+  test('should use cloudflare waitUntil when valid cloudflare context is provided', async () => {
+    const flushMock = vi.spyOn(flushModule, 'flush').mockResolvedValue(true);
+    const mockCloudflareCtx = {
+      waitUntil: vi.fn(),
+    };
+
+    await flushIfServerless({ cloudflareCtx: mockCloudflareCtx, timeout: 5000 });
+
+    expect(mockCloudflareCtx.waitUntil).toHaveBeenCalledTimes(1);
+    expect(flushMock).toHaveBeenCalledWith(5000);
+  });
+
+  test('should ignore cloudflare context when waitUntil is not a function (and use Vercel waitUntil instead)', async () => {
+    const flushMock = vi.spyOn(flushModule, 'flush').mockResolvedValue(true);
+    const vercelWaitUntilSpy = vi.spyOn(vercelWaitUntilModule, 'vercelWaitUntil').mockImplementation(() => {});
+
+    // Mock Vercel environment
+    // @ts-expect-error This is not typed
+    GLOBAL_OBJ[Symbol.for('@vercel/request-context')] = { get: () => ({ waitUntil: vi.fn() }) };
+
+    const mockCloudflareCtx = {
+      waitUntil: 'not-a-function', // Invalid waitUntil
+    };
+
+    // @ts-expect-error Using the wrong type here on purpose
+    await flushIfServerless({ cloudflareCtx: mockCloudflareCtx });
+
+    expect(vercelWaitUntilSpy).toHaveBeenCalledTimes(1);
+    expect(flushMock).toHaveBeenCalledWith(2000);
+  });
+
+  test('should handle multiple serverless environment variables simultaneously', async () => {
+    const flushMock = vi.spyOn(flushModule, 'flush').mockResolvedValue(true);
+
+    global.process = {
+      ...originalProcess,
+      env: {
+        ...originalProcess.env,
+        LAMBDA_TASK_ROOT: '/var/task',
+        VERCEL: '1',
+        NETLIFY: 'true',
+        CF_PAGES: '1',
+      },
+    };
+
+    await flushIfServerless({ timeout: 4000 });
+
+    expect(flushMock).toHaveBeenCalledWith(4000);
+  });
+
+  test('should use default timeout when not specified', async () => {
+    const flushMock = vi.spyOn(flushModule, 'flush').mockResolvedValue(true);
+    const mockCloudflareCtx = {
+      waitUntil: vi.fn(),
+    };
+
+    await flushIfServerless({ cloudflareCtx: mockCloudflareCtx });
+
+    expect(flushMock).toHaveBeenCalledWith(2000);
+  });
+
+  test('should handle zero timeout value', async () => {
+    const flushMock = vi.spyOn(flushModule, 'flush').mockResolvedValue(true);
+
+    global.process = {
+      ...originalProcess,
+      env: {
+        ...originalProcess.env,
+        LAMBDA_TASK_ROOT: '/var/task',
+      },
+    };
+
+    await flushIfServerless({ timeout: 0 });
+
+    expect(flushMock).toHaveBeenCalledWith(0);
+  });
+});

packages/nextjs/src/common/captureRequestError.ts

@@ -1,6 +1,5 @@
 import type { RequestEventData } from '@sentry/core';
-import { captureException, headersToDict, vercelWaitUntil, withScope } from '@sentry/core';
-import { flushSafelyWithTimeout } from './utils/responseEnd';
+import { captureException, flushIfServerless, headersToDict, withScope } from '@sentry/core';
 
 type RequestInfo = {
   path: string;
@@ -41,6 +40,6 @@ export function captureRequestError(error: unknown, request: RequestInfo, errorC
       },
     });
 
-    vercelWaitUntil(flushSafelyWithTimeout());
+    flushIfServerless().catch(() => /* no-op */ {});
   });
 }

packages/nextjs/src/common/pages-router-instrumentation/_error.ts

@@ -1,6 +1,5 @@
-import { captureException, httpRequestToRequestData, vercelWaitUntil, withScope } from '@sentry/core';
+import { captureException, flushIfServerless, httpRequestToRequestData, withScope } from '@sentry/core';
 import type { NextPageContext } from 'next';
-import { flushSafelyWithTimeout } from '../utils/responseEnd';
 
 type ContextOrProps = {
   req?: NextPageContext['req'];
@@ -54,5 +53,5 @@ export async function captureUnderscoreErrorException(contextOrProps: ContextOrP
     });
   });
 
-  vercelWaitUntil(flushSafelyWithTimeout());
+  flushIfServerless().catch(() => /* no-op */ {});
 }