feat(nextjs): Add tunnel route handler that forwards only the envelope

Author: s1gr1d

CHANGELOG.md

@@ -4,6 +4,21 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+### Important Changes
+
+- **feat(nextjs): Add a tunnel route handler that sends only the event payload to Sentry ([#25456](https://github.com/getsentry/sentry-javascript/pull/25456))**
+
+  The `tunnelRoute` option can now send events through a route handler in your app. The handler forwards only the event payload to Sentry, and no request headers. To use it, add this file next to your `tunnelRoute` option:
+
+  ```ts
+  // app/sentry-tunnel/route.ts (or src/app/sentry-tunnel/route.ts)
+  export { POST } from '@sentry/nextjs/tunnel';
+  ```
+
+  The handler accepts events for the DSN of your server SDK. To accept other DSNs, use `createSentryTunnelRoute({ allowedDsns })` from the same import. Without the file, the tunnel route works as before.
+
+  Also, the server no longer sends spans of tunnel requests when span streaming is on, because these spans only show the SDK's own traffic.
+
 ## 11.8.0
 
 ### Important Changes

dev-packages/e2e-tests/test-applications/nextjs-16-tunnel/.gitignore

@@ -12,6 +12,9 @@
 
 event-dumps
 
+# Copied by `test:build-handler*`
+/app/sentry-tunnel/
+
 # testing
 /coverage
 

dev-packages/e2e-tests/test-applications/nextjs-16-tunnel/instrumentation-client.ts

@@ -1,9 +1,9 @@
 import * as Sentry from '@sentry/nextjs';
+import { SENTRY_DSN } from './sentry-dsn';
 
 Sentry.init({
   environment: 'qa', // dynamic sampling bias to keep transactions
-  // Use a fake but properly formatted Sentry SaaS DSN for tunnel route testing
-  dsn: 'https://public@o12345.ingest.us.sentry.io/67890',
+  dsn: SENTRY_DSN,
   // No tunnel option - using tunnelRoute from withSentryConfig
   tracesSampleRate: 1.0,
 });

dev-packages/e2e-tests/test-applications/nextjs-16-tunnel/package.json

@@ -15,6 +15,8 @@
     "test:dev-webpack": "TEST_ENV=development-webpack _SENTRY_TUNNEL_DESTINATION_OVERRIDE=http://localhost:3031/ playwright test",
     "test:build": "pnpm install && pnpm build",
     "test:build-webpack": "pnpm install && pnpm build-webpack",
+    "test:build-handler": "pnpm install && cp -R tunnel-handler/node/sentry-tunnel app/ && pnpm build",
+    "test:build-handler-webpack": "pnpm install && cp -R tunnel-handler/edge/sentry-tunnel app/ && pnpm build-webpack",
     "test:build-canary": "pnpm install && pnpm add next@canary && pnpm build",
     "test:build-latest": "pnpm install && pnpm add next@latest && pnpm build",
     "test:build-latest-webpack": "pnpm install && pnpm add next@latest && pnpm build-webpack",
@@ -61,6 +63,16 @@
         "build-command": "pnpm test:build",
         "label": "nextjs-16-tunnel (turbopack)",
         "assert-command": "pnpm test:assert"
+      },
+      {
+        "build-command": "NEXT_PUBLIC_E2E_TEST_TUNNEL_MODE=handler pnpm test:build-handler",
+        "label": "nextjs-16-tunnel (handler, turbopack)",
+        "assert-command": "NEXT_PUBLIC_E2E_TEST_TUNNEL_MODE=handler pnpm test:assert"
+      },
+      {
+        "build-command": "NEXT_PUBLIC_E2E_TEST_TUNNEL_MODE=handler pnpm test:build-handler-webpack",
+        "label": "nextjs-16-tunnel (handler, webpack, edge)",
+        "assert-command": "NEXT_PUBLIC_E2E_TEST_TUNNEL_MODE=handler pnpm test:assert-webpack"
       }
     ],
     "optionalVariants": [

dev-packages/e2e-tests/test-applications/nextjs-16-tunnel/sentry-dsn.ts

@@ -0,0 +1,6 @@
+// The handler variants send the server events to the event proxy too, so the tests also see server spans.
+export const SENTRY_DSN =
+  process.env.NEXT_PUBLIC_E2E_TEST_TUNNEL_MODE === 'handler'
+    ? 'http://public@localhost:3031/1337'
+    : // A fake but properly formatted Sentry SaaS DSN, because the rewrite mode tunnels only SaaS DSNs
+      'https://public@o12345.ingest.us.sentry.io/67890';

dev-packages/e2e-tests/test-applications/nextjs-16-tunnel/sentry.edge.config.ts

@@ -1,9 +1,9 @@
 import * as Sentry from '@sentry/nextjs';
+import { SENTRY_DSN } from './sentry-dsn';
 
 Sentry.init({
   environment: 'qa', // dynamic sampling bias to keep transactions
-  // Use a fake but properly formatted Sentry SaaS DSN for tunnel route testing
-  dsn: 'https://public@o12345.ingest.us.sentry.io/67890',
+  dsn: SENTRY_DSN,
   // No tunnel option - using tunnelRoute from withSentryConfig
   tracesSampleRate: 1.0,
   // debug: true,

dev-packages/e2e-tests/test-applications/nextjs-16-tunnel/sentry.server.config.ts

@@ -1,9 +1,9 @@
 import * as Sentry from '@sentry/nextjs';
+import { SENTRY_DSN } from './sentry-dsn';
 
 Sentry.init({
   environment: 'qa', // dynamic sampling bias to keep transactions
-  // Use a fake but properly formatted Sentry SaaS DSN for tunnel route testing
-  dsn: 'https://public@o12345.ingest.us.sentry.io/67890',
+  dsn: SENTRY_DSN,
   // No tunnel option - using tunnelRoute from withSentryConfig
   tracesSampleRate: 1.0,
   // debug: true,

dev-packages/e2e-tests/test-applications/nextjs-16-tunnel/tests/tunnel-route.test.ts

@@ -1,6 +1,6 @@
 import { expect, test } from '@playwright/test';
-import { getSpanOp, waitForStreamedSpan, waitForStreamedSpans } from '@sentry-internal/test-utils';
-import type { SerializedStreamedSpan } from '@sentry/core';
+import { getSpanOp, waitForRequest, waitForStreamedSpan, waitForStreamedSpans } from '@sentry-internal/test-utils';
+import type { Event, SerializedStreamedSpan } from '@sentry/core';
 
 function getStringAttribute(span: SerializedStreamedSpan, key: string): string | undefined {
   const attribute = span.attributes[key];
@@ -120,3 +120,68 @@ test('Tunnel requests should not create middleware or fetch spans', async ({ pag
 
   expect(sentryFetchSpans).toHaveLength(0);
 });
+
+test.describe('Tunnel route handler', () => {
+  test.skip(process.env.NEXT_PUBLIC_E2E_TEST_TUNNEL_MODE !== 'handler', 'Only the handler variants use the handler');
+
+  test('forwards events without the cookies of the browser', async ({ page, context, baseURL }) => {
+    await context.addCookies([{ name: 'session', value: '8f2c1d', url: baseURL }]);
+    const proxyRequestPromise = waitForRequest('nextjs-16-tunnel', ({ envelope }) =>
+      envelope[1].some(
+        ([itemHeader, item]) =>
+          itemHeader.type === 'event' &&
+          (item as Event).exception?.values?.[0]?.value === 'Tunnel route handler cookie test',
+      ),
+    );
+
+    await page.goto('/');
+    await page.waitForFunction(() => typeof (window as { __SENTRY__?: unknown }).__SENTRY__ === 'object');
+    const tunnelRequestPromise = page.waitForRequest(
+      request =>
+        request.method() === 'POST' &&
+        new URL(request.url()).origin === baseURL &&
+        (request.postData() ?? '').includes('Tunnel route handler cookie test'),
+    );
+    await page.evaluate(() => {
+      setTimeout(() => {
+        throw new Error('Tunnel route handler cookie test');
+      });
+    });
+
+    const tunnelRequest = await tunnelRequestPromise;
+    const proxyRequest = await proxyRequestPromise;
+
+    expect(new URL(tunnelRequest.url()).search).toBe('');
+    expect((await tunnelRequest.allHeaders()).cookie).toBe('session=8f2c1d');
+    expect(proxyRequest.rawProxyRequestHeaders.cookie).toBeUndefined();
+    expect(proxyRequest.rawProxyRequestHeaders['content-type']).toBe('application/x-sentry-envelope');
+  });
+
+  test('does not create server spans for tunnel requests', async ({ page }) => {
+    // The callback never returns true, so this promise is deliberately left unsettled.
+    const allSpans: SerializedStreamedSpan[] = [];
+    void waitForStreamedSpans('nextjs-16-tunnel', spans => {
+      allSpans.push(...spans);
+      return false;
+    });
+    const pageloadSpanPromise = waitForStreamedSpan('nextjs-16-tunnel', span => {
+      return getSpanOp(span) === 'pageload' && span.is_segment;
+    });
+
+    await page.goto('/');
+    await pageloadSpanPromise;
+    // Wait for the server to send the spans that the tunnel request would wrongly produce
+    await page.waitForTimeout(3000);
+
+    const postSpans = allSpans.filter(
+      span => span.name.startsWith('POST') || getStringAttribute(span, 'http.request.method') === 'POST',
+    );
+    const ingestSpans = allSpans.filter(
+      span =>
+        getSpanOp(span) === 'http.client' &&
+        !!getStringAttribute(span, 'url.full')?.startsWith('http://localhost:3031/'),
+    );
+    expect(postSpans).toEqual([]);
+    expect(ingestSpans).toEqual([]);
+  });
+});

dev-packages/e2e-tests/test-applications/nextjs-16-tunnel/tunnel-handler/edge/sentry-tunnel/route.ts

@@ -0,0 +1,6 @@
+import { createSentryTunnelRoute } from '@sentry/nextjs/tunnel';
+import { SENTRY_DSN } from '@/sentry-dsn';
+
+export const { POST } = createSentryTunnelRoute({ allowedDsns: [SENTRY_DSN] });
+
+export const runtime = 'edge';

dev-packages/e2e-tests/test-applications/nextjs-16-tunnel/tunnel-handler/node/sentry-tunnel/route.ts

@@ -0,0 +1 @@
+export { POST } from '@sentry/nextjs/tunnel';