ref(core): Deprecate the released handleTunnelRequest form and reword the serveTunnelIntegration docs

.oxlintrc.base.json

@@ -61,10 +61,14 @@
     "typescript/no-duplicate-type-constituents": "off",
     // @types/node 20 still marks `channel.subscribe()` and `channel.unsubscribe()` as deprecated,
     // but Node revoked this deprecation (DEP0163) in v22.20.0 and v24.8.0.
+    // `handleTunnelRequest` has only one deprecated overload, but the rule flags every re-export of it.
     "typescript/no-deprecated": [
       "error",
       {
-        "allow": [{ "from": "package", "package": "diagnostics_channel", "name": ["subscribe", "unsubscribe"] }]
+        "allow": [
+          { "from": "package", "package": "diagnostics_channel", "name": ["subscribe", "unsubscribe"] },
+          "handleTunnelRequest"
+        ]
       }
     ]
   },

packages/core/src/integrations/serveTunnel.ts

@@ -16,19 +16,29 @@ const _serveTunnelIntegration = ((options: ServerTunnelOptions = {}) => {
 }) 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.
+ * Lets your server forward the events of a browser SDK set up with `tunnel: true` to Sentry.
  *
- * 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.
+ * With this integration on the server and `tunnel: true` in the browser `init`, the browser sends its events to your
+ * own server instead of Sentry, where ad-blockers can't drop them, and your server forwards them to Sentry.
+ *
+ * Meta-framework SDKs (e.g. Next.js, Nuxt or SvelteKit) answer the tunnel requests for you. On a standalone server
+ * (e.g. Express or Fastify), also call `handleTunnelRequestIfMatched` in your request handling.
+ *
+ * By default only envelopes for the server's own DSN are forwarded.
  *
  * @example
  * ```js
+ * // Server
  * Sentry.init({
  *   dsn: '__DSN__',
  *   integrations: [Sentry.serveTunnelIntegration()],
  * });
+ *
+ * // Browser
+ * Sentry.init({
+ *   dsn: '__DSN__',
+ *   tunnel: true,
+ * });
  * ```
  */
 export const serveTunnelIntegration = defineIntegration(_serveTunnelIntegration);

packages/core/src/utils/tunnelForward.ts

@@ -62,7 +62,9 @@ export function handleTunnelRequest(
   options?: TunnelForwardOptions,
 ): Promise<void>;
 /**
- * The released form, kept until v12. Its `request` option is deprecated: pass the request as the first argument.
+ * The released form, kept until v12.
+ *
+ * @deprecated Pass the request as the first argument instead: `handleTunnelRequest(request, options)`.
  */
 export function handleTunnelRequest(options: HandleTunnelRequestOptions): Promise<Response>;
 export function handleTunnelRequest(