ref(core): Add shared ServerRequestOptions type across runtimes

Node, Deno, Bun and Cloudflare each have their own options for incoming
HTTP requests, and the option sets drift. Bun.serve takes only
`maxRequestBodySize`, and Cloudflare has no span options. When we add
an option to one runtime, nothing reminds us to add it to the others.

`ServerRequestOptions` in `@sentry/core/server` lists the options that
every incoming request integration should support. Each runtime options
type is checked against it with `CheckServerRequestOptions`. The check
lists the options that the runtime does not support yet, with a comment
that says why. It fails to compile when a shared option is neither
declared nor listed, when a listed option is declared, or when a
callback written for the shared type does not fit the runtime option.

The runtime types do not extend the shared type. With `extends`, a new
shared option would appear in every runtime type, supported or not, and
nothing would fail to compile. Each runtime keeps its own declarations
and docs.

Node and Bun now type the request in `ignoreRequestBody` as
`RequestOptions & HttpIncomingMessage`. The value was always an
`IncomingMessage`. Callbacks typed with `RequestOptions` still compile.
The `RequestOptions` part is deprecated, for removal in v12.

A new BUGBOT rule flags an incoming request option that applies to more
than one runtime but is not in the shared type.

There is no runtime behavior change.

Fixes JS-3968
Fixes #25570

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: isaacs

.cursor/BUGBOT.md

@@ -78,6 +78,7 @@ Keep reviews high-signal. Prefer actionable, high-confidence findings over specu
   - What to do instead: Use an existing reference to the scope or client. For example, this is possible in most `Integration` hooks.
 - Flag hard-coded attribute names and span ops (e.g. `'sentry.origin'`, `'sentry.op'`, `'http.request.method'`, `'db.system.name'`) when `@sentry/conventions` exports a constant for them. Use the constant from `@sentry/conventions/attributes` (e.g. `SENTRY_ORIGIN`, `SENTRY_OP`) or `@sentry/conventions/op` instead. Do not flag values that have no constant in `@sentry/conventions`.
 - Flag unnecessary `span.setAttribute(s)` calls: If data is already available at span start, it must be set via the `attributes` option of `startSpan`, `startSpanManual`, `startInactiveSpan` or `startIdleSpan` calls. This ensures that as much context as possible is available when `tracesSampler` or `ignoreSpans` SDK options are applied. If a `span.setAttribute(s)` call happens at a later time than right after span start and the attribute value can only be computed at that time, do not flag it.
+- Flag a new option on an integration for incoming HTTP requests that is not in `ServerRequestOptions` (`packages/core/src/integrations/http/server-request-options.ts`), when it applies to more than one runtime. These integrations are Node `httpIntegration`, Deno `denoHttpIntegration` and `denoServeIntegration`, Bun `bunHttpServerIntegration` and `bunServerIntegration`, and Cloudflare `httpServerIntegration`. Add the option to `ServerRequestOptions`, then support it in each runtime or list it as unsupported in that runtime's `CheckServerRequestOptions` check. Also flag a runtime option that matches a shared option in purpose but has a different name or meaning.
 
 ### Code quality
 

packages/bun/src/integrations/bunHttpServer.ts

@@ -3,7 +3,12 @@ import * as http from 'node:http';
 import * as https from 'node:https';
 import type { IntegrationFn, Span } from '@sentry/core';
 import { defineIntegration } from '@sentry/core';
-import type { HttpIncomingMessage, HttpServerResponse } from '@sentry/core/server';
+import type {
+  AssertTrue,
+  CheckServerRequestOptions,
+  HttpIncomingMessage,
+  HttpServerResponse,
+} from '@sentry/core/server';
 import { getHttpServerSubscriptions, HTTP_ON_SERVER_REQUEST } from '@sentry/core/server';
 
 const INTEGRATION_NAME = 'BunHttpServer' as const;
