feat(sveltekit): Serve the managed tunnel from sentryHandle under the app's base path

dev-packages/e2e-tests/test-applications/sveltekit-3-cloudflare-workers/package.json

@@ -11,7 +11,9 @@
     "clean": "npx rimraf node_modules pnpm-lock.yaml",
     "test:e2e": "playwright test",
     "test:build": "pnpm install && pnpm build",
-    "test:assert": "pnpm test:e2e"
+    "test:assert": "pnpm test:e2e",
+    "test:build:tunnel": "pnpm install && E2E_TEST_TUNNEL=1 E2E_TEST_DSN=http://public@localhost:3031/1337 PUBLIC_E2E_TEST_DSN=http://public@localhost:3031/1337 pnpm build",
+    "test:assert:tunnel": "E2E_TEST_TUNNEL=1 E2E_TEST_DSN=http://public@localhost:3031/1337 PUBLIC_E2E_TEST_DSN=http://public@localhost:3031/1337 playwright test tunnel"
   },
   "dependencies": {
     "@sentry/sveltekit": "file:../../packed/sentry-sveltekit-packed.tgz"
@@ -30,5 +32,14 @@
   },
   "volta": {
     "extends": "../../package.json"
+  },
+  "sentryTest": {
+    "variants": [
+      {
+        "label": "sveltekit-3-cloudflare-workers (tunnel)",
+        "build-command": "pnpm test:build:tunnel",
+        "assert-command": "pnpm test:assert:tunnel"
+      }
+    ]
   }
 }

dev-packages/e2e-tests/test-applications/sveltekit-3-cloudflare-workers/src/app.d.ts

