ref(core): Keep the Node tunnel handler out of bundles without a tunnel

Core's HTTP server instrumentation imported the tunnel's Node handler, so every Node and Cloudflare bundle carried
it. The tunnel now registers the handler in the tunnel store when its hooks install, and the instrumentation calls it
from there.

Author: logaretm

packages/core/src/integrations/http/server-subscription.ts

@@ -25,8 +25,7 @@ import { DEBUG_BUILD } from '../../debug-build';
 import { debug } from '../../utils/debug-logger';
 import { safeCallback } from '../../utils/safeCallback';
 import { isServedTunnelRequest } from '../../utils/tunnel';
-import { handleServedNodeTunnelRequest } from '../../utils/tunnelForward';
-import { setHttpServerAnswersTunnel } from '../../utils/tunnelStore';
+import { getNodeTunnelHandler, setHttpServerHandlesTunnel } from '../../utils/tunnelStore';
 import { getClient, getCurrentScope, getIsolationScope, withIsolationScope } from '../../currentScopes';
 import { hasSpansEnabled } from '../../utils/hasSpansEnabled';
 import {
@@ -139,7 +138,7 @@ export function instrumentServer(options: HttpInstrumentationOptions, server: Ht
       // second wrapper for the tunnel. With `intercept: false` the app answers them, so they keep their own isolation
       // scope.
       if (isServedTunnelRequest(request)) {
-        if (handleServedNodeTunnelRequest(request, response)) {
+        if (getNodeTunnelHandler()?.(request, response)) {
           return true;
         }
 
@@ -258,7 +257,7 @@ export function getHttpServerSubscriptions(options: HttpInstrumentationOptions):
   // this because it creates spans through a separate code path).
   const userWrap = options.wrapServerEmitRequest;
   const spanWrap = buildServerSpanWrap(options);
-  setHttpServerAnswersTunnel();
+  setHttpServerHandlesTunnel();
 
   const effectiveOptions: HttpInstrumentationOptions = {
     ...options,

packages/core/src/server.ts

@@ -14,7 +14,10 @@ export {
   isServedTunnelRequest as _INTERNAL_isServedTunnelRequest,
   isTunnelRequest,
 } from './utils/tunnel';
-export { httpServerAnswersTunnel as _INTERNAL_httpServerAnswersTunnel } from './utils/tunnelStore';
+export {
+  httpServerHandlesTunnel as _INTERNAL_httpServerHandlesTunnel,
+  setNodeTunnelHandler as _INTERNAL_setNodeTunnelHandler,
+} from './utils/tunnelStore';
 export {
   forwardTunnelRequest as _INTERNAL_forwardTunnelRequest,
   handleServedNodeTunnelRequest as _INTERNAL_handleServedNodeTunnelRequest,

packages/core/src/utils/tunnelForward.ts

@@ -130,6 +130,11 @@ export function handleTunnelRequestIfMatched(
   );
 }
 
+/**
+ * Answers a tunnel request on a Node server ahead of the app, see {@link handleServedNodeTunnelRequest}.
+ */
+export type NodeTunnelHandler = (request: NodeTunnelRequest, response: NodeTunnelResponse) => boolean;
+
 /**
  * Answers a request to the tunnel `serveTunnelIntegration` serves on a Node server, ahead of the app. Returns `true`
  * when it claimed the request and answers it, `false` to hand the request to the app.

packages/core/src/utils/tunnelStore.ts

@@ -3,6 +3,7 @@ import { getGlobalSingleton } from '../carrier';
 import type { IgnoreSpanFilter } from '../types/options';
 import type { TunnelDefaults } from './tunnelDefaults';
 import type { ServedTunnel, TunnelForwarder } from './tunnel';
+import type { NodeTunnelHandler } from './tunnelForward';
 
 /**
  * What the tunnel keeps per server client.
@@ -23,8 +24,10 @@ export interface ClientTunnelState {
 export interface TunnelStore {
   clients: WeakMap<Client, ClientTunnelState>;
   defaults?: TunnelDefaults;
-  /** Whether core's HTTP server instrumentation is set up, whose `emit` wrapper answers tunnel requests itself. */
-  httpServerAnswersTunnel?: boolean;
+  /** Whether core's HTTP server instrumentation is set up, whose `emit` wrapper handles tunnel requests itself. */
+  httpServerHandlesTunnel?: boolean;
+  /** Answers tunnel requests on Node servers. The tunnel sets it, so apps without one don't bundle it. */
+  nodeHandler?: NodeTunnelHandler;
 }
 
 /**
@@ -64,16 +67,30 @@ export function setStoredTunnelDefaults(defaults: TunnelDefaults | undefined): v
 }
 
 /**
- * Records that core's HTTP server instrumentation is set up. Its `emit` wrapper answers tunnel requests, so `node:http`
+ * Records that core's HTTP server instrumentation is set up. Its `emit` wrapper handles tunnel requests, so `node:http`
  * servers need no second one for the tunnel.
  */
-export function setHttpServerAnswersTunnel(): void {
-  getTunnelStore().httpServerAnswersTunnel = true;
+export function setHttpServerHandlesTunnel(): void {
+  getTunnelStore().httpServerHandlesTunnel = true;
 }
 
 /**
- * Whether core's HTTP server instrumentation answers tunnel requests, see {@link setHttpServerAnswersTunnel}.
+ * Whether core's HTTP server instrumentation handles tunnel requests, see {@link setHttpServerHandlesTunnel}.
  */
-export function httpServerAnswersTunnel(): boolean {
-  return !!getTunnelStore().httpServerAnswersTunnel;
+export function httpServerHandlesTunnel(): boolean {
+  return !!getTunnelStore().httpServerHandlesTunnel;
+}
+
+/**
+ * Sets what answers tunnel requests on Node servers, like the forwarder `serveTunnelIntegration` brings in.
+ */
+export function setNodeTunnelHandler(handler: NodeTunnelHandler): void {
+  getTunnelStore().nodeHandler = handler;
+}
+
+/**
+ * What answers tunnel requests on Node servers, see {@link setNodeTunnelHandler}.
+ */
+export function getNodeTunnelHandler(): NodeTunnelHandler | undefined {
+  return getTunnelStore().nodeHandler;
 }

packages/server-utils/src/integrations/serveTunnel.ts

@@ -1,6 +1,11 @@
 import type { ServerTunnelOptions } from '@sentry/core';
 import { defineIntegration } from '@sentry/core';
-import { HTTP_ON_SERVER_REQUEST, serveTunnelIntegration as coreServeTunnelIntegration } from '@sentry/core/server';
+import {
+  _INTERNAL_handleServedNodeTunnelRequest as handleServedNodeTunnelRequest,
+  _INTERNAL_setNodeTunnelHandler as setNodeTunnelHandler,
+  HTTP_ON_SERVER_REQUEST,
+  serveTunnelIntegration as coreServeTunnelIntegration,
+} from '@sentry/core/server';
 import { subscribe } from '../utils/diagnosticsChannel';
 import { instrumentTunnelServer } from '../utils/tunnelServer';
 
@@ -16,6 +21,9 @@ export function instrumentTunnelServers(): void {
   }
 
   isSubscribed = true;
+  // Core's HTTP server instrumentation answers tunnel requests through it, without bundling it for apps that have no
+  // tunnel.
+  setNodeTunnelHandler(handleServedNodeTunnelRequest);
   subscribe(HTTP_ON_SERVER_REQUEST, instrumentTunnelServer);
 }
 

packages/server-utils/src/utils/tunnelServer.ts

@@ -1,7 +1,7 @@
 import { debug } from '@sentry/core';
 import {
   _INTERNAL_handleServedNodeTunnelRequest as handleServedNodeTunnelRequest,
-  _INTERNAL_httpServerAnswersTunnel as httpServerAnswersTunnel,
+  _INTERNAL_httpServerHandlesTunnel as httpServerHandlesTunnel,
 } from '@sentry/core/server';
 import { DEBUG_BUILD } from '../debug-build';
 
@@ -20,7 +20,7 @@ const tunnelServers = new WeakSet<TunnelServer>();
 export function instrumentTunnelServer(message: unknown): void {
   try {
     const server = (message as { server?: TunnelServer } | undefined)?.server;
-    if (!server || tunnelServers.has(server) || httpServerAnswersTunnel()) {
+    if (!server || tunnelServers.has(server) || httpServerHandlesTunnel()) {
       return;
     }