feat(core,node-core): Consolidate bun and node types with ServerRuntimeOptions (#18734)

closes #18437
closes
[JS-1272](https://linear.app/getsentry/issue/JS-1272/extend-bunoptions-with-nodeoptions)

This adds a new type `ServerRuntimeOptions` inside `@sentry/core`, a
type which can be used for all SDKs without OpenTelemetry suppport. In
case OpenTelemetry support is needed `OpenTelemetryServerRuntimeOptions`
are exported from `@sentry/node-core`, which extends
`ServerRuntimeOptions` with the options which are needed to support
OTel.

For now we don't have a nice testing strategy for Bun yet, and I didn't
want to copy paste all Node integration/e2e tests just for this, I'm
still up for suggestions.

Author: JPeer264

packages/bun/src/types.ts

@@ -1,54 +1,12 @@
-import type { BaseTransportOptions, ClientOptions, Options, TracePropagationTargets } from '@sentry/core';
+import type { BaseTransportOptions, ClientOptions, Options } from '@sentry/core';
+import type { OpenTelemetryServerRuntimeOptions } from '@sentry/node-core';
 
-export interface BaseBunOptions {
-  /**
-   * List of strings/regex controlling to which outgoing requests
-   * the SDK will attach tracing headers.
-   *
-   * By default the SDK will attach those headers to all outgoing
-   * requests. If this option is provided, the SDK will match the
-   * request URL of outgoing requests against the items in this
-   * array, and only attach tracing headers if a match was found.
-   *
-   * @example
-   * ```js
-   * Sentry.init({
-   *   tracePropagationTargets: ['api.site.com'],
-   * });
-   * ```
-   */
-  tracePropagationTargets?: TracePropagationTargets;
-
-  /** Sets an optional server name (device name) */
-  serverName?: string;
-
-  /**
-   * If you use Spotlight by Sentry during development, use
-   * this option to forward captured Sentry events to Spotlight.
-   *
-   * Either set it to true, or provide a specific Spotlight Sidecar URL.
-   *
-   * More details: https://spotlightjs.com/
-   *
-   * IMPORTANT: Only set this option to `true` while developing, not in production!
-   */
-  spotlight?: boolean | string;
-
-  /**
-   * If this is set to true, the SDK will not set up OpenTelemetry automatically.
-   * In this case, you _have_ to ensure to set it up correctly yourself, including:
-   * * The `SentrySpanProcessor`
-   * * The `SentryPropagator`
-   * * The `SentryContextManager`
-   * * The `SentrySampler`
-   *
-   * If you are registering your own OpenTelemetry Loader Hooks (or `import-in-the-middle` hooks), it is also recommended to set the `registerEsmLoaderHooks` option to false.
-   */
-  skipOpenTelemetrySetup?: boolean;
-
-  /** Callback that is executed when a fatal global error occurs. */
-  onFatalError?(this: void, error: Error): void;
-}
+/**
+ * Base options for the Sentry Bun SDK.
+ * Extends the common WinterTC options with OpenTelemetry support shared with Node.js and other server-side SDKs.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface BaseBunOptions extends OpenTelemetryServerRuntimeOptions {}
 
 /**
  * Configuration options for the Sentry Bun SDK

packages/core/src/index.ts

@@ -393,7 +393,7 @@ export type { Extra, Extras } from './types-hoist/extra';
 export type { Integration, IntegrationFn } from './types-hoist/integration';
 export type { Mechanism } from './types-hoist/mechanism';
 export type { ExtractedNodeRequestData, HttpHeaderValue, Primitive, WorkerLocation } from './types-hoist/misc';
-export type { ClientOptions, CoreOptions as Options } from './types-hoist/options';
+export type { ClientOptions, CoreOptions as Options, ServerRuntimeOptions } from './types-hoist/options';
 export type { Package } from './types-hoist/package';
 export type { PolymorphicEvent, PolymorphicRequest } from './types-hoist/polymorphics';
 export type {

packages/core/src/types-hoist/options.ts

@@ -11,6 +11,95 @@ import type { StackLineParser, StackParser } from './stacktrace';
 import type { TracePropagationTargets } from './tracing';
 import type { BaseTransportOptions, Transport } from './transport';
 
+/**
+ * Base options for WinterTC-compatible server-side JavaScript runtimes.
+ * This interface contains common configuration options shared between
+ * SDKs.
+ */
+export interface ServerRuntimeOptions {
+  /**
+   * List of strings/regex controlling to which outgoing requests
+   * the SDK will attach tracing headers.
+   *
+   * By default the SDK will attach those headers to all outgoing
+   * requests. If this option is provided, the SDK will match the
+   * request URL of outgoing requests against the items in this
+   * array, and only attach tracing headers if a match was found.
+   *
+   * @example
+   * ```js
+   * Sentry.init({
+   *   tracePropagationTargets: ['api.site.com'],
+   * });
+   * ```
+   */
+  tracePropagationTargets?: TracePropagationTargets;
+
+  /**
+   * Sets an optional server name (device name).
+   *
+   * This is useful for identifying which server or instance is sending events.
+   */
+  serverName?: string;
+
+  /**
+   * If you use Spotlight by Sentry during development, use
+   * this option to forward captured Sentry events to Spotlight.
+   *
+   * Either set it to true, or provide a specific Spotlight Sidecar URL.
+   *
+   * More details: https://spotlightjs.com/
+   *
+   * IMPORTANT: Only set this option to `true` while developing, not in production!
+   */
+  spotlight?: boolean | string;
+
+  /**
+   * If set to `false`, the SDK will not automatically detect the `serverName`.
+   *
+   * This is useful if you are using the SDK in a CLI app or Electron where the
+   * hostname might be considered PII.
+   *
+   * @default true
+   */
+  includeServerName?: boolean;
+
+  /**
+   * By default, the SDK will try to identify problems with your instrumentation setup and warn you about it.
+   * If you want to disable these warnings, set this to `true`.
+   */
+  disableInstrumentationWarnings?: boolean;
+
+  /**
+   * Controls how many milliseconds to wait before shutting down. The default is 2 seconds. Setting this too low can cause
+   * problems for sending events from command line applications. Setting it too
+   * high can cause the application to block for users with network connectivity
+   * problems.
+   */
+  shutdownTimeout?: number;
+
+  /**
+   * Configures in which interval client reports will be flushed. Defaults to `60_000` (milliseconds).
+   */
+  clientReportFlushInterval?: number;
+
+  /**
+   * The max. duration in seconds that the SDK will wait for parent spans to be finished before discarding a span.
+   * The SDK will automatically clean up spans that have no finished parent after this duration.
+   * This is necessary to prevent memory leaks in case of parent spans that are never finished or otherwise dropped/missing.
+   * However, if you have very long-running spans in your application, a shorter duration might cause spans to be discarded too early.
+   * In this case, you can increase this duration to a value that fits your expected data.
+   *
+   * Defaults to 300 seconds (5 minutes).
+   */
+  maxSpanWaitDuration?: number;
+
+  /**
+   * Callback that is executed when a fatal global error occurs.
+   */
+  onFatalError?(this: void, error: Error): void;
+}
+
 /**
  * A filter object for ignoring spans.
  * At least one of the properties (`op` or `name`) must be set.

packages/node-core/src/index.ts

@@ -50,7 +50,7 @@ export { NodeClient } from './sdk/client';
 export { cron } from './cron';
 export { NODE_VERSION } from './nodeVersion';
 
-export type { NodeOptions } from './types';
+export type { NodeOptions, OpenTelemetryServerRuntimeOptions } from './types';
 
 export {
   // This needs exporting so the NodeClient can be used without calling init

packages/node-core/src/types.ts

@@ -1,28 +1,43 @@
 import type { Span as WriteableSpan } from '@opentelemetry/api';
 import type { Instrumentation } from '@opentelemetry/instrumentation';
 import type { ReadableSpan, SpanProcessor } from '@opentelemetry/sdk-trace-base';
-import type { ClientOptions, Options, SamplingContext, Scope, Span, TracePropagationTargets } from '@sentry/core';
+import type { ClientOptions, Options, SamplingContext, Scope, ServerRuntimeOptions, Span } from '@sentry/core';
 import type { NodeTransportOptions } from './transports';
 
-export interface BaseNodeOptions {
+/**
+ * Base options for WinterTC-compatible server-side JavaScript runtimes with OpenTelemetry support.
+ * This interface extends the base ServerRuntimeOptions from @sentry/core with OpenTelemetry-specific configuration options.
+ * Used by Node.js, Bun, and other WinterTC-compliant runtime SDKs that support OpenTelemetry instrumentation.
+ */
+export interface OpenTelemetryServerRuntimeOptions extends ServerRuntimeOptions {
   /**
-   * List of strings/regex controlling to which outgoing requests
-   * the SDK will attach tracing headers.
-   *
-   * By default the SDK will attach those headers to all outgoing
-   * requests. If this option is provided, the SDK will match the
-   * request URL of outgoing requests against the items in this
-   * array, and only attach tracing headers if a match was found.
+   * If this is set to true, the SDK will not set up OpenTelemetry automatically.
+   * In this case, you _have_ to ensure to set it up correctly yourself, including:
+   * * The `SentrySpanProcessor`
+   * * The `SentryPropagator`
+   * * The `SentryContextManager`
+   * * The `SentrySampler`
+   */
+  skipOpenTelemetrySetup?: boolean;
+
+  /**
+   * Provide an array of OpenTelemetry Instrumentations that should be registered.
    *
-   * @example
-   * ```js
-   * Sentry.init({
-   *   tracePropagationTargets: ['api.site.com'],
-   * });
-   * ```
+   * Use this option if you want to register OpenTelemetry instrumentation that the Sentry SDK does not yet have support for.
    */
-  tracePropagationTargets?: TracePropagationTargets;
+  openTelemetryInstrumentations?: Instrumentation[];
+
+  /**
+   * Provide an array of additional OpenTelemetry SpanProcessors that should be registered.
+   */
+  openTelemetrySpanProcessors?: SpanProcessor[];
+}
 
+/**
+ * Base options for the Sentry Node SDK.
+ * Extends the common WinterTC options with OpenTelemetry support shared with Bun and other server-side SDKs.
+ */
+export interface BaseNodeOptions extends OpenTelemetryServerRuntimeOptions {
   /**
    * Sets profiling sample rate when @sentry/profiling-node is installed
    *
@@ -61,61 +76,13 @@ export interface BaseNodeOptions {
    */
   profileLifecycle?: 'manual' | 'trace';
 
-  /**
-   * If set to `false`, the SDK will not automatically detect the `serverName`.
-   *
-   * This is useful if you are using the SDK in a CLI app or Electron where the
-   * hostname might be considered PII.
-   *
-   * @default true
-   */
-  includeServerName?: boolean;
-
-  /** Sets an optional server name (device name) */
-  serverName?: string;
-
   /**
    * Include local variables with stack traces.
    *
    * Requires the `LocalVariables` integration.
    */
   includeLocalVariables?: boolean;
 
-  /**
-   * If you use Spotlight by Sentry during development, use
-   * this option to forward captured Sentry events to Spotlight.
-   *
-   * Either set it to true, or provide a specific Spotlight Sidecar URL.
-   *
-   * More details: https://spotlightjs.com/
-   *
-   * IMPORTANT: Only set this option to `true` while developing, not in production!
-   */
-  spotlight?: boolean | string;
-
-  /**
-   * Provide an array of OpenTelemetry Instrumentations that should be registered.
-   *
-   * Use this option if you want to register OpenTelemetry instrumentation that the Sentry SDK does not yet have support for.
-   */
-  openTelemetryInstrumentations?: Instrumentation[];
-
-  /**
-   * Provide an array of additional OpenTelemetry SpanProcessors that should be registered.
-   */
-  openTelemetrySpanProcessors?: SpanProcessor[];
-
-  /**
-   * The max. duration in seconds that the SDK will wait for parent spans to be finished before discarding a span.
-   * The SDK will automatically clean up spans that have no finished parent after this duration.
-   * This is necessary to prevent memory leaks in case of parent spans that are never finished or otherwise dropped/missing.
-   * However, if you have very long-running spans in your application, a shorter duration might cause spans to be discarded too early.
-   * In this case, you can increase this duration to a value that fits your expected data.
-   *
-   * Defaults to 300 seconds (5 minutes).
-   */
-  maxSpanWaitDuration?: number;
-
   /**
    * Whether to register ESM loader hooks to automatically instrument libraries.
    * This is necessary to auto instrument libraries that are loaded via ESM imports, but it can cause issues
@@ -125,28 +92,6 @@ export interface BaseNodeOptions {
    * Defaults to `true`.
    */
   registerEsmLoaderHooks?: boolean;
-
-  /**
-   * Configures in which interval client reports will be flushed. Defaults to `60_000` (milliseconds).
-   */
-  clientReportFlushInterval?: number;
-
-  /**
-   * By default, the SDK will try to identify problems with your instrumentation setup and warn you about it.
-   * If you want to disable these warnings, set this to `true`.
-   */
-  disableInstrumentationWarnings?: boolean;
-
-  /**
-   * Controls how many milliseconds to wait before shutting down. The default is 2 seconds. Setting this too low can cause
-   * problems for sending events from command line applications. Setting it too
-   * high can cause the application to block for users with network connectivity
-   * problems.
-   */
-  shutdownTimeout?: number;
-
-  /** Callback that is executed when a fatal global error occurs. */
-  onFatalError?(this: void, error: Error): void;
 }
 
 /**