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

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,12 @@
 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
+  // The tunnel variants also accept another app's DSN, so the server serves more than one tunnel path.
+  integrations: process.env.E2E_TEST_TUNNEL
+    ? [Sentry.serveTunnelIntegration({ allowedDsns: ['http://other@localhost:3031/1338'] })]
+    : [],
 });

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

@@ -45,7 +45,10 @@
     "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-basepath": "pnpm install && E2E_TEST_TUNNEL=1 E2E_TEST_BASE_PATH=/app pnpm build",
+    "test:assert:tunnel-basepath": "E2E_TEST_TUNNEL=1 E2E_TEST_BASE_PATH=/app pnpm test:playwright tunnel",
+    "test:assert:tunnel-basepath-dev": "TEST_ENV=development E2E_TEST_TUNNEL=1 E2E_TEST_BASE_PATH=/app pnpm test:playwright tunnel"
   },
   "eslintConfig": {
     "extends": [
@@ -87,6 +90,22 @@
       {
         "runtime": "cloudflare",
         "label": "react-router-8-framework (cloudflare)"
+      },
+      {
+        "build-command": "pnpm test:build:tunnel-basepath",
+        "assert-command": "pnpm test:assert:tunnel-basepath",
+        "label": "react-router-8-framework (tunnel-basepath)"
+      },
+      {
+        "runtime": "cloudflare",
+        "build-command": "pnpm test:build:tunnel-basepath",
+        "assert-command": "pnpm test:assert:tunnel-basepath",
+        "label": "react-router-8-framework (tunnel-basepath-cloudflare)"
+      },
+      {
+        "label": "react-router-8-framework (tunnel-basepath-dev)",
+        "build-command": "pnpm install",
+        "assert-command": "pnpm test:assert:tunnel-basepath-dev"
       }
     ]
   }

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

