feat(react-router): Serve the managed tunnel from a route in the server build

React Router has no request hook to answer from, so `sentryReactRouter()` adds a
resource route whose path is read from the DSN at runtime. React Router reads it
on its first request, so a request before `Sentry.init` keeps the tunnel off
until restart.

Author: logaretm

dev-packages/e2e-tests/test-applications/react-router-8-framework/app/entry.client.tsx

@@ -6,8 +6,8 @@ import { HydratedRouter } from 'react-router/dom';
 Sentry.init({
   environment: 'qa', // dynamic sampling bias to keep transactions
   // todo: get this from env
-  dsn: 'https://username@domain/123',
-  tunnel: `http://localhost:3031/`, // proxy server
+  dsn: __E2E_TEST_TUNNEL__ ? 'http://public@localhost:3031/1337' : 'https://username@domain/123',
+  tunnel: __E2E_TEST_TUNNEL__ ? true : `http://localhost:3031/`, // proxy server
   integrations: [Sentry.reactRouterTracingIntegration()],
   tracesSampleRate: 1.0,
   tracePropagationTargets: [/^\//],

dev-packages/e2e-tests/test-applications/react-router-8-framework/app/globals.d.ts

@@ -0,0 +1 @@
+declare const __E2E_TEST_TUNNEL__: boolean;

dev-packages/e2e-tests/test-applications/react-router-8-framework/app/root.tsx

@@ -2,6 +2,20 @@ import { Links, Meta, Outlet, Scripts, ScrollRestoration, isRouteErrorResponse }
 import type { Route } from './+types/root';
 import stylesheet from './app.css?url';
 
+// The tunnel variant checks that the managed tunnel answers before an auth middleware like this one. Other variants
+// get none, so their span assertions stay as they are.
+export const middleware: Route.MiddlewareFunction[] = __E2E_TEST_TUNNEL__
+  ? [
+      ({ request }, next) => {
+        if (request.method === 'POST' && request.headers.get('x-auth') !== 'ok') {
+          return new Response('blocked by user auth', { status: 401 });
+        }
+
+        return next();
+      },
+    ]
+  : [];
+
 export const links: Route.LinksFunction = () => [
   { rel: 'preconnect', href: 'https://fonts.googleapis.com' },
   {

dev-packages/e2e-tests/test-applications/react-router-8-framework/instrument.mjs

@@ -1,8 +1,8 @@
 import * as Sentry from '@sentry/react-router';
 
 Sentry.init({
-  dsn: 'https://username@domain/123',
+  dsn: process.env.E2E_TEST_TUNNEL ? 'http://public@localhost:3031/1337' : 'https://username@domain/123',
   environment: 'qa', // dynamic sampling bias to keep transactions
   tracesSampleRate: 1.0,
-  tunnel: `http://localhost:3031/`, // proxy server
+  tunnel: process.env.E2E_TEST_TUNNEL ? true : `http://localhost:3031/`, // proxy server
 });

dev-packages/e2e-tests/test-applications/react-router-8-framework/package.json

@@ -44,7 +44,9 @@
     "test:build": "pnpm install && pnpm build",
     "test:assert": "pnpm test:ts && pnpm test:playwright",
     "test:ts": "pnpm typecheck",
-    "test:playwright": "playwright test"
+    "test:playwright": "playwright test",
+    "test:build:tunnel": "pnpm install && E2E_TEST_TUNNEL=1 pnpm build",
+    "test:assert:tunnel": "E2E_TEST_TUNNEL=1 pnpm test:playwright tunnel"
   },
   "eslintConfig": {
     "extends": [
@@ -85,6 +87,11 @@
       {
         "runtime": "cloudflare",
         "label": "react-router-8-framework (cloudflare)"
+      },
+      {
+        "build-command": "pnpm test:build:tunnel",
+        "assert-command": "pnpm test:assert:tunnel",
+        "label": "react-router-8-framework (tunnel)"
       }
     ]
   }

dev-packages/e2e-tests/test-applications/react-router-8-framework/tests/tunnel.test.ts

@@ -0,0 +1,40 @@
+import { expect, test } from '@playwright/test';
+import { getSpanOp, waitForStreamedSpan } from '@sentry-internal/test-utils';
+
+test.skip(!process.env.E2E_TEST_TUNNEL, 'Only runs in the tunnel variant');
+
+const APP_NAME = 'react-router-8-framework';
+const TUNNEL_PATH = /^\/[a-z0-9]{1,7}$/;
+
+test('answers the managed tunnel before the root middleware', async ({ page }) => {
+  // The variant's root middleware rejects every other POST.
+  expect((await page.request.post('/', { data: 'x' })).status()).toBe(401);
+
+  const tunnelServerSpanPromise = waitForStreamedSpan(
+    APP_NAME,
+    span => getSpanOp(span) === 'http.server' && TUNNEL_PATH.test(String(span.attributes['url.path']?.value ?? '')),
+  );
+  const tunnelResponsePromise = page.waitForResponse(
+    response => response.request().method() === 'POST' && TUNNEL_PATH.test(new URL(response.url()).pathname),
+  );
+
+  await page.goto('/');
+  const tunnelResponse = await tunnelResponsePromise;
+
+  expect(tunnelResponse.status()).toBe(200);
+  expect(new URL(tunnelResponse.url()).origin).toBe(new URL(page.url()).origin);
+
+  // Anchor on a regular server span requested after the tunnel traffic: spans flush in order, so a tunnel span
+  // would arrive first.
+  const anchorSpanPromise = waitForStreamedSpan(
+    APP_NAME,
+    span => getSpanOp(span) === 'http.server' && String(span.attributes['url.path']?.value ?? '') === '/performance',
+  );
+  await page.request.get('/performance');
+
+  const winner = await Promise.race([
+    tunnelServerSpanPromise.then(() => 'tunnel' as const),
+    anchorSpanPromise.then(() => 'anchor' as const),
+  ]);
+  expect(winner).toBe('anchor');
+});

dev-packages/e2e-tests/test-applications/react-router-8-framework/vite.config.ts

@@ -4,6 +4,9 @@ import { defineConfig } from 'vite';
 
 export default defineConfig(config => {
   return {
+    define: {
+      __E2E_TEST_TUNNEL__: JSON.stringify(!!process.env.E2E_TEST_TUNNEL),
+    },
     plugins: [reactRouter(), sentryReactRouter({ sourcemaps: { disable: true } }, config)],
   };
 });

packages/react-router/src/cloudflare/index.ts

@@ -4,6 +4,7 @@ import { isPrerenderRequest } from '../server/serverBuild';
 export * from '../client';
 
 export { wrapSentryHandleRequest } from '../server/wrapSentryHandleRequest';
+export { createSentryTunnelRoute } from '../server/tunnelRoute';
 export {
   createSentryServerInstrumentation,
   type CreateSentryServerInstrumentationOptions,

packages/react-router/src/server/index.ts

@@ -8,6 +8,7 @@ export { wrapSentryHandleRequest } from './wrapSentryHandleRequest';
 export { createSentryHandleRequest, type SentryHandleRequestOptions } from './createSentryHandleRequest';
 export { createSentryHandleError, type SentryHandleErrorOptions } from './createSentryHandleError';
 export { getMetaTagTransformer } from './getMetaTagTransformer';
+export { createSentryTunnelRoute } from './tunnelRoute';
 
 // React Router instrumentation API support
 export {

packages/react-router/src/server/tunnelRoute.ts

@@ -0,0 +1,38 @@
+import { debug, getClient, getTunnelPaths, handleTunnelRequestIfMatched } from '@sentry/core';
+import { DEBUG_BUILD } from '../common/debug-build';
+
+// Never matches a request, for when the managed tunnel is off.
+const DISABLED_TUNNEL_PATH = '/__sentry-tunnel-disabled__';
+
+/**
+ * A resource route that serves the managed tunnel. `sentryReactRouter()` adds it to the server build, since React
+ * Router has no request hook to answer from. Not meant to be used directly.
+ */
+export function createSentryTunnelRoute(): Record<string, unknown> {
+  return {
+    id: 'sentry-tunnel',
+    parentId: undefined,
+    index: undefined,
+    caseSensitive: undefined,
+    // React Router reads the path once, on its first request, and keeps it until the server restarts.
+    get path(): string {
+      if (!getClient()) {
+        DEBUG_BUILD &&
+          debug.warn('The managed tunnel stays off until restart: a request came in before `Sentry.init`.');
+        return DISABLED_TUNNEL_PATH;
+      }
+
+      const [path, ...otherPaths] = getTunnelPaths();
+      if (otherPaths.length) {
+        DEBUG_BUILD && debug.warn(`React Router can only serve one managed tunnel path, so only ${path} is served.`);
+      }
+
+      return path ?? DISABLED_TUNNEL_PATH;
+    },
+    module: {
+      action: ({ request }: { request: Request }) =>
+        handleTunnelRequestIfMatched(request) ?? new Response(null, { status: 404 }),
+      loader: () => new Response(null, { status: 405, headers: { Allow: 'POST' } }),
+    },
+  };
+}