@@ -1,6 +1,8 @@
 // See https://svelte.dev/docs/kit/types#app.d.ts
 // `App.Platform` (including `platform.ctx`) is declared by `@sveltejs/adapter-cloudflare`.
 declare global {
+  const __E2E_TEST_TUNNEL__: boolean;
+
   namespace App {
     // interface Error {}
     // interface Locals {}

dev-packages/e2e-tests/test-applications/sveltekit-3-cloudflare-workers/src/hooks.client.ts

@@ -4,7 +4,7 @@ import * as Sentry from '@sentry/sveltekit';
 Sentry.init({
   environment: 'qa',
   dsn: PUBLIC_E2E_TEST_DSN,
-  tunnel: 'http://localhost:3031/', // proxy server
+  tunnel: __E2E_TEST_TUNNEL__ ? true : 'http://localhost:3031/', // proxy server
   tracesSampleRate: 1.0,
 });
 

dev-packages/e2e-tests/test-applications/sveltekit-3-cloudflare-workers/src/hooks.server.ts

@@ -10,7 +10,7 @@ export const handle = sequence(
     environment: 'qa', // dynamic sampling bias to keep spans
     dsn: E2E_TEST_DSN,
     debug: !!process.env.DEBUG,
-    tunnel: 'http://localhost:3031/', // proxy server
+    tunnel: __E2E_TEST_TUNNEL__ ? true : 'http://localhost:3031/', // proxy server
     tracesSampleRate: 1.0,
   }),
   sentryHandle(),

dev-packages/e2e-tests/test-applications/sveltekit-3-cloudflare-workers/tests/tunnel.test.ts

@@ -0,0 +1,23 @@
+import { expect, test } from '@playwright/test';
+import { getSpanOp, isServerSpanAt, waitForStreamedSpan, watchForTunnelSpan } from '@sentry-internal/test-utils';
+
+test.skip(!process.env.E2E_TEST_TUNNEL, 'Only runs in the tunnel variant');
+
+const APP_NAME = 'sveltekit-3-cloudflare-workers';
+const TUNNEL_PATH = /^\/app\/[a-z0-9]{1,7}$/;
+
+test('serves the managed tunnel from the Worker under the base path', async ({ page }) => {
+  const pageloadSpanPromise = waitForStreamedSpan(APP_NAME, span => getSpanOp(span) === 'pageload' && span.is_segment);
+  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('/app/');
+
+  expect((await tunnelResponsePromise).status()).toBe(200);
+  await expect(pageloadSpanPromise).resolves.toBeDefined();
+  expect(
+    await raceTunnelSpan(isServerSpanAt('/app/server-load-error'), () => page.request.get('/app/server-load-error')),
+  ).toBe('anchor');
+});

dev-packages/e2e-tests/test-applications/sveltekit-3-cloudflare-workers/vite.config.js

@@ -4,7 +4,13 @@ import { sveltekit } from '@sveltejs/kit/vite';
 import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
 import { defineConfig } from 'vite';
 
+// The tunnel variant serves the app under a base path to cover that the managed tunnel follows it.
+const tunnelVariant = !!process.env.E2E_TEST_TUNNEL;
+
 export default defineConfig({
+  define: {
+    __E2E_TEST_TUNNEL__: JSON.stringify(tunnelVariant),
+  },
   plugins: [
     sentrySvelteKit({
       autoUploadSourceMaps: false,
@@ -17,6 +23,7 @@ export default defineConfig({
       prerender: {
         handleHttpError: 'ignore',
       },
+      paths: tunnelVariant ? { base: '/app' } : undefined,
     }),
   ],
 });

dev-packages/e2e-tests/test-applications/sveltekit-3/package.json

@@ -12,7 +12,10 @@
     "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
     "test:prod": "TEST_ENV=production playwright test",
     "test:build": "pnpm install && pnpm build",
-    "test:assert": "pnpm test:prod"
+    "test:assert": "pnpm test:prod",
+    "test:build:tunnel": "pnpm install && E2E_TEST_TUNNEL=1 E2E_TEST_DSN=http://public@localhost:3031/1337 PUBLIC_E2E_TEST_DSN=http://public@localhost:3031/1337 pnpm build",
+    "test:assert:tunnel": "E2E_TEST_TUNNEL=1 E2E_TEST_DSN=http://public@localhost:3031/1337 PUBLIC_E2E_TEST_DSN=http://public@localhost:3031/1337 TEST_ENV=production playwright test tunnel",
+    "test:assert:tunnel-dev": "E2E_TEST_TUNNEL=1 E2E_TEST_DSN=http://public@localhost:3031/1337 PUBLIC_E2E_TEST_DSN=http://public@localhost:3031/1337 TEST_ENV=development playwright test tunnel"
   },
   "dependencies": {
     "@sentry/sveltekit": "file:../../packed/sentry-sveltekit-packed.tgz"
@@ -31,5 +34,19 @@
   "volta": {
     "extends": "../../package.json"
   },
-  "type": "module"
+  "type": "module",
+  "sentryTest": {
+    "variants": [
+      {
+        "label": "sveltekit-3 (tunnel)",
+        "build-command": "pnpm test:build:tunnel",
+        "assert-command": "pnpm test:assert:tunnel"
+      },
+      {
+        "label": "sveltekit-3 (tunnel-dev)",
+        "build-command": "pnpm install",
+        "assert-command": "pnpm test:assert:tunnel-dev"
+      }
+    ]
+  }
 }

dev-packages/e2e-tests/test-applications/sveltekit-3/src/app.d.ts

@@ -1,6 +1,8 @@
 // See https://kit.svelte.dev/docs/types#app
 // for information about these interfaces
 declare global {
+  const __E2E_TEST_TUNNEL__: boolean;
+
   namespace App {
     // interface Error {}
     // interface Locals {}

dev-packages/e2e-tests/test-applications/sveltekit-3/src/hooks.client.ts

@@ -4,7 +4,7 @@ import * as Sentry from '@sentry/sveltekit';
 Sentry.init({
   environment: 'qa', // dynamic sampling bias to keep transactions
   dsn: PUBLIC_E2E_TEST_DSN,
-  tunnel: `http://localhost:3031/`, // proxy server
+  tunnel: __E2E_TEST_TUNNEL__ ? true : `http://localhost:3031/`, // proxy server
   tracesSampleRate: 1.0,
 });
 

dev-packages/e2e-tests/test-applications/sveltekit-3/src/instrumentation.server.ts

@@ -7,6 +7,6 @@ Sentry.init({
   environment: 'qa', // dynamic sampling bias to keep transactions
   dsn: E2E_TEST_DSN,
   debug: !!process.env.DEBUG,
-  tunnel: `http://localhost:3031/`, // proxy server
+  tunnel: __E2E_TEST_TUNNEL__ ? true : `http://localhost:3031/`, // proxy server
   tracesSampleRate: 1.0,
 });

dev-packages/e2e-tests/test-applications/sveltekit-3/tests/tunnel.test.ts

@@ -0,0 +1,38 @@
+import { expect, test } from '@playwright/test';
+import { waitForError, watchForTunnelSpan } from '@sentry-internal/test-utils';
+import type { SerializedStreamedSpan } from '@sentry-internal/test-utils';
+
+test.skip(!process.env.E2E_TEST_TUNNEL, 'Only runs in the tunnel variant');
+
+const APP_NAME = 'sveltekit-3';
+const TUNNEL_PATH = /^\/app\/[a-z0-9]{1,7}$/;
+
+// Kit's own `sveltekit.handle.root` span starts with only `http.url`, no `url.path`.
+function getSpanPath(span: SerializedStreamedSpan): string {
+  const url = String(span.attributes['http.url']?.value ?? span.attributes['url.path']?.value ?? '');
+
+  return url.startsWith('http') ? new URL(url).pathname : url;
+}
+
+test('sends client events through the managed tunnel under the base path, without spans of it', async ({ page }) => {
+  const errorEventPromise = waitForError(APP_NAME, event => event?.exception?.values?.[0]?.value === 'Click Error');
+  const raceTunnelSpan = watchForTunnelSpan(APP_NAME, span => TUNNEL_PATH.test(getSpanPath(span)));
+
+  // The pageload envelope is the first tunnel request, and it's only sent once the app hydrated.
+  const tunnelResponsePromise = page.waitForResponse(
+    response => response.request().method() === 'POST' && TUNNEL_PATH.test(new URL(response.url()).pathname),
+  );
+  await page.goto('/app/client-error');
+
+  expect((await tunnelResponsePromise).status()).toBe(200);
+
+  await page.getByText('Throw error').click();
+  await expect(errorEventPromise).resolves.toBeDefined();
+
+  expect(
+    await raceTunnelSpan(
+      span => getSpanPath(span).endsWith('/app/users/123'),
+      () => page.request.get('/app/users/123'),
+    ),
+  ).toBe('anchor');
+});

dev-packages/e2e-tests/test-applications/sveltekit-3/vite.config.js

@@ -4,7 +4,13 @@ import { sveltekit } from '@sveltejs/kit/vite';
 import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
 import { defineConfig } from 'vite';
 
+// The tunnel variant serves the app under a base path to cover that the managed tunnel follows it.
+const tunnelVariant = !!process.env.E2E_TEST_TUNNEL;
+
 export default defineConfig({
+  define: {
+    __E2E_TEST_TUNNEL__: JSON.stringify(tunnelVariant),
+  },
   plugins: [
     sentrySvelteKit({
       autoUploadSourceMaps: false,
@@ -22,6 +28,7 @@ export default defineConfig({
       tracing: {
         server: true,
       },
+      paths: tunnelVariant ? { base: '/app' } : undefined,
     }),
   ],
 });

dev-packages/test-utils/src/index.ts

@@ -17,6 +17,7 @@ export {
   getSpanOp,
 } from './event-proxy-server';
 export type { SerializedStreamedSpan } from '@sentry/core';
+export { isServerSpanAt, watchForTunnelSpan } from './tunnel';
 
 export {
   findAbsolutePathImports,

dev-packages/test-utils/src/tunnel.ts

@@ -0,0 +1,37 @@
+import type { SerializedStreamedSpan } from '@sentry/core';
+import { getSpanOp, waitForStreamedSpan } from './event-proxy-server';
+
+type SpanMatcher = (span: SerializedStreamedSpan) => boolean;
+
+/**
+ * Matches an `http.server` span whose `url.path` equals or matches `path`.
+ */
+export function isServerSpanAt(path: string | RegExp): SpanMatcher {
+  return span => {
+    const urlPath = String(span.attributes['url.path']?.value ?? '');
+
+    return getSpanOp(span) === 'http.server' && (typeof path === 'string' ? urlPath === path : path.test(urlPath));
+  };
+}
+
+/**
+ * Starts listening for a span of a tunnel request. Call it before the tunnel traffic, then call the returned function
+ * with a regular request made after it. Spans flush in order, so it resolves to `'tunnel'` if the tunnel request
+ * created a span, and to `'anchor'` otherwise, without waiting on a timeout.
+ */
+export function watchForTunnelSpan(
+  proxyServerName: string,
+  isTunnelSpan: SpanMatcher,
+): (isAnchorSpan: SpanMatcher, requestAnchor: () => Promise<unknown>) => Promise<'tunnel' | 'anchor'> {
+  const tunnelSpanPromise = waitForStreamedSpan(proxyServerName, isTunnelSpan);
+
+  return async (isAnchorSpan, requestAnchor) => {
+    const anchorSpanPromise = waitForStreamedSpan(proxyServerName, isAnchorSpan);
+    await requestAnchor();
+
+    return Promise.race([
+      tunnelSpanPromise.then(() => 'tunnel' as const),
+      anchorSpanPromise.then(() => 'anchor' as const),
+    ]);
+  };
+}

packages/sveltekit/src/client/sdk.ts

@@ -2,6 +2,7 @@ import type { Client, Integration } from '@sentry/core';
 import { applySdkMetadata } from '@sentry/core';
 import type { BrowserOptions } from '@sentry/svelte';
 import { getDefaultIntegrations as getDefaultSvelteIntegrations, init as initSvelteSdk, WINDOW } from '@sentry/svelte';
+import { applyTunnelBasePath } from '../common/tunnel';
 import { browserTracingIntegration as svelteKitBrowserTracingIntegration } from './browserTracingIntegration';
 
 type WindowWithSentryFetchProxy = typeof WINDOW & {
@@ -23,6 +24,7 @@ export function init(options: BrowserOptions): Client | undefined {
   };
 
   applySdkMetadata(opts, 'sveltekit', ['sveltekit', 'svelte']);
+  applyTunnelBasePath(opts);
 
   // 1. Switch window.fetch to our fetch proxy we injected earlier
   const actualFetch = switchToFetchProxy();

packages/sveltekit/src/common/tunnel.ts

@@ -0,0 +1,14 @@
+import type { Options } from '@sentry/core';
+import { applyTunnelDefaults, GLOBAL_OBJ } from '@sentry/core';
+
+/** Set by `sentrySvelteKit()` to the app's `paths.base`. */
+export const TUNNEL_BASE_PATH_GLOBAL = '__sentry_sveltekit_base_path';
+
+/**
+ * Serves the managed tunnel under the app's base path, which SvelteKit requires for every request it handles.
+ * A `basePath` the user set wins.
+ */
+export function applyTunnelBasePath(options: Pick<Options, 'tunnel'>): void {
+  const basePath = (GLOBAL_OBJ as { [TUNNEL_BASE_PATH_GLOBAL]?: string })[TUNNEL_BASE_PATH_GLOBAL];
+  options.tunnel = applyTunnelDefaults(options.tunnel, { basePath });
+}

packages/sveltekit/src/server-common/handle.ts

@@ -19,7 +19,7 @@ import {
   withIsolationScope,
   filterCollectedUrl,
 } from '@sentry/core';
-import { flushIfServerless } from '@sentry/core/server';
+import { flushIfServerless, handleTunnelRequestIfMatched } from '@sentry/core/server';
 import type { Handle, ResolveOptions } from '@sveltejs/kit';
 import { DEBUG_BUILD } from '../common/debug-build';
 import { getTracePropagationData, sendErrorToSentry } from './utils';
@@ -291,6 +291,11 @@ export function sentryHandle(handlerOptions?: SentryHandleOptions): Handle {
   };
 
   const sentryRequestHandler: Handle = input => {
+    const tunnelResponse = handleTunnelRequestIfMatched(input.event.request);
+    if (tunnelResponse) {
+      return tunnelResponse;
+    }
+
     const backwardsForwardsCompatibleEvent = input.event as typeof input.event & BackwardsForwardsCompatibleEvent;
 
     // Escape hatch to suppress request isolation and trace continuation (see initCloudflareSentryHandle)

packages/sveltekit/src/server/sdk.ts

@@ -1,6 +1,7 @@
 import { applySdkMetadata } from '@sentry/core';
 import type { NodeClient, NodeOptions } from '@sentry/node';
 import { getDefaultIntegrations as getDefaultNodeIntegrations, init as initNodeSdk } from '@sentry/node';
+import { applyTunnelBasePath } from '../common/tunnel';
 import { rewriteFramesIntegration } from '../server-common/integrations/rewriteFramesIntegration';
 import { svelteKitSpansIntegration } from '../server-common/integrations/svelteKitSpans';
 import { httpIntegration } from './integrations/http';
@@ -26,6 +27,7 @@ export function init(options: NodeOptions): NodeClient | undefined {
   };
 
   applySdkMetadata(opts, 'sveltekit', ['sveltekit', 'node']);
+  applyTunnelBasePath(opts);
 
   return initNodeSdk(opts);
 }

packages/sveltekit/src/vite/sentryVitePlugins.ts

@@ -11,6 +11,7 @@ import { makeGlobalValuesInjectionPlugin } from './injectGlobalValues';
 import { createKitConfigResolver } from './kitConfig';
 import { makeCustomSentryVitePlugins } from './sourceMaps';
 import { getAdapterOutputDir } from './svelteConfig';
+import { makeTunnelBasePathPlugin } from './tunnelBasePath';
 import type { CustomSentryVitePluginOptions, SentrySvelteKitPluginOptions } from './types';
 
 const DEFAULT_PLUGIN_OPTIONS: SentrySvelteKitPluginOptions = {
@@ -56,6 +57,7 @@ export async function sentrySvelteKit(options: SentrySvelteKitPluginOptions = {}
     kitConfigResolver.plugin,
     makeBrowserTracingVariantResolverPlugin(),
     makeOpenTelemetryApiResolverPlugin(),
+    makeTunnelBasePathPlugin(getKitConfig),
   ];
 
   if (mergedOptions.autoInstrument) {

packages/sveltekit/src/vite/tunnelBasePath.ts

@@ -0,0 +1,50 @@
+import { escapeStringForRegex } from '@sentry/core';
+import MagicString from 'magic-string';
+import type { Plugin } from 'vite';
+import { TUNNEL_BASE_PATH_GLOBAL } from '../common/tunnel';
+import type { ResolvedKitConfig } from './kitConfig';
+import { getHooksFileName } from './svelteConfig';
+
+const VIRTUAL_BASE_PATH_FILE = '\0sentry-sveltekit-tunnel-base-path';
+
+/**
+ * Hands the app's `paths.base` to the client and server SDKs so `tunnel: true` works under a base path without
+ * the user repeating it. It's imported first in the hooks files, so it's set before any `init` they import.
+ */
+export function makeTunnelBasePathPlugin(getKitConfig: () => Promise<ResolvedKitConfig>): Plugin {
+  let basePath = '';
+  let entryFileRegexp: RegExp | undefined;
+
+  return {
+    name: 'sentry-sveltekit-tunnel-base-path',
+
+    configResolved: async () => {
+      const kitConfig = await getKitConfig();
+      basePath = kitConfig.paths?.base || '';
+
+      const hooksFiles = [getHooksFileName(kitConfig, 'server'), getHooksFileName(kitConfig, 'client')]
+        .map(escapeStringForRegex)
+        .join('|');
+      // oxlint-disable-next-line sdk/no-regexp-constructor -- not end user input + escaped anyway
+      entryFileRegexp = new RegExp(`/(?:${hooksFiles}|src/instrumentation\\.server)\\.(?:js|ts|mjs|mts)$`);
+    },
+
+    resolveId: id => (id === VIRTUAL_BASE_PATH_FILE ? { id, moduleSideEffects: true } : null),
+
+    load: id =>
+      id === VIRTUAL_BASE_PATH_FILE
+        ? `globalThis[${JSON.stringify(TUNNEL_BASE_PATH_GLOBAL)}] = ${JSON.stringify(basePath)};`
+        : null,
+
+    transform: (code, id) => {
+      if (!basePath || !entryFileRegexp?.test(id)) {
+        return null;
+      }
+
+      const ms = new MagicString(code);
+      ms.prepend(`import ${JSON.stringify(VIRTUAL_BASE_PATH_FILE)};\n`);
+
+      return { code: ms.toString(), map: ms.generateMap({ hires: true }) };
+    },
+  };
+}