@@ -37,8 +42,12 @@ interface BunHttpServerOptions {
 
   /**
    * Do not capture the request body for incoming HTTP requests to URLs where the given callback returns `true`.
+   *
+   * The `request` parameter is the incoming `node:http` `IncomingMessage`. The `RequestOptions` part of the type is
+   * deprecated and will be removed in v12. Its fields that `IncomingMessage` does not have (such as `path` or
+   * `hostname`) are always `undefined`.
    */
-  ignoreRequestBody?: (url: string, request: http.RequestOptions) => boolean;
+  ignoreRequestBody?: (url: string, request: http.RequestOptions & HttpIncomingMessage) => boolean;
 
   /**
    * Controls the maximum size of incoming HTTP request bodies attached to events.
@@ -73,6 +82,13 @@ interface BunHttpServerOptions {
   onSpanEnd?: (span: Span, request: HttpIncomingMessage, response: HttpServerResponse) => void;
 }
 
+// Checks these options against the shared `ServerRequestOptions`. A new
+// shared field fails to compile here, until this integration supports
+// it or lists it as unsupported.
+type _ServerRequestOptionsCheck = AssertTrue<
+  CheckServerRequestOptions<BunHttpServerOptions, HttpIncomingMessage, HttpServerResponse>
+>;
+
 let hasPatched = false;
 
 const _bunHttpServerIntegration = ((options: BunHttpServerOptions = {}) => {

packages/bun/src/integrations/bunserver.ts

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 import type { Integration, IntegrationFn, MaxRequestBodySize, SpanAttributes } from '@sentry/core';
 import {
   captureBodyFromWinterCGRequest,
@@ -20,6 +21,7 @@ import {
   filterCollectedUrl,
   filterCollectedUrlQuery,
 } from '@sentry/core';
+import type { AssertTrue, CheckServerRequestOptions } from '@sentry/core/server';
 import { classifyResponseStreaming, getClientIPAddress } from '@sentry/core/server';
 import type { Server, ServeOptions } from 'bun';
 import {
@@ -55,6 +57,26 @@ export type BunServerIntegrationOptions = {
   maxRequestBodySize?: MaxRequestBodySize;
 };
 
+// Checks these options against the shared `ServerRequestOptions`. A new
+// shared field fails to compile here, until this integration supports
+// it or lists it as unsupported.
+type _ServerRequestOptionsCheck = AssertTrue<
+  CheckServerRequestOptions<
+    BunServerIntegrationOptions,
+    Request,
+    Response,
+    // Not supported yet.
+    | 'spans'
+    | 'sessions'
+    | 'sessionFlushingDelayMS'
+    | 'ignoreRequestBody'
+    | 'ignoreIncomingRequests'
+    | 'ignoreStaticAssets'
+    | 'onSpanCreated'
+    | 'onSpanEnd'
+  >
+>;
+
 const _bunServerIntegration = ((options: BunServerIntegrationOptions = {}) => {
   return {
     name: INTEGRATION_NAME,

packages/cloudflare/src/integrations/httpServer.ts

@@ -1,5 +1,6 @@
 import type { Client, IntegrationFn, MaxRequestBodySize } from '@sentry/core';
 import { captureBodyFromWinterCGRequest, defineIntegration, getIsolationScope } from '@sentry/core';
+import type { AssertTrue, CheckServerRequestOptions } from '@sentry/core/server';
 
 const INTEGRATION_NAME = 'HttpServer' as const;
 
@@ -40,6 +41,27 @@ export interface HttpServerIntegrationOptions {
   ignoreRequestBody?: (url: string, request: Request) => boolean;
 }
 
+// Checks these options against the shared `ServerRequestOptions`. A new
+// shared field fails to compile here, until this integration supports
+// it or lists it as unsupported.
+type _ServerRequestOptionsCheck = AssertTrue<
+  CheckServerRequestOptions<
+    HttpServerIntegrationOptions,
+    Request,
+    Response,
+    // Not supported yet.
+    | 'spans'
+    | 'ignoreIncomingRequests'
+    | 'ignoreStaticAssets'
+    | 'onSpanCreated'
+    | 'onSpanEnd'
+    // Not supported. A worker has no long-lived process to run the timer
+    // that flushes session aggregates.
+    | 'sessions'
+    | 'sessionFlushingDelayMS'
+  >
+>;
+
 interface HttpServerIntegrationInstance {
   name: string;
   maxRequestBodySize: MaxRequestBodySize | undefined;

packages/core/src/integrations/http/server-request-options.ts

@@ -0,0 +1,128 @@
+import type { Span } from '../../types/span';
+import type { MaxRequestBodySize } from '../../utils/request';
+
+/**
+ * Options that every integration for incoming HTTP requests should
+ * support, in each runtime.
+ *
+ * `TRequest` and `TResponse` are the request and response types that the
+ * runtime passes to callbacks: `HttpIncomingMessage` and
+ * `HttpServerResponse` for `node:http`, or the web `Request` and
+ * `Response` for `Deno.serve`, `Bun.serve` and Cloudflare.
+ *
+ * Runtime options types do not extend this type. Each one declares its
+ * own fields, with docs for that runtime, and uses
+ * {@link CheckServerRequestOptions} to check them against this type.
+ * Then a new field here fails to compile in each runtime, until the
+ * runtime supports it or lists it as unsupported.
+ */
+export interface ServerRequestOptions<TRequest, TResponse> {
+  /**
+   * Whether to create spans for incoming requests.
+   * Defaults to the client's tracing configuration.
+   */
+  spans?: boolean;
+
+  /**
+   * Whether to create [Sessions](https://docs.sentry.io/product/releases/health/#sessions) for incoming
+   * requests, to track the health and crash-free rate of releases.
+   *
+   * @default `true`
+   */
+  sessions?: boolean;
+
+  /**
+   * Number of milliseconds until sessions are flushed as a session aggregate.
+   *
+   * @default `60000` (60s)
+   */
+  sessionFlushingDelayMS?: number;
+
+  /**
+   * Controls the maximum size of incoming request bodies attached to events.
+   *
+   * @default 'medium'
+   */
+  maxRequestBodySize?: MaxRequestBodySize;
+
+  /**
+   * Do not capture the request body for incoming requests where the given callback returns `true`.
+   *
+   * `url` is the full URL of the request, including the query string.
+   */
+  ignoreRequestBody?: (url: string, request: TRequest) => boolean;
+
+  /**
+   * Do not create spans for incoming requests where the given callback returns `true`.
+   *
+   * `urlPath` is the path of the request, including the query string.
+   */
+  ignoreIncomingRequests?: (urlPath: string, request: TRequest) => boolean;
+
+  /**
+   * Whether to ignore common static asset requests (favicon.ico, robots.txt, etc.)
+   * when creating spans.
+   *
+   * @default `true`
+   */
+  ignoreStaticAssets?: boolean;
+
+  /**
+   * A hook to change the span for an incoming request, after the span is created.
+   */
+  onSpanCreated?: (span: Span, request: TRequest) => void;
+
+  /**
+   * A hook to change the span for an incoming request one last time, before it ends.
+   */
+  onSpanEnd?: (span: Span, request: TRequest, response: TResponse) => void;
+}
+
+/**
+ * `true` when `TOptions` matches {@link ServerRequestOptions}, else a
+ * string that names the problem. Use it with a type that accepts only
+ * `true`, so a mismatch fails to compile:
+ *
+ * ```ts
+ * type _Check = AssertTrue<CheckServerRequestOptions<MyOptions, Request, Response, 'sessions'>>;
+ * ```
+ *
+ * `TUnsupported` lists the fields that the runtime does not support.
+ *
+ * The check fails when:
+ * - `TOptions` does not declare a field, and `TUnsupported` does not
+ *   list it.
+ * - `TUnsupported` lists a field that `TOptions` declares.
+ * - A callback written for the shared type does not fit the field in
+ *   `TOptions`.
+ */
+export type CheckServerRequestOptions<
+  TOptions,
+  TRequest,
+  TResponse,
+  TUnsupported extends keyof ServerRequestOptions<TRequest, TResponse> = never,
+> = [MissingFields<TOptions, TRequest, TResponse, TUnsupported>] extends [never]
+  ? [Extract<TUnsupported, keyof TOptions>] extends [never]
+    ? SupportedFields<
+        ServerRequestOptions<TRequest, TResponse>,
+        TRequest,
+        TResponse,
+        TUnsupported
+      > extends SupportedFields<TOptions, TRequest, TResponse, TUnsupported>
+      ? true
+      : 'A field type does not match ServerRequestOptions'
+    : `Listed as unsupported, but declared: ${Extract<TUnsupported, keyof TOptions> & string}`
+  : `Missing field: ${MissingFields<TOptions, TRequest, TResponse, TUnsupported> & string}`;
+
+type MissingFields<TOptions, TRequest, TResponse, TUnsupported> = Exclude<
+  keyof ServerRequestOptions<TRequest, TResponse>,
+  TUnsupported | keyof TOptions
+>;
+
+type SupportedFields<T, TRequest, TResponse, TUnsupported> = Pick<
+  T,
+  Extract<keyof T, Exclude<keyof ServerRequestOptions<TRequest, TResponse>, TUnsupported>>
+>;
+
+/** Accepts only `true`. Use it with {@link CheckServerRequestOptions}. */
+export type AssertTrue<T extends true> = T;

packages/core/src/server.ts

@@ -43,6 +43,11 @@ export type {
   HttpServerResponse,
   HttpModuleExport,
 } from './integrations/http/types';
+export type {
+  AssertTrue,
+  CheckServerRequestOptions,
+  ServerRequestOptions,
+} from './integrations/http/server-request-options';
 export { createFetchIntegration } from './integrations/fetch';
 export type { FetchIntegrationOptions } from './integrations/fetch';
 export { classifyResponseStreaming } from './utils/responseStreaming';

packages/deno/src/integrations/deno-serve.ts

@@ -1,5 +1,6 @@
 import type { Event, IntegrationFn, MaxRequestBodySize, Span } from '@sentry/core';
 import { debug, defineIntegration } from '@sentry/core';
+import type { AssertTrue, CheckServerRequestOptions } from '@sentry/core/server';
 import { DEFAULT_IGNORE_STATUS_CODES, processHttpServerTransactionEvent } from '@sentry/core/server';
 import type { RequestHandlerWrapperOptions } from '../wrap-deno-request-handler';
 import { wrapDenoRequestHandler } from '../wrap-deno-request-handler';
@@ -99,6 +100,11 @@ export type DenoServeIntegrationOptions = {
   ignoreStatusCodes?: (number | [number, number])[];
 };
 
+// Checks these options against the shared `ServerRequestOptions`. A new
+// shared field fails to compile here, until this integration supports
+// it or lists it as unsupported.
+type _ServerRequestOptionsCheck = AssertTrue<CheckServerRequestOptions<DenoServeIntegrationOptions, Request, Response>>;
+
 export type ServeParams =
   // [(Request) => Response]
   | [Deno.ServeHandler<Deno.NetAddr>]

packages/deno/src/integrations/http.ts

@@ -3,7 +3,13 @@ import { errorMonitor } from 'node:events';
 import type { RequestOptions } from 'node:http';
 import type { Event, Integration, IntegrationFn, Span } from '@sentry/core';
 import { defineIntegration } from '@sentry/core';
-import type { HttpClientRequest, HttpIncomingMessage, HttpServerResponse } from '@sentry/core/server';
+import type {
+  AssertTrue,
+  CheckServerRequestOptions,
+  HttpClientRequest,
+  HttpIncomingMessage,
+  HttpServerResponse,
+} from '@sentry/core/server';
 import {
   DEFAULT_IGNORE_STATUS_CODES,
   getHttpClientSubscriptions,
@@ -151,6 +157,13 @@ export interface DenoHttpIntegrationOptions {
   onSpanEnd?: (span: Span, request: HttpIncomingMessage, response: HttpServerResponse) => void;
 }
 
+// Checks these options against the shared `ServerRequestOptions`. A new
+// shared field fails to compile here, until this integration supports
+// it or lists it as unsupported.
+type _ServerRequestOptionsCheck = AssertTrue<
+  CheckServerRequestOptions<DenoHttpIntegrationOptions, HttpIncomingMessage, HttpServerResponse>
+>;
+
 const _denoHttpIntegration = ((options: DenoHttpIntegrationOptions = {}) => {
   const breadcrumbs = options.breadcrumbs ?? true;
   const tracePropagation = options.tracePropagation ?? true;

packages/node/src/integrations/http/httpServerIntegration.ts

@@ -45,9 +45,11 @@ export interface HttpServerIntegrationOptions {
    * This can be useful for long running requests where the body is not needed and we want to avoid capturing it.
    *
    * @param url Contains the entire URL, including query string (if any), protocol, host, etc. of the incoming request.
-   * @param request Contains the {@type RequestOptions} object used to make the incoming request.
+   * @param request The incoming request, a `node:http` `IncomingMessage`. Use `request.url`, `request.method`,
+   * `request.headers`, etc. The `RequestOptions` part of the type is deprecated and will be removed in v12. Its
+   * fields that `IncomingMessage` does not have (such as `path` or `hostname`) are always `undefined`.
    */
-  ignoreRequestBody?: (url: string, request: RequestOptions) => boolean;
+  ignoreRequestBody?: (url: string, request: RequestOptions & HttpIncomingMessage) => boolean;
 
   /**
    * Controls the maximum size of incoming HTTP request bodies attached to events.
@@ -84,13 +86,7 @@ const _httpServerIntegration = ((options: HttpServerIntegrationOptions = {}) =>
     // core subscription helper. Explicitly opt out so the helper does not
     // double-create spans when the client has tracing enabled.
     spans: false as const,
-    // Cast: core uses HttpIncomingMessage; node consumers pass
-    // RequestOptions-typed callbacks.
-    // The two are structurally compatible for the fields the callback reads
-    // (url, method, headers).
-    ignoreRequestBody: options.ignoreRequestBody as
-      | ((url: string, request: HttpIncomingMessage) => boolean)
-      | undefined,
+    ignoreRequestBody: options.ignoreRequestBody,
 
     /**
      * Hook called by core's `instrumentServer` to wrap the upstream

packages/node/src/integrations/http/index.ts

@@ -8,6 +8,12 @@ import {
   hasSpanStreamingEnabled,
   stripDataUrlContent,
 } from '@sentry/core';
+import type {
+  AssertTrue,
+  CheckServerRequestOptions,
+  HttpIncomingMessage,
+  HttpServerResponse,
+} from '@sentry/core/server';
 import { getRequestUrlFromClientRequest } from '@sentry/core/server';
 import type { NodeClient } from '../../sdk/client';
 import type { HttpServerIntegrationOptions } from './httpServerIntegration';
@@ -83,6 +89,19 @@ interface HttpOptions extends HttpServerIntegrationOptions, HttpServerSpansInteg
   outgoingRequestApplyCustomAttributes?: OutgoingHttpRequestInstrumentationOptions['outgoingRequestApplyCustomAttributes'];
 }
 
+// Checks these options against the shared `ServerRequestOptions`. A new
+// shared field fails to compile here, until this integration supports
+// it or lists it as unsupported.
+type _ServerRequestOptionsCheck = AssertTrue<
+  CheckServerRequestOptions<
+    HttpOptions,
+    HttpIncomingMessage,
+    HttpServerResponse,
+    // Not supported yet.
+    'onSpanEnd'
+  >
+>;
+
 /**
  * The http integration instruments Node's internal http and https modules.
  * It creates breadcrumbs and spans for outgoing HTTP requests which will be attached to the currently active span.