feat: Polish the public tunnel API and export it on Server SDKs

packages/astro/src/index.server.ts

@@ -164,6 +164,10 @@ export {
   tediousIntegration,
   trpcMiddleware,
   serveTunnelIntegration,
+  getTunnelPath,
+  handleTunnelRequest,
+  handleTunnelRequestIfMatched,
+  isTunnelRequest,
   updateSpanName,
   vercelAIIntegration,
   withActiveSpan,

packages/astro/src/server/middleware.ts

@@ -26,7 +26,10 @@ import {
   filterCollectedUrl,
   filterCollectedUrlQuery,
 } from '@sentry/core';
-import { flushIfServerless, handleTunnelRequestIfMatched } from '@sentry/core/server';
+import {
+  flushIfServerless,
+  _INTERNAL_handleServedTunnelRequest as handleServedTunnelRequest,
+} from '@sentry/core/server';
 import {
   captureException,
   continueTrace,
@@ -87,7 +90,7 @@ export const handleRequest: (options?: MiddlewareOptions) => MiddlewareHandler =
       return next();
     }
 
-    const tunnelResponse = handleTunnelRequestIfMatched(ctx.request);
+    const tunnelResponse = handleServedTunnelRequest(ctx.request);
     if (tunnelResponse) {
       return tunnelResponse;
     }

packages/astro/test/server/middleware.test.ts

@@ -39,7 +39,7 @@ describe('sentryMiddleware with the managed tunnel', () => {
     const getClientSpy = vi.spyOn(SentryNode, 'getClient').mockReturnValue({} as Client);
     const tunnelResponse = new Response('forwarded');
     const matcherSpy = vi
-      .spyOn(SentryCoreServer, 'handleTunnelRequestIfMatched')
+      .spyOn(SentryCoreServer, '_INTERNAL_handleServedTunnelRequest')
       .mockReturnValue(Promise.resolve(tunnelResponse));
     const next = vi.fn();
     const request = new Request('https://myDomain.io/abc123', { method: 'POST' });

packages/aws-serverless/src/index.ts

@@ -152,6 +152,10 @@ export {
   systemErrorIntegration,
   trpcMiddleware,
   serveTunnelIntegration,
+  getTunnelPath,
+  handleTunnelRequest,
+  handleTunnelRequestIfMatched,
+  isTunnelRequest,
   updateSpanName,
   supabaseIntegration,
   instrumentSupabaseClient,
@@ -193,6 +197,7 @@ export {
   eveIntegration,
   getInstrumentedModuleNames,
 } from '@sentry/node';
+export type { HandleTunnelRequestOptions, ServerTunnelOptions, TunnelRequestLike } from '@sentry/node';
 
 export {
   captureConsoleIntegration,

packages/bun/src/index.ts

@@ -172,6 +172,10 @@ export {
   spanToBaggageHeader,
   trpcMiddleware,
   serveTunnelIntegration,
+  getTunnelPath,
+  handleTunnelRequest,
+  handleTunnelRequestIfMatched,
+  isTunnelRequest,
   updateSpanName,
   supabaseIntegration,
   instrumentSupabaseClient,
@@ -214,6 +218,7 @@ export {
   eveIntegration,
   getInstrumentedModuleNames,
 } from '@sentry/node';
+export type { HandleTunnelRequestOptions, ServerTunnelOptions, TunnelRequestLike } from '@sentry/node';
 
 export {
   captureConsoleIntegration,

packages/cloudflare/src/index.ts

@@ -110,7 +110,16 @@ export {
   withStreamedSpan,
   spanStreamingIntegration,
 } from '@sentry/core';
-export { trpcMiddleware, serveTunnelIntegration, wrapMcpServerWithSentry } from '@sentry/core/server';
+export {
+  handleTunnelRequestIfMatched,
+  isTunnelRequest,
+  serveTunnelIntegration,
+  trpcMiddleware,
+  wrapMcpServerWithSentry,
+} from '@sentry/core/server';
+export type { TunnelRequestLike } from '@sentry/core/server';
+export { getTunnelPath, handleTunnelRequest } from '@sentry/core';
+export type { HandleTunnelRequestOptions, ServerTunnelOptions } from '@sentry/core';
 export { createFlueInstrumentation, instrumentPostgresJsSql } from '@sentry/server-utils';
 export type { FlueOptions } from '@sentry/server-utils';
 

packages/cloudflare/test/tunnelExports.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import * as Sentry from '../src';
+import type { HandleTunnelRequestOptions, ServerTunnelOptions, TunnelRequestLike } from '../src';
+
+describe('managed tunnel exports', () => {
+  it.each([
+    'serveTunnelIntegration',
+    'handleTunnelRequestIfMatched',
+    'isTunnelRequest',
+    'getTunnelPath',
+    'handleTunnelRequest',
+  ])('exports %s for wiring the tunnel by hand', name => {
+    expect(typeof (Sentry as Record<string, unknown>)[name]).toBe('function');
+  });
+
+  it('exports the tunnel types', () => {
+    const tunnelOptions: ServerTunnelOptions = { allowedDsns: [] };
+    const request: TunnelRequestLike = { method: 'POST', url: '/tunnel' };
+    const handleOptions: HandleTunnelRequestOptions = { request: new Request('http://localhost/tunnel') };
+
+    expect([tunnelOptions, request, handleOptions]).toHaveLength(3);
+  });
+});

packages/core/src/integrations/serveTunnel.ts

@@ -1,7 +1,8 @@
 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 { enableManagedTunnel } from '../utils/managedTunnelDefaults';
+import { SERVE_TUNNEL_INTEGRATION_NAME } from '../utils/tunnel';
 import { forwardTunnelRequest } from '../utils/tunnelForward';
 
 const _serveTunnelIntegration = ((options: ServerTunnelOptions = {}) => {

packages/core/src/server.ts

@@ -9,10 +9,14 @@ export { ServerRuntimeClient } from './server-runtime-client';
 export type { TunnelRequestLike } from './utils/tunnel';
 export {
   getTunnelPaths as _INTERNAL_getTunnelPaths,
-  handleTunnelRequestIfMatched,
+  handleServedTunnelRequest as _INTERNAL_handleServedTunnelRequest,
+  isServedTunnelRequest as _INTERNAL_isServedTunnelRequest,
   isTunnelRequest,
 } from './utils/tunnel';
-export { forwardTunnelRequest as _INTERNAL_forwardTunnelRequest } from './utils/tunnelForward';
+export {
+  forwardTunnelRequest as _INTERNAL_forwardTunnelRequest,
+  handleTunnelRequestIfMatched,
+} from './utils/tunnelForward';
 export { serveTunnelIntegration } from './integrations/serveTunnel';
 export {
   _INTERNAL_resetManagedTunnelDefaults,

packages/core/src/utils/managedTunnelDefaults.ts

@@ -1,13 +1,11 @@
 import type { Client } from '../client';
-import type { Integration } from '../types/integration';
 import { getClient } from '../currentScopes';
 import type { IgnoreSpanFilter, ServerTunnelOptions } from '../types/options';
 import type { TunnelForwarder } from './tunnel';
 import {
+  getServeTunnelForwarder,
   getTunnelIgnoreSpanFilters,
   normalizeTunnelBasePath,
-  resolveAllowedDsns,
-  resolveTunnelPaths,
   setServedTunnel,
 } from './tunnel';
 
@@ -29,12 +27,6 @@ interface ManagedTunnelDefaults {
   basePath?: string;
 }
 
-/**
- * The name of `serveTunnelIntegration`, which carries the forwarder. Kept here so this module doesn't import the
- * integration, and with it the forwarder, into apps that don't use it.
- */
-export const SERVE_TUNNEL_INTEGRATION_NAME = 'ServeTunnel';
-
 let managedTunnelDefaults: ManagedTunnelDefaults | undefined;
 
 const tunnelForwarders = new WeakMap<Client, TunnelForwarder>();
@@ -78,11 +70,7 @@ export function applyManagedTunnelDefaults(client: Client | undefined): void {
   const tunnelOptions: ServerTunnelOptions | undefined = options?._managedTunnel ?? managedTunnelDefaults?.tunnel;
   // A framework SDK can bundle its own copy of this module, which only reaches the forwarder through the client.
   const forward =
-    client &&
-    (tunnelForwarders.get(client) ??
-      client.getIntegrationByName?.<Integration & { forward?: TunnelForwarder }>(SERVE_TUNNEL_INTEGRATION_NAME)
-        ?.forward ??
-      managedTunnelDefaults?.forward);
+    client && (tunnelForwarders.get(client) ?? getServeTunnelForwarder(client) ?? managedTunnelDefaults?.forward);
   if (!client || !options || !tunnelOptions || !forward) {
     return;
   }
@@ -93,9 +81,7 @@ export function applyManagedTunnelDefaults(client: Client | undefined): void {
       ? { ...tunnelOptions, basePath }
       : tunnelOptions;
   options._managedTunnel = resolved;
-  const allowedDsns = resolveAllowedDsns(resolved.allowedDsns, client.getDsn());
-  const paths = resolveTunnelPaths(resolved, allowedDsns);
-  setServedTunnel(client, { paths, allowedDsns, forward });
+  const { paths } = setServedTunnel(client, resolved, forward);
 
   const previousFilters = installedSpanFilters.get(client) ?? [];
   const spanFilters = getTunnelIgnoreSpanFilters(resolved, paths);

packages/core/src/utils/tunnel.ts

@@ -1,4 +1,5 @@
 import type { Client } from '../client';
+import type { Integration } from '../types/integration';
 import { getClient } from '../currentScopes';
 import { URL_PATH } from '@sentry/conventions/attributes';
 import type { DsnComponents, DsnLike } from '../types/dsn';
@@ -13,27 +14,68 @@ import { parseUrl } from './url';
 export type TunnelForwarder = (request: Request, allowedDsns: Array<string>) => Promise<Response>;
 
 /**
- * A server client's tunnel paths, allowed DSNs and forwarder, computed once per client.
+ * A server client's tunnel paths, base path, allowed DSNs and forwarder, computed once per client.
  */
-interface ServedTunnel {
-  paths: string[];
-  allowedDsns: string[];
+interface ServedTunnel extends TunnelMatch {
   forward: TunnelForwarder;
 }
 
 const servedTunnels = new WeakMap<Client, ServedTunnel>();
 
 /**
- * Stores a server client's computed tunnel paths and allowed DSNs.
+ * The name of `serveTunnelIntegration`, which carries the forwarder. Kept here so this module doesn't import the
+ * integration, and with it the forwarder, into apps that don't use it.
+ */
+export const SERVE_TUNNEL_INTEGRATION_NAME = 'ServeTunnel';
+
+/**
+ * Computes a server client's served tunnel from its resolved options, and stores it.
  */
-export function setServedTunnel(client: Client, servedTunnel: ServedTunnel): void {
+export function setServedTunnel(
+  client: Client,
+  tunnelOptions: ServerTunnelOptions,
+  forward: TunnelForwarder,
+): ServedTunnel {
+  const allowedDsns = resolveAllowedDsns(tunnelOptions.allowedDsns, client.getDsn());
+  const servedTunnel = {
+    paths: resolveTunnelPaths(tunnelOptions, allowedDsns),
+    basePath: tunnelOptions.basePath,
+    allowedDsns,
+    forward,
+  };
   servedTunnels.set(client, servedTunnel);
+
+  return servedTunnel;
 }
 
+/**
+ * The forwarder `serveTunnelIntegration` carries. Any copy of this module can reach it through the client.
+ */
+export function getServeTunnelForwarder(client: Client): TunnelForwarder | undefined {
+  return client.getIntegrationByName?.<Integration & { forward?: TunnelForwarder }>(SERVE_TUNNEL_INTEGRATION_NAME)
+    ?.forward;
+}
+
+/**
+ * The active client's served tunnel. A copy of this module that didn't set it up rebuilds it once from what the
+ * client carries. Bundlers can give a framework's request hook its own copy, like Next.js's middleware next to its
+ * `instrumentation`.
+ */
 function getServedTunnel(): ServedTunnel | undefined {
   const client = getClient();
+  if (!client) {
+    return undefined;
+  }
+
+  const servedTunnel = servedTunnels.get(client);
+  if (servedTunnel) {
+    return servedTunnel;
+  }
 
-  return client && servedTunnels.get(client);
+  const tunnelOptions = client.getOptions()._managedTunnel;
+  const forward = getServeTunnelForwarder(client);
+
+  return tunnelOptions && forward ? setServedTunnel(client, tunnelOptions, forward) : undefined;
 }
 
 /**
@@ -60,11 +102,11 @@ export function applyTunnelDefaults(
 }
 
 /**
- * Returns the same-origin tunnel path for a DSN, e.g. `/k3x9q2a`. Browser and server derive it independently,
- * and as a hash it gives ad-blocker filter lists nothing to match.
+ * Returns the same-origin tunnel path for a DSN, e.g. `/k3x9q2a`, by default the active client's. Browser and server
+ * derive it independently, and as a hash it gives ad-blocker filter lists nothing to match.
  */
-export function getTunnelPath(dsn: DsnLike): string | undefined {
-  const components = makeDsn(dsn);
+export function getTunnelPath(dsn?: DsnLike): string | undefined {
+  const components = dsn ? makeDsn(dsn) : getClient()?.getDsn();
 
   return components ? `/${fnv1a32(dsnToString(components)).toString(36)}` : undefined;
 }
@@ -76,7 +118,6 @@ export interface TunnelRequestLike {
   method?: string;
   /** Absolute URL or path with query, e.g. Node's `IncomingMessage.url`. */
   url?: string;
-  headers?: Headers | Record<string, string | string[] | undefined>;
 }
 
 /**
@@ -133,29 +174,67 @@ export function normalizeTunnelBasePath(basePath: string | undefined): string {
 }
 
 /**
- * Returns true if the request targets the active server client's managed tunnel.
+ * The paths, base path and allowed DSNs of a tunnel to match requests against.
  */
-export function isTunnelRequest(request: TunnelRequestLike): boolean {
-  if (request.method !== 'POST' || !request.url) {
-    return false;
+interface TunnelMatch {
+  paths: string[];
+  basePath?: string;
+  allowedDsns: string[];
+}
+
+/**
+ * Resolves the tunnel the public helpers match: `options`, else the one `serveTunnelIntegration` serves, else the
+ * path of the active client's own DSN.
+ */
+export function resolveTunnelMatch(options?: ServerTunnelOptions): TunnelMatch {
+  const servedTunnel = !options && getServedTunnel();
+  if (servedTunnel) {
+    return servedTunnel;
   }
 
-  const tunnelOptions = getClient()?.getOptions()._managedTunnel;
-  if (!tunnelOptions) {
+  const allowedDsns = resolveAllowedDsns(options?.allowedDsns, getClient()?.getDsn());
+
+  return { paths: resolveTunnelPaths(options ?? {}, allowedDsns), basePath: options?.basePath, allowedDsns };
+}
+
+/**
+ * Returns true if the request is a POST to one of the tunnel's paths.
+ */
+export function matchesTunnel(request: TunnelRequestLike, tunnel: Omit<TunnelMatch, 'allowedDsns'>): boolean {
+  if (request.method !== 'POST' || !request.url) {
     return false;
   }
 
-  const path = stripBasePath(parseUrl(request.url).path || '/', tunnelOptions.basePath);
+  const path = stripBasePath(parseUrl(request.url).path || '/', tunnel.basePath);
+
+  return path !== undefined && tunnel.paths.includes(path.replace(/\/$/, ''));
+}
+
+/**
+ * Returns true if the request is a POST to the managed tunnel. The tunnel comes from `options`, else from
+ * `serveTunnelIntegration`, else it's the path of the active client's own DSN.
+ */
+export function isTunnelRequest(request: TunnelRequestLike, options?: ServerTunnelOptions): boolean {
+  return matchesTunnel(request, resolveTunnelMatch(options));
+}
+
+/**
+ * Returns true if the request targets the tunnel `serveTunnelIntegration` serves. Unlike {@link isTunnelRequest},
+ * there's no fallback, so the framework SDKs serve nothing without the integration.
+ */
+export function isServedTunnelRequest(request: TunnelRequestLike): boolean {
+  const servedTunnel = getServedTunnel();
 
-  return path !== undefined && getTunnelPaths().includes(path.replace(/\/$/, ''));
+  return !!servedTunnel && matchesTunnel(request, servedTunnel);
 }
 
 /**
- * Forwards the request if it targets the managed tunnel, otherwise returns `undefined` for the app to handle.
+ * Forwards the request if it targets the tunnel `serveTunnelIntegration` serves, otherwise returns `undefined`. The
+ * framework SDKs answer tunnel requests with it.
  */
-export function handleTunnelRequestIfMatched(request: Request): Promise<Response> | undefined {
+export function handleServedTunnelRequest(request: Request): Promise<Response> | undefined {
   const servedTunnel = getServedTunnel();
-  if (!servedTunnel?.allowedDsns.length || !isTunnelRequest(request)) {
+  if (!servedTunnel?.allowedDsns.length || !matchesTunnel(request, servedTunnel)) {
     return undefined;
   }