feat: Accept tunnel: true in init to enable the managed tunnel

packages/astro/src/index.server.ts

@@ -163,6 +163,7 @@ export {
   systemErrorIntegration,
   tediousIntegration,
   trpcMiddleware,
+  serveTunnelIntegration,
   updateSpanName,
   vercelAIIntegration,
   withActiveSpan,

packages/aws-serverless/src/index.ts

@@ -151,6 +151,7 @@ export {
   spanToBaggageHeader,
   systemErrorIntegration,
   trpcMiddleware,
+  serveTunnelIntegration,
   updateSpanName,
   supabaseIntegration,
   instrumentSupabaseClient,

packages/browser/src/client.ts

@@ -1,11 +1,13 @@
 import type {
+  BrowserTunnelOptions,
   ClientOptions,
   Event,
   EventHint,
   Options as CoreOptions,
   ParameterizedString,
   Scope,
   SeverityLevel,
+  TunnelInit,
 } from '@sentry/core';
 import type { BrowserClientReplayOptions } from '@sentry/core/browser';
 import type { RouteProvider } from '@sentry/browser-utils';
@@ -91,7 +93,15 @@ type BrowserSpecificOptions = BrowserClientReplayOptions &
  * Configuration options for the Sentry Browser SDK.
  * @see @sentry/core Options for more information.
  */
-export type BrowserOptions = CoreOptions<BrowserTransportOptions> & BrowserSpecificOptions;
+export type BrowserOptions = CoreOptions<BrowserTransportOptions> &
+  BrowserSpecificOptions & {
+    /**
+     * Where to send envelopes instead of the Sentry ingest URL, see {@link TunnelInit}.
+     *
+     * @default undefined
+     */
+    tunnel?: TunnelInit<BrowserTunnelOptions>;
+  };
 
 /**
  * Configuration options for the Sentry Browser SDK Client class

packages/browser/src/sdk.ts

@@ -24,6 +24,7 @@ import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport } from './transports/fetch';
 import { normalizeStringifyValue } from './normalizeStringifyValue';
 import { checkAndWarnIfIsEmbeddedBrowserExtension } from './utils/detectBrowserExtension';
+import { resolveBrowserTunnelOption } from './utils/managedTunnel';
 
 /** Get the default integrations for the browser SDK. */
 export function getDefaultIntegrations(_options: Options): Integration[] {
@@ -117,6 +118,7 @@ export function init(options: BrowserOptions = {}): Client | undefined {
 
   const clientOptions: BrowserClientOptions = {
     ...options,
+    ...resolveBrowserTunnelOption(options),
     enabled: shouldDisableBecauseIsBrowserExtenstion ? false : options.enabled,
     stackParser: stackParserFromStackParserOptions(options.stackParser || defaultStackParser),
     integrations,

packages/browser/src/utils/managedTunnel.ts

@@ -0,0 +1,43 @@
+import type { BrowserTunnelOptions } from '@sentry/core';
+import {
+  debug,
+  getTunnelPath,
+  makeDsn,
+  _INTERNAL_normalizeTunnelBasePath as normalizeTunnelBasePath,
+} from '@sentry/core';
+import { DEBUG_BUILD } from '../debug-build';
+import type { BrowserOptions } from '../client';
+
+/**
+ * Resolves `tunnel: true` or {@link BrowserTunnelOptions} to the managed tunnel's same-origin path. A string is left as
+ * written, so a tunnel the app serves itself gets the same requests as before.
+ */
+export function resolveBrowserTunnelOption(
+  options: BrowserOptions,
+): Pick<BrowserOptions, 'transportOptions'> & { tunnel: string | undefined } {
+  const { tunnel, dsn, transportOptions } = options;
+  if (!tunnel || typeof tunnel === 'string') {
+    return { tunnel, transportOptions };
+  }
+
+  const tunnelOptions: BrowserTunnelOptions = tunnel === true ? {} : tunnel;
+  const dsnComponents = dsn && makeDsn(dsn);
+  const tunnelPath = tunnelOptions.path ?? (dsnComponents && getTunnelPath(dsnComponents));
+  if (!tunnelPath) {
+    return { tunnel: undefined, transportOptions };
+  }
+
+  const basePath = normalizeTunnelBasePath(tunnelOptions.basePath);
+  const resolvedTunnel = `${basePath}${tunnelPath}${tunnelOptions.trailingSlash ? '/' : ''}`;
+
+  DEBUG_BUILD && debug.log(`Tunneling events to "${resolvedTunnel}"`);
+
+  return {
+    tunnel: resolvedTunnel,
+    transportOptions: {
+      ...transportOptions,
+      // CSRF protection (SvelteKit, Astro) rejects the default `text/plain` POST to the tunnel as a form submission.
+      headers: { 'Content-Type': 'application/x-sentry-envelope', ...transportOptions?.headers },
+    },
+  };
+}

packages/browser/test/utils/managedTunnel.test.ts

@@ -0,0 +1,87 @@
+import { getTunnelPath } from '@sentry/core';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getClient, getCurrentScope, init } from '../../src';
+import { makeFetchTransport } from '../../src/transports/fetch';
+import { resolveBrowserTunnelOption } from '../../src/utils/managedTunnel';
+
+const DSN = 'https://[email protected]/1337';
+
+describe('resolveBrowserTunnelOption', () => {
+  it('resolves `tunnel: true` to the path the server derives from the same DSN', () => {
+    const { tunnel } = resolveBrowserTunnelOption({ dsn: DSN, tunnel: true });
+
+    expect(tunnel).toBe(getTunnelPath(DSN));
+  });
+
+  it('sends to a managed tunnel as application/x-sentry-envelope so CSRF checks do not treat it as a form post', () => {
+    expect(resolveBrowserTunnelOption({ dsn: DSN, tunnel: true }).transportOptions).toEqual({
+      headers: { 'Content-Type': 'application/x-sentry-envelope' },
+    });
+    expect(
+      resolveBrowserTunnelOption({ dsn: DSN, tunnel: true, transportOptions: { headers: { 'X-Custom': '1' } } })
+        .transportOptions,
+    ).toEqual({ headers: { 'Content-Type': 'application/x-sentry-envelope', 'X-Custom': '1' } });
+  });
+
+  it('prefixes the base path and appends a trailing slash when asked', () => {
+    const { tunnel } = resolveBrowserTunnelOption({ dsn: DSN, tunnel: { basePath: '/docs/', trailingSlash: true } });
+
+    expect(tunnel).toBe(`/docs${getTunnelPath(DSN)}/`);
+  });
+
+  it('normalizes the base path like the server does, so the tunnel URL is never page-relative', () => {
+    expect(resolveBrowserTunnelOption({ dsn: DSN, tunnel: { basePath: 'docs' } }).tunnel).toBe(
+      `/docs${getTunnelPath(DSN)}`,
+    );
+    expect(resolveBrowserTunnelOption({ dsn: DSN, tunnel: { basePath: './docs/' } }).tunnel).toBe(
+      `/docs${getTunnelPath(DSN)}`,
+    );
+    expect(resolveBrowserTunnelOption({ dsn: DSN, tunnel: { basePath: './' } }).tunnel).toBe(getTunnelPath(DSN));
+  });
+
+  it('uses a fixed path instead of the DSN-derived one', () => {
+    expect(resolveBrowserTunnelOption({ dsn: DSN, tunnel: { path: '/monitor' } }).tunnel).toBe('/monitor');
+  });
+
+  it.each(['https://proxy.example.com/tunnel', '/monitor'])(
+    'keeps the string tunnel %s and its transport options untouched',
+    tunnel => {
+      const transportOptions = { headers: { 'x-custom': '1' } };
+
+      expect(resolveBrowserTunnelOption({ dsn: DSN, tunnel, transportOptions })).toEqual({ tunnel, transportOptions });
+    },
+  );
+
+  it('turns the tunnel off without a valid DSN', () => {
+    expect(resolveBrowserTunnelOption({ tunnel: true }).tunnel).toBeUndefined();
+    expect(resolveBrowserTunnelOption({ dsn: 'not-a-dsn', tunnel: true }).tunnel).toBeUndefined();
+  });
+});
+
+describe('init with `tunnel: true`', () => {
+  afterEach(() => {
+    getCurrentScope().setClient(undefined);
+  });
+
+  it('gives the client a resolved tunnel URL', () => {
+    init({ dsn: DSN, tunnel: true, defaultIntegrations: false });
+
+    expect(getClient()?.getOptions().tunnel).toBe(getTunnelPath(DSN));
+  });
+
+  it('only sets the envelope content type for a managed tunnel', () => {
+    const transport = vi.fn(makeFetchTransport);
+
+    init({ dsn: DSN, tunnel: true, transport });
+    const managedTransportOptions = transport.mock.calls[0]?.[0];
+    init({ dsn: DSN, tunnel: 'https://proxy.example.com', transport });
+
+    expect(managedTransportOptions).toEqual(
+      expect.objectContaining({
+        url: getTunnelPath(DSN),
+        headers: { 'Content-Type': 'application/x-sentry-envelope' },
+      }),
+    );
+    expect(transport).toHaveBeenLastCalledWith(expect.not.objectContaining({ headers: expect.anything() }));
+  });
+});

packages/bun/src/index.ts

@@ -171,6 +171,7 @@ export {
   spanToTraceHeader,
   spanToBaggageHeader,
   trpcMiddleware,
+  serveTunnelIntegration,
   updateSpanName,
   supabaseIntegration,
   instrumentSupabaseClient,

packages/bun/src/types.ts

@@ -35,7 +35,13 @@ export interface BaseBunOptions extends ServerRuntimeOptions {
  * Configuration options for the Sentry Bun SDK
  * @see @sentry/core Options for more information.
  */
-export interface BunOptions extends Options<BaseTransportOptions>, BaseBunOptions {}
+export interface BunOptions extends Options<BaseTransportOptions>, BaseBunOptions {
+  /**
+   * A URL to send this server's own envelopes to instead of the Sentry ingest URL. To serve the managed tunnel for the
+   * browser, use `serveTunnelIntegration`.
+   */
+  tunnel?: string;
+}
 
 /**
  * Configuration options for the Sentry Bun SDK Client class

packages/cloudflare/src/client.ts

@@ -540,6 +540,12 @@ interface BaseCloudflareOptions {
  */
 export interface CloudflareOptions extends Options<CloudflareTransportOptions>, BaseCloudflareOptions {
   ctx?: ExecutionContextCompat;
+
+  /**
+   * A URL to send this server's own envelopes to instead of the Sentry ingest URL. To serve the managed tunnel for the
+   * browser, use `serveTunnelIntegration`.
+   */
+  tunnel?: string;
 }
 
 /**

packages/cloudflare/src/index.ts

@@ -110,7 +110,7 @@ export {
   withStreamedSpan,
   spanStreamingIntegration,
 } from '@sentry/core';
-export { trpcMiddleware, wrapMcpServerWithSentry } from '@sentry/core/server';
+export { trpcMiddleware, serveTunnelIntegration, wrapMcpServerWithSentry } from '@sentry/core/server';
 export { createFlueInstrumentation, instrumentPostgresJsSql } from '@sentry/server-utils';
 export type { FlueOptions } from '@sentry/server-utils';
 

packages/cloudflare/test/sdk.test.ts

@@ -6,7 +6,11 @@ import type { CloudflareOptions } from '../src/client';
 import { CloudflareClient } from '../src/client';
 import { getDefaultIntegrations, init } from '../src/sdk';
 import { resetSdk } from './testUtils';
-import { mysqlIntegration as exportedMysqlIntegration, spanStreamingIntegration } from '../src/';
+import {
+  mysqlIntegration as exportedMysqlIntegration,
+  spanStreamingIntegration,
+  serveTunnelIntegration,
+} from '../src/';
 
 describe('init', () => {
   beforeEach(() => {
@@ -23,6 +27,18 @@ describe('init', () => {
     expect(client).toBeInstanceOf(CloudflareClient);
   });
 
+  test('serves the managed tunnel with `serveTunnelIntegration`', () => {
+    const browserDsn = 'https://[email protected]/42';
+    init({
+      dsn: 'https://[email protected]/1337',
+      integrations: [serveTunnelIntegration({ allowedDsns: [browserDsn] })],
+    });
+
+    const options = getClient()?.getOptions();
+    expect(options?.tunnel).toBeUndefined();
+    expect(options?._managedTunnel).toEqual({ allowedDsns: [browserDsn] });
+  });
+
   test('installs SpanStreaming integration by default', () => {
     init({
       dsn: 'https://[email protected]/1337',

packages/core/src/client.ts

@@ -1317,6 +1317,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
       try {
         const result = await this._transport.send(envelope);
         this.emit('afterEnvelope', envelope);
+
         return result;
       } catch (reason) {
         DEBUG_BUILD && debug.error('Error while sending envelope:', reason);

packages/core/src/index.ts

@@ -101,13 +101,12 @@ export { isSentryRequestUrl } from './utils/isSentryRequestUrl';
 export { handleCallbackErrors } from './utils/handleCallbackErrors';
 export { safeCallback } from './utils/safeCallback';
 export { parameterize, fmt } from './utils/parameterize';
-export type { HandleTunnelRequestOptions } from './utils/tunnel';
+export type { HandleTunnelRequestOptions } from './utils/tunnelForward';
+export { handleTunnelRequest } from './utils/tunnelForward';
 export {
   applyTunnelDefaults as _INTERNAL_applyTunnelDefaults,
   getTunnelPath,
-  handleTunnelRequest,
   normalizeTunnelBasePath as _INTERNAL_normalizeTunnelBasePath,
-  TUNNEL_RESPONSE_HEADER,
 } from './utils/tunnel';
 export { addAutoIpAddressToSession } from './utils/ipAddress';
 export {

packages/core/src/integrations/serveTunnel.ts

@@ -0,0 +1,33 @@
+import { defineIntegration } from '../integration';
+import type { IntegrationFn } from '../types/integration';
+import type { ServerTunnelOptions } from '../types/options';
+import { enableManagedTunnel, SERVE_TUNNEL_INTEGRATION_NAME } from '../utils/managedTunnelDefaults';
+import { forwardTunnelRequest } from '../utils/tunnelForward';
+
+const _serveTunnelIntegration = ((options: ServerTunnelOptions = {}) => {
+  return {
+    name: SERVE_TUNNEL_INTEGRATION_NAME,
+    forward: forwardTunnelRequest,
+    setup(client) {
+      enableManagedTunnel(client, options, forwardTunnelRequest);
+    },
+  };
+}) satisfies IntegrationFn;
+
+/**
+ * Serves the managed tunnel, so a browser `init` with `tunnel: true` sends its envelopes through the app's own origin
+ * instead of the Sentry ingest URL, where ad-blockers can't drop them. The meta-framework SDKs answer the tunnel
+ * requests from their request hooks.
+ *
+ * By default the tunnel path is derived from the DSN, under the app's base path, and only envelopes for the server's
+ * own DSN are forwarded. A `path` is served as written.
+ *
+ * @example
+ * ```js
+ * Sentry.init({
+ *   dsn: '__DSN__',
+ *   integrations: [Sentry.serveTunnelIntegration()],
+ * });
+ * ```
+ */
+export const serveTunnelIntegration = defineIntegration(_serveTunnelIntegration);

packages/core/src/server.ts

@@ -11,8 +11,9 @@ export {
   getTunnelPaths as _INTERNAL_getTunnelPaths,
   handleTunnelRequestIfMatched,
   isTunnelRequest,
-  resolveServerTunnelOption as _INTERNAL_resolveServerTunnelOption,
 } from './utils/tunnel';
+export { forwardTunnelRequest as _INTERNAL_forwardTunnelRequest } from './utils/tunnelForward';
+export { serveTunnelIntegration } from './integrations/serveTunnel';
 export {
   _INTERNAL_resetManagedTunnelDefaults,
   setManagedTunnelDefaults as _INTERNAL_setManagedTunnelDefaults,