@@ -10,7 +10,7 @@ const startCommands = {
 
 const config = getPlaywrightConfig(
   {
-    startCommand: startCommands[getRuntime()],
+    startCommand: process.env.TEST_ENV === 'development' ? 'pnpm dev --port 3030' : startCommands[getRuntime()],
     port: 3030,
   },
   // Boot Redis before the tests run, outside the webServer startup-timeout window.

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

@@ -2,5 +2,7 @@ import type { Config } from '@react-router/dev/config';
 
 export default {
   ssr: true,
+  // The base-path variant serves the app, and so the tunnel, under `/app`.
+  ...(process.env.E2E_TEST_BASE_PATH && { basename: `${process.env.E2E_TEST_BASE_PATH}/` }),
   prerender: ['/performance/static'],
 } satisfies Config;

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

@@ -0,0 +1,27 @@
+import { expect, test } from '@playwright/test';
+import { isServerSpanAt, watchForTunnelSpan } 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 BASE_PATH = process.env.E2E_TEST_BASE_PATH ?? '';
+const TUNNEL_PATH = new RegExp(`^${BASE_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(`${BASE_PATH}/`, { data: 'x' })).status()).toBe(401);
+
+  const raceTunnelSpan = watchForTunnelSpan(APP_NAME, isServerSpanAt(TUNNEL_PATH));
+  const tunnelResponsePromise = page.waitForResponse(
+    response => response.request().method() === 'POST' && TUNNEL_PATH.test(new URL(response.url()).pathname),
+  );
+
+  await page.goto(`${BASE_PATH}/`);
+
+  expect((await tunnelResponsePromise).status()).toBe(200);
+  expect(
+    await raceTunnelSpan(isServerSpanAt(`${BASE_PATH}/performance`), () =>
+      page.request.get(`${BASE_PATH}/performance`),
+    ),
+  ).toBe('anchor');
+});

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

@@ -5,6 +5,9 @@ import { sentryReactRouter } from '@sentry/react-router/vite';
 import { defineConfig } from 'vite';
 
 export default defineConfig(async config => ({
+  define: {
+    __E2E_TEST_TUNNEL__: JSON.stringify(!!process.env.E2E_TEST_TUNNEL),
+  },
   plugins: [
     cloudflare({ viteEnvironment: { name: 'ssr' } }),
     reactRouter(),

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)],
   };
 });

dev-packages/e2e-tests/test-applications/react-router-8-framework/workers/instrument.server.ts

@@ -1,8 +1,11 @@
-import { defineCloudflareOptions } from '@sentry/cloudflare';
+import { defineCloudflareOptions, serveTunnelIntegration } from '@sentry/cloudflare';
+
+declare const __E2E_TEST_TUNNEL__: boolean;
 
 export default defineCloudflareOptions({
-  dsn: 'https://username@domain/123',
+  dsn: __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
+  integrations: __E2E_TEST_TUNNEL__ ? [serveTunnelIntegration()] : [],
 });

packages/react-router/src/client/sdk.ts

@@ -1,10 +1,21 @@
 import type { BrowserOptions } from '@sentry/browser';
 import { init as browserInit } from '@sentry/browser';
 import type { Client } from '@sentry/core';
-import { applySdkMetadata, consoleSandbox, setTag } from '@sentry/core';
+import {
+  applySdkMetadata,
+  _INTERNAL_applyTunnelDefaults as applyTunnelDefaults,
+  consoleSandbox,
+  GLOBAL_OBJ,
+  setTag,
+} from '@sentry/core';
 
 const BROWSER_TRACING_INTEGRATION_ID = 'BrowserTracing';
 
+// React Router inlines this context before the client entry runs, so it's there before `init`.
+const GLOBAL_OBJ_WITH_ROUTER_CONTEXT = GLOBAL_OBJ as typeof GLOBAL_OBJ & {
+  __reactRouterContext?: { basename?: string };
+};
+
 /**
  * Initializes the client side of the React Router SDK.
  */
@@ -25,6 +36,11 @@ export function init(options: BrowserOptions): Client | undefined {
     }
   }
 
+  // The managed tunnel is served under the app's `basename`, like every other route. A `basePath` the user set wins.
+  options.tunnel = applyTunnelDefaults(options.tunnel, {
+    basePath: GLOBAL_OBJ_WITH_ROUTER_CONTEXT.__reactRouterContext?.basename,
+  });
+
   applySdkMetadata(options, 'react-router', ['react-router', 'browser']);
 
   const client = browserInit(options);

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 { createSentryTunnelRoutes } 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 { createSentryTunnelRoutes } from './tunnelRoute';
 
 // React Router instrumentation API support
 export {

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

@@ -0,0 +1,70 @@
+import { debug, getClient } from '@sentry/core';
+import {
+  _INTERNAL_getTunnelPaths as getTunnelPaths,
+  handleTunnelRequestIfMatched,
+  _INTERNAL_setManagedTunnelDefaults as setManagedTunnelDefaults,
+} from '@sentry/core/server';
+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__';
+
+/**
+ * The resource routes that serve the managed tunnel, one per tunnel path. `sentryReactRouter()` adds them to the
+ * server build, since React Router has no request hook to answer from and a route matches only one path. Not meant
+ * to be used directly.
+ *
+ * @param basename The app's `basename`, which React Router matches the routes under but leaves in the request URL.
+ */
+export function createSentryTunnelRoutes(basename?: string): Record<string, Record<string, unknown>> {
+  // Runs when the server build loads. Clients created later, e.g. per request on Cloudflare, start with the basename.
+  setManagedTunnelDefaults({ basePath: basename });
+
+  // `init` runs from `--import` before the server build loads, so the client and its tunnel paths are usually known.
+  if (!getClient()) {
+    return { 'sentry-tunnel': makeTunnelRoute('sentry-tunnel', getLazyTunnelPath) };
+  }
+
+  return Object.fromEntries(
+    getTunnelPaths().map((path, index) => {
+      const id = `sentry-tunnel-${index}`;
+
+      return [id, makeTunnelRoute(id, () => path)];
+    }),
+  );
+}
+
+/**
+ * The path of the single route added when `init` runs after the server build loads, e.g. per request on Cloudflare.
+ * React Router reads it on its first request and keeps it until the server restarts.
+ */
+function getLazyTunnelPath(): 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(`Sentry.init ran after the server build loaded, so only ${path} is served.`);
+  }
+
+  return path ?? DISABLED_TUNNEL_PATH;
+}
+
+function makeTunnelRoute(id: string, getPath: () => string): Record<string, unknown> {
+  return {
+    id,
+    parentId: undefined,
+    index: undefined,
+    caseSensitive: undefined,
+    get path(): string {
+      return getPath();
+    },
+    module: {
+      action: ({ request }: { request: Request }) =>
+        handleTunnelRequestIfMatched(request) ?? new Response(null, { status: 404 }),
+      loader: () => new Response(null, { status: 405, headers: { Allow: 'POST' } }),
+    },
+  };
+}

packages/react-router/src/vite/makeTunnelRoutePlugin.ts

@@ -0,0 +1,30 @@
+import type { Plugin } from 'vite';
+
+const SERVER_BUILD_MODULE_ID = 'virtual:react-router/server-build';
+
+/**
+ * Adds the managed tunnel routes to the server build. They only serve requests when `serveTunnelIntegration` is set
+ * up. The server build exports the app's `basename`, which the route needs to match the request URL.
+ */
+export function makeTunnelRoutePlugin(): Plugin {
+  return {
+    name: 'sentry-react-router-tunnel-route',
+    enforce: 'post',
+
+    transform(code, id, options) {
+      if (!options?.ssr || !id.includes(SERVER_BUILD_MODULE_ID)) {
+        return null;
+      }
+
+      return {
+        code: `${code}
+import { createSentryTunnelRoutes as __sentryCreateTunnelRoutes } from '@sentry/react-router';
+if (typeof routes === 'object' && routes) {
+  Object.assign(routes, __sentryCreateTunnelRoutes(typeof basename === 'string' ? basename : undefined));
+}
+`,
+        map: null,
+      };
+    },
+  };
+}

packages/react-router/src/vite/plugin.ts

@@ -4,6 +4,7 @@ import { makeConfigInjectorPlugin } from './makeConfigInjectorPlugin';
 import { makeCustomSentryVitePlugins } from './makeCustomSentryVitePlugins';
 import { makeEnableSourceMapsPlugin } from './makeEnableSourceMapsPlugin';
 import { makeServerBuildCapturePlugin } from './makeServerBuildCapturePlugin';
+import { makeTunnelRoutePlugin } from './makeTunnelRoutePlugin';
 import type { SentryReactRouterBuildOptions } from './types';
 
 /**
@@ -21,6 +22,7 @@ export async function sentryReactRouter(
 
   plugins.push(makeConfigInjectorPlugin(options));
   plugins.push(makeServerBuildCapturePlugin());
+  plugins.push(makeTunnelRoutePlugin());
 
   if (process.env.NODE_ENV !== 'development' && viteConfig.command === 'build' && viteConfig.mode !== 'development') {
     plugins.push(sentryOrchestrionPlugin({ buildTimeInstrumentation: options.buildTimeInstrumentation }));

packages/react-router/test/client/sdk.test.ts

@@ -41,6 +41,18 @@ describe('React Router client SDK', () => {
       expect(browserInit).toHaveBeenCalledWith(expect.objectContaining(expectedMetadata));
     });
 
+    it("serves the managed tunnel under the app's `basename`, unless the user set a base path", () => {
+      vi.stubGlobal('__reactRouterContext', { basename: '/app/' });
+
+      reactRouterInit({ tunnel: true });
+      expect(browserInit).toHaveBeenLastCalledWith(expect.objectContaining({ tunnel: { basePath: '/app' } }));
+
+      reactRouterInit({ tunnel: { basePath: '/custom' } });
+      expect(browserInit).toHaveBeenLastCalledWith(expect.objectContaining({ tunnel: { basePath: '/custom' } }));
+
+      vi.unstubAllGlobals();
+    });
+
     it('returns client from init', () => {
       expect(reactRouterInit({})).not.toBeUndefined();
     });