react-on-rails-pro-node-renderer 16.7.0-rc.2 → 16.7.0-rc.3

package/lib/integrations/api.d.ts

@@ -24,6 +24,6 @@
  */
 export { default as log } from '../shared/log.js';
 export { addErrorNotifier, addMessageNotifier, addNotifier, error, message, Notifier, ErrorNotifier, MessageNotifier, } from '../shared/errorReporter.js';
-export { setupTracing, TracingContext, TracingIntegrationOptions, UnitOfWorkOptions, } from '../shared/tracing.js';
-export { configureFastify, FastifyConfigFunction } from '../worker.js';
+export { setupTracing, setupSubSpan, subSpan, TracingContext, TracingIntegrationOptions, UnitOfWorkOptions, SubSpanOptions, SubSpanFn, SubSpanController, } from '../shared/tracing.js';
+export { configureFastify, FastifyConfigFunction } from '../worker/fastifyConfig.js';
 //# sourceMappingURL=api.d.ts.map

package/lib/integrations/api.js

@@ -27,7 +27,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.configureFastify = exports.setupTracing = exports.message = exports.error = exports.addNotifier = exports.addMessageNotifier = exports.addErrorNotifier = exports.log = void 0;
+exports.configureFastify = exports.subSpan = exports.setupSubSpan = exports.setupTracing = exports.message = exports.error = exports.addNotifier = exports.addMessageNotifier = exports.addErrorNotifier = exports.log = void 0;
 var log_js_1 = require("../shared/log.js");
 Object.defineProperty(exports, "log", { enumerable: true, get: function () { return __importDefault(log_js_1).default; } });
 var errorReporter_js_1 = require("../shared/errorReporter.js");
@@ -38,6 +38,8 @@ Object.defineProperty(exports, "error", { enumerable: true, get: function () { r
 Object.defineProperty(exports, "message", { enumerable: true, get: function () { return errorReporter_js_1.message; } });
 var tracing_js_1 = require("../shared/tracing.js");
 Object.defineProperty(exports, "setupTracing", { enumerable: true, get: function () { return tracing_js_1.setupTracing; } });
-var worker_js_1 = require("../worker.js");
-Object.defineProperty(exports, "configureFastify", { enumerable: true, get: function () { return worker_js_1.configureFastify; } });
+Object.defineProperty(exports, "setupSubSpan", { enumerable: true, get: function () { return tracing_js_1.setupSubSpan; } });
+Object.defineProperty(exports, "subSpan", { enumerable: true, get: function () { return tracing_js_1.subSpan; } });
+var fastifyConfig_js_1 = require("../worker/fastifyConfig.js");
+Object.defineProperty(exports, "configureFastify", { enumerable: true, get: function () { return fastifyConfig_js_1.configureFastify; } });
 //# sourceMappingURL=api.js.map

package/lib/integrations/opentelemetry.d.ts

@@ -0,0 +1,34 @@
+import type { Attributes } from '@opentelemetry/api';
+import type { SpanExporter, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+declare module '../shared/tracing.js' {
+    interface UnitOfWorkOptions {
+        opentelemetry?: {
+            name: string;
+            attributes?: Attributes;
+        };
+    }
+}
+export interface OpenTelemetryInitOptions {
+    /** Service name reported in traces. Defaults to "react-on-rails-pro-node-renderer".
+     *  `OTEL_SERVICE_NAME` env var takes precedence over this value. If neither is
+     *  set, `resourceAttributes["service.name"]` or `OTEL_RESOURCE_ATTRIBUTES`
+     *  can override the default service name. */
+    serviceName?: string;
+    /** Register HTTP + Fastify auto-instrumentation. Default: false.
+     *  OpenTelemetry module patches are process-global and cannot be rolled back;
+     *  if later init steps fail, patched modules remain installed with a no-op tracer. */
+    fastify?: boolean;
+    /** Wrap SSR work in spans via setupTracing + setupSubSpan. Default: false. */
+    tracing?: boolean;
+    /** Override the default OTLP HTTP exporter. */
+    exporter?: SpanExporter;
+    /** Override the default span processor.
+     *  Default: BatchSpanProcessor in production, SimpleSpanProcessor otherwise. */
+    spanProcessor?: SpanProcessor;
+    /** Additional resource attributes merged into the default resource. */
+    resourceAttributes?: Record<string, string>;
+    /** Maximum time to wait for provider.shutdown() during Fastify onClose. Default: 5000ms. */
+    shutdownTimeoutMs?: number;
+}
+export declare function init(opts?: OpenTelemetryInitOptions): void;
+//# sourceMappingURL=opentelemetry.d.ts.map

package/lib/integrations/opentelemetry.js

@@ -0,0 +1,305 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+/* eslint-disable no-restricted-imports --
+ * This integration needs internal worker/shared modules that the public
+ * api.ts does not yet re-export (tracing adapter slots, OTel global state,
+ * fastify config + worker shutdown hook registration). Tracked in #3419
+ * — once api.ts surfaces these, remove this disable. */
+const tracing_js_1 = require("../shared/tracing.js");
+const opentelemetryState_js_1 = require("../shared/opentelemetryState.js");
+const fastifyConfig_js_1 = require("../worker/fastifyConfig.js");
+const shutdownHooks_js_1 = require("../worker/shutdownHooks.js");
+/* eslint-enable no-restricted-imports */
+const api_js_1 = require("./api.js");
+const DEFAULT_SERVICE_NAME = 'react-on-rails-pro-node-renderer';
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5000;
+// Leave 1s of headroom under the worker's hard cap so the shutdown hook can
+// resolve cleanly even when provider.shutdown() runs right at its limit.
+const MAX_SHUTDOWN_TIMEOUT_MS = shutdownHooks_js_1.WORKER_SHUTDOWN_HOOKS_TIMEOUT_MS - 1000;
+function isProduction() {
+    return process.env.NODE_ENV === 'production' || process.env.RAILS_ENV === 'production';
+}
+function resolveConfiguredServiceName(opts) {
+    return process.env.OTEL_SERVICE_NAME ?? opts.serviceName;
+}
+function resolveShutdownTimeoutMs(opts) {
+    const requested = opts.shutdownTimeoutMs;
+    if (requested === undefined) {
+        return DEFAULT_SHUTDOWN_TIMEOUT_MS;
+    }
+    if (!Number.isFinite(requested) || requested <= 0) {
+        return DEFAULT_SHUTDOWN_TIMEOUT_MS;
+    }
+    if (requested > MAX_SHUTDOWN_TIMEOUT_MS) {
+        api_js_1.log.warn('[OpenTelemetry] shutdownTimeoutMs=%dms exceeds worker shutdown hook cap (%dms); capping to %dms so the hook can resolve before the worker is forcibly destroyed.', requested, shutdownHooks_js_1.WORKER_SHUTDOWN_HOOKS_TIMEOUT_MS, MAX_SHUTDOWN_TIMEOUT_MS);
+        return MAX_SHUTDOWN_TIMEOUT_MS;
+    }
+    return requested;
+}
+function parseResourceAttributes(value) {
+    if (!value)
+        return {};
+    // OTel resource attributes are comma-separated. Literal commas in values must
+    // be percent-encoded by callers; unencoded commas split the value.
+    const attributes = {};
+    for (const pair of value.split(',')) {
+        const [rawKey, ...rawValueParts] = pair.split('=');
+        const key = rawKey?.trim();
+        if (key && rawValueParts.length > 0) {
+            const rawValue = rawValueParts.join('=').trim().replace(/^"|"$/g, '');
+            try {
+                attributes[key] = decodeURIComponent(rawValue);
+            }
+            catch {
+                // Keep init resilient when callers provide malformed percent-encoding.
+                attributes[key] = rawValue;
+            }
+        }
+    }
+    return attributes;
+}
+function configureOpenTelemetryDiagnostics(otelApi) {
+    otelApi.diag.setLogger({
+        error: (diagnosticMessage, ...args) => api_js_1.log.error({ otel: true, level: 'error', args }, diagnosticMessage),
+        warn: (diagnosticMessage, ...args) => api_js_1.log.warn({ otel: true, level: 'warn', args }, diagnosticMessage),
+        // DiagLogLevel.WARN below suppresses lower-severity diagnostics before
+        // these callbacks run. Keep no-op methods to satisfy the OTel logger API.
+        info: () => undefined,
+        debug: () => undefined,
+        verbose: () => undefined,
+    }, otelApi.DiagLogLevel.WARN);
+}
+function disableOpenTelemetryGlobals(otelApi) {
+    otelApi.trace.disable();
+    otelApi.context.disable();
+    otelApi.propagation.disable();
+    otelApi.diag.disable();
+}
+function resetInstalledTracingAdapters(installedAdapters) {
+    if (installedAdapters.subSpan) {
+        (0, tracing_js_1.resetSubSpan)();
+    }
+    if (installedAdapters.tracing) {
+        (0, tracing_js_1.resetTracing)();
+    }
+    return { tracing: false, subSpan: false };
+}
+async function shutdownProviderWithTimeout(provider, shutdownTimeoutMs) {
+    let timeoutId;
+    let timedOut = false;
+    const shutdownPromise = provider.shutdown();
+    const observedShutdownPromise = shutdownPromise.catch((error) => {
+        if (!timedOut) {
+            api_js_1.log.warn({ error }, '[OpenTelemetry] provider.shutdown() failed');
+        }
+    });
+    try {
+        await Promise.race([
+            observedShutdownPromise,
+            new Promise((resolve) => {
+                timeoutId = setTimeout(() => {
+                    timedOut = true;
+                    // shutdownPromise rejection (if any) is handled by observedShutdownPromise above.
+                    void shutdownPromise.catch(() => undefined);
+                    api_js_1.log.warn('[OpenTelemetry] provider.shutdown() timed out after %dms; continuing worker shutdown', shutdownTimeoutMs);
+                    resolve();
+                }, shutdownTimeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+function init(opts = {}) {
+    if ((0, opentelemetryState_js_1.getOpenTelemetryTracerProvider)()) {
+        (0, api_js_1.message)('[OpenTelemetry] init() called more than once; ignoring duplicate call.');
+        return;
+    }
+    let installedAdapters = { tracing: false, subSpan: false };
+    let otelApi;
+    let registeredProvider;
+    let unregisterFastifyConfig;
+    let unregisterWorkerShutdownHook;
+    let ownsOpenTelemetryGlobals = false;
+    try {
+        /* eslint-disable @typescript-eslint/no-require-imports, global-require --
+         * Lazy require so init() can no-op when peer deps are missing instead of
+         * crashing at module load time. */
+        const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
+        const { BatchSpanProcessor, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');
+        const { resourceFromAttributes } = require('@opentelemetry/resources');
+        const { ATTR_SERVICE_NAME } = require('@opentelemetry/semantic-conventions');
+        otelApi = require('@opentelemetry/api');
+        const loadedOtelApi = otelApi;
+        const resourceAttributes = {
+            ...parseResourceAttributes(process.env.OTEL_RESOURCE_ATTRIBUTES),
+            ...(opts.resourceAttributes ?? {}),
+        };
+        const configuredServiceName = resolveConfiguredServiceName(opts);
+        const serviceName = configuredServiceName ?? resourceAttributes[ATTR_SERVICE_NAME] ?? DEFAULT_SERVICE_NAME;
+        const shutdownTimeoutMs = resolveShutdownTimeoutMs(opts);
+        const resource = resourceFromAttributes({
+            [ATTR_SERVICE_NAME]: serviceName,
+            ...resourceAttributes,
+            ...(configuredServiceName ? { [ATTR_SERVICE_NAME]: configuredServiceName } : {}),
+        });
+        const defaultExporter = () => {
+            const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
+            return new OTLPTraceExporter();
+        };
+        /* eslint-enable @typescript-eslint/no-require-imports, global-require */
+        const spanProcessor = opts.spanProcessor ??
+            (() => {
+                const exporter = opts.exporter ?? defaultExporter();
+                return isProduction() ? new BatchSpanProcessor(exporter) : new SimpleSpanProcessor(exporter);
+            })();
+        const provider = new NodeTracerProvider({
+            resource,
+            spanProcessors: [spanProcessor],
+        });
+        // Take ownership of the global tracer provider BEFORE installing module
+        // patches via registerInstrumentations(). provider.register() calls
+        // trace.setGlobalTracerProvider() internally, which silently fails (returns
+        // false but does not throw) when another OpenTelemetry SDK already owns the
+        // global proxy's delegate. Call setGlobalTracerProvider() directly first so
+        // we can detect that silent failure and bail before patching modules.
+        const acquiredTracerGlobal = loadedOtelApi.trace.setGlobalTracerProvider(provider);
+        if (!acquiredTracerGlobal) {
+            installedAdapters = resetInstalledTracingAdapters(installedAdapters);
+            void provider.shutdown().catch(() => undefined);
+            (0, api_js_1.message)('[OpenTelemetry] init: another OpenTelemetry tracer provider is already registered globally; aborting.');
+            return;
+        }
+        // Mark ownership BEFORE provider.register() so the outer catch's cleanup
+        // (which keys off ownsOpenTelemetryGlobals + the module-local provider
+        // reference) correctly disables the globals if register() throws.
+        ownsOpenTelemetryGlobals = true;
+        registeredProvider = provider;
+        (0, opentelemetryState_js_1.setOpenTelemetryTracerProvider)(provider);
+        // Re-call provider.register() to set context manager + propagator globals.
+        // The second setGlobalTracerProvider() call inside register() is a no-op
+        // (registerGlobal returns false because the proxy is already owned by us),
+        // but the propagator + context manager setup still runs.
+        provider.register();
+        configureOpenTelemetryDiagnostics(loadedOtelApi);
+        if (opts.fastify) {
+            /* eslint-disable @typescript-eslint/no-require-imports, global-require */
+            const { registerInstrumentations } = require('@opentelemetry/instrumentation');
+            const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
+            // @fastify/otel uses `export = exported` so the require() returns the namespace
+            // object; the constructor lives on `.FastifyOtelInstrumentation` (also as `.default`).
+            const { FastifyOtelInstrumentation } = require('@fastify/otel');
+            /* eslint-enable @typescript-eslint/no-require-imports, global-require */
+            registerInstrumentations({
+                instrumentations: [
+                    // HTTP first — Fastify instrumentation depends on it.
+                    new HttpInstrumentation(),
+                    new FastifyOtelInstrumentation({ registerOnInitialization: true }),
+                ],
+                tracerProvider: provider,
+            });
+        }
+        if (opts.tracing) {
+            const tracer = loadedOtelApi.trace.getTracer(serviceName);
+            installedAdapters.tracing = (0, tracing_js_1.setupTracing)({
+                startSsrRequestOptions: () => ({
+                    // Keep the root span free of request payload data. Future safe
+                    // attributes should be derived from structured metadata supplied by
+                    // Ruby, not parsed out of the executable renderingRequest string.
+                    opentelemetry: { name: 'ror.ssr.request' },
+                }),
+                executor: async (fn, unitOfWorkOptions) => {
+                    const otelOpts = unitOfWorkOptions.opentelemetry ?? { name: 'ror.ssr.request' };
+                    return tracer.startActiveSpan(otelOpts.name, { attributes: otelOpts.attributes }, async (span) => {
+                        try {
+                            return await fn();
+                        }
+                        catch (err) {
+                            span.setStatus({
+                                code: loadedOtelApi.SpanStatusCode.ERROR,
+                                message: err instanceof Error ? err.message : String(err),
+                            });
+                            throw err;
+                        }
+                        finally {
+                            span.end();
+                        }
+                    });
+                },
+            });
+            if (installedAdapters.tracing) {
+                const subSpanImpl = (subOpts, fn) => tracer.startActiveSpan(subOpts.name, { attributes: subOpts.attributes }, async (span) => {
+                    const controller = {
+                        setAttributes(attributes) {
+                            span.setAttributes(attributes);
+                        },
+                    };
+                    try {
+                        return await fn(controller);
+                    }
+                    catch (err) {
+                        span.setStatus({
+                            code: loadedOtelApi.SpanStatusCode.ERROR,
+                            message: err instanceof Error ? err.message : String(err),
+                        });
+                        throw err;
+                    }
+                    finally {
+                        span.end();
+                    }
+                });
+                installedAdapters.subSpan = (0, tracing_js_1.setupSubSpan)(subSpanImpl);
+            }
+            else {
+                (0, api_js_1.message)('[OpenTelemetry] tracing integration was not installed because another tracing integration is ' +
+                    'active; skipping OpenTelemetry sub-spans.');
+            }
+        }
+        let shutdownOpenTelemetryPromise;
+        const shutdownOpenTelemetry = () => {
+            shutdownOpenTelemetryPromise ?? (shutdownOpenTelemetryPromise = (async () => {
+                try {
+                    await shutdownProviderWithTimeout(provider, shutdownTimeoutMs);
+                    if ((0, opentelemetryState_js_1.getOpenTelemetryTracerProvider)() === provider) {
+                        (0, opentelemetryState_js_1.setOpenTelemetryTracerProvider)(null);
+                        disableOpenTelemetryGlobals(loadedOtelApi);
+                        ownsOpenTelemetryGlobals = false;
+                        installedAdapters = resetInstalledTracingAdapters(installedAdapters);
+                    }
+                }
+                finally {
+                    unregisterFastifyConfig?.();
+                    unregisterWorkerShutdownHook?.();
+                }
+            })());
+            return shutdownOpenTelemetryPromise;
+        };
+        // Register these last so failed init paths do not leave partial shutdown hooks
+        // behind. The worker hook runs during cluster restarts, while Fastify onClose
+        // still handles explicit app.close() calls from tests or custom integrations.
+        unregisterWorkerShutdownHook = (0, shutdownHooks_js_1.registerWorkerShutdownHook)(shutdownOpenTelemetry);
+        unregisterFastifyConfig = (0, fastifyConfig_js_1.registerFastifyConfigFunction)((app) => {
+            app.addHook('onClose', shutdownOpenTelemetry);
+        });
+        api_js_1.log.info('[OpenTelemetry] Tracer provider initialized');
+    }
+    catch (err) {
+        unregisterFastifyConfig?.();
+        unregisterWorkerShutdownHook?.();
+        if (ownsOpenTelemetryGlobals &&
+            registeredProvider &&
+            otelApi &&
+            (0, opentelemetryState_js_1.getOpenTelemetryTracerProvider)() === registeredProvider) {
+            (0, opentelemetryState_js_1.setOpenTelemetryTracerProvider)(null);
+            disableOpenTelemetryGlobals(otelApi);
+            ownsOpenTelemetryGlobals = false;
+        }
+        installedAdapters = resetInstalledTracingAdapters(installedAdapters);
+        (0, api_js_1.message)(`[OpenTelemetry] init failed: ${String(err)}`);
+    }
+}
+//# sourceMappingURL=opentelemetry.js.map

package/lib/shared/opentelemetryState.d.ts

@@ -0,0 +1,4 @@
+import type { NodeTracerProvider as NodeTracerProviderType } from '@opentelemetry/sdk-trace-node';
+export declare function getOpenTelemetryTracerProvider(): NodeTracerProviderType | null;
+export declare function setOpenTelemetryTracerProvider(provider: NodeTracerProviderType | null): void;
+//# sourceMappingURL=opentelemetryState.d.ts.map

package/lib/shared/opentelemetryState.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOpenTelemetryTracerProvider = getOpenTelemetryTracerProvider;
+exports.setOpenTelemetryTracerProvider = setOpenTelemetryTracerProvider;
+let tracerProvider = null;
+function getOpenTelemetryTracerProvider() {
+    return tracerProvider;
+}
+function setOpenTelemetryTracerProvider(provider) {
+    tracerProvider = provider;
+}
+//# sourceMappingURL=opentelemetryState.js.map

package/lib/shared/tracing.d.ts

@@ -43,11 +43,90 @@ export interface TracingIntegrationOptions {
  * @param options.startSsrRequestOptions - Options used to start a new unit of work for an SSR request.
  *   Should be an object with your integration name as the only property.
  *   It will be passed to the executor.
+ * @returns true when this call installed the tracing integration.
  */
-export declare function setupTracing(options: TracingIntegrationOptions): void;
+export declare function setupTracing(options: TracingIntegrationOptions): boolean;
 /**
  * Reports a unit of work to the tracing service, if any.
  */
 export declare function trace<T>(fn: UnitOfWork<T>, unitOfWorkOptions: UnitOfWorkOptions): Promise<T>;
+/**
+ * Resets the installed tracing executor + startSsrRequestOptions back to
+ * defaults. Internal integrations use this during lifecycle teardown.
+ */
+export declare function resetTracing(): void;
+/**
+ * Test-only: reset the installed tracing executor + startSsrRequestOptions back
+ * to defaults. Not part of the public api — do not re-export from
+ * `integrations/api.ts`.
+ */
+export declare function __resetTracingForTest(): void;
+/**
+ * Options passed to a sub-span wrapper.
+ *
+ * `name` is the span name (use dot.namespaced form, e.g. `ror.bundle.upload`).
+ * `attributes` are arbitrary key/value pairs attached to the span at creation.
+ */
+export interface SubSpanOptions {
+    name: string;
+    attributes?: Record<string, string | number | boolean>;
+}
+/**
+ * Handed to the wrapped function so it can record attributes that are only
+ * known after the work runs (e.g., response byte counts). Implementations
+ * forward calls to the underlying span; the no-op default discards them.
+ *
+ * Only include byte counts, hashes, and counts here — never raw request or
+ * response payloads. Span attributes are not redacted by the renderer's
+ * logging policy.
+ */
+export interface SubSpanController {
+    setAttributes(attributes: Record<string, string | number | boolean>): void;
+}
+/**
+ * Signature of a sub-span implementation installed via {@link setupSubSpan}.
+ * Must invoke `fn(controller)` and return its result. May wrap `fn` in a
+ * tracing span. The implementation supplies a controller that forwards
+ * `setAttributes` to the span; pass a no-op controller (e.g.
+ * `{ setAttributes() {} }`) when no span is being created.
+ *
+ * Implementations must either invoke `fn` synchronously or not invoke it at
+ * all before throwing/rejecting. Deferred invocation, such as scheduling `fn`
+ * with `setImmediate`, is unsupported because the fallback may run `fn`
+ * itself to preserve renderer behavior when an implementation fails before
+ * invocation.
+ */
+export type SubSpanFn = <T>(opts: SubSpanOptions, fn: (controller: SubSpanController) => Promise<T>) => Promise<T>;
+/**
+ * Install a sub-span implementation. Integrations call this from their `init()`
+ * to start receiving sub-span events. If never called, sub-spans are no-ops.
+ * @returns true when this call installed the sub-span integration.
+ */
+export declare function setupSubSpan(impl: SubSpanFn): boolean;
+/**
+ * Wrap an async function in a named sub-span. Safe to call even when no
+ * integration is installed — defaults to passing through to `fn`.
+ *
+ * The wrapped function receives a {@link SubSpanController} it can use to
+ * attach attributes that are only known after the work runs (e.g., response
+ * byte counts). With no integration installed, attribute updates are dropped.
+ *
+ * If the installed implementation throws or rejects before invoking `fn`, the
+ * caller is shielded: `fn` is still executed outside any sub-span (with the
+ * no-op controller) and its result returned. If the implementation fails
+ * after invoking `fn`, the error is rethrown so `fn` is never run twice.
+ */
+export declare function subSpan<T>(opts: SubSpanOptions, fn: (controller: SubSpanController) => Promise<T>): Promise<T>;
+/**
+ * Resets the installed sub-span implementation back to the default pass-through.
+ * Internal integrations use this during lifecycle teardown.
+ */
+export declare function resetSubSpan(): void;
+/**
+ * Test-only: reset the installed sub-span implementation back to the default
+ * pass-through. Not part of the public api — do not re-export from
+ * `integrations/api.ts`.
+ */
+export declare function __resetSubSpanForTest(): void;
 export {};
 //# sourceMappingURL=tracing.d.ts.map

package/lib/shared/tracing.js

@@ -1,8 +1,18 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startSsrRequestOptions = void 0;
 exports.setupTracing = setupTracing;
 exports.trace = trace;
+exports.resetTracing = resetTracing;
+exports.__resetTracingForTest = __resetTracingForTest;
+exports.setupSubSpan = setupSubSpan;
+exports.subSpan = subSpan;
+exports.resetSubSpan = resetSubSpan;
+exports.__resetSubSpanForTest = __resetSubSpanForTest;
+const log_js_1 = __importDefault(require("./log.js"));
 const errorReporter_js_1 = require("./errorReporter.js");
 /* eslint-enable @typescript-eslint/no-empty-object-type */
 let setupRun = false;
@@ -18,17 +28,19 @@ exports.startSsrRequestOptions = startSsrRequestOptions;
  * @param options.startSsrRequestOptions - Options used to start a new unit of work for an SSR request.
  *   Should be an object with your integration name as the only property.
  *   It will be passed to the executor.
+ * @returns true when this call installed the tracing integration.
  */
 function setupTracing(options) {
     if (setupRun) {
         (0, errorReporter_js_1.message)('setupTracing called more than once. Currently only one tracing integration can be enabled.');
-        return;
+        return false;
     }
     executor = options.executor;
     if (options.startSsrRequestOptions) {
         mutableStartSsrRequestOptions = options.startSsrRequestOptions;
     }
     setupRun = true;
+    return true;
 }
 /**
  * Reports a unit of work to the tracing service, if any.
@@ -36,4 +48,100 @@ function setupTracing(options) {
 function trace(fn, unitOfWorkOptions) {
     return executor(fn, unitOfWorkOptions);
 }
+/**
+ * Resets the installed tracing executor + startSsrRequestOptions back to
+ * defaults. Internal integrations use this during lifecycle teardown.
+ */
+function resetTracing() {
+    executor = (fn) => fn();
+    mutableStartSsrRequestOptions = () => ({});
+    setupRun = false;
+}
+/**
+ * Test-only: reset the installed tracing executor + startSsrRequestOptions back
+ * to defaults. Not part of the public api — do not re-export from
+ * `integrations/api.ts`.
+ */
+// eslint-disable-next-line no-underscore-dangle
+function __resetTracingForTest() {
+    resetTracing();
+}
+const noOpSubSpanController = {
+    setAttributes() { },
+};
+const defaultSubSpan = (_opts, fn) => fn(noOpSubSpanController);
+let subSpanImpl = defaultSubSpan;
+let subSpanSetupRun = false;
+/**
+ * Install a sub-span implementation. Integrations call this from their `init()`
+ * to start receiving sub-span events. If never called, sub-spans are no-ops.
+ * @returns true when this call installed the sub-span integration.
+ */
+function setupSubSpan(impl) {
+    if (subSpanSetupRun) {
+        (0, errorReporter_js_1.message)('setupSubSpan called more than once. Only one sub-span integration can be enabled.');
+        return false;
+    }
+    subSpanImpl = impl;
+    subSpanSetupRun = true;
+    return true;
+}
+/**
+ * Wrap an async function in a named sub-span. Safe to call even when no
+ * integration is installed — defaults to passing through to `fn`.
+ *
+ * The wrapped function receives a {@link SubSpanController} it can use to
+ * attach attributes that are only known after the work runs (e.g., response
+ * byte counts). With no integration installed, attribute updates are dropped.
+ *
+ * If the installed implementation throws or rejects before invoking `fn`, the
+ * caller is shielded: `fn` is still executed outside any sub-span (with the
+ * no-op controller) and its result returned. If the implementation fails
+ * after invoking `fn`, the error is rethrown so `fn` is never run twice.
+ */
+function subSpan(opts, fn) {
+    let invoked = false;
+    const wrappedFn = (controller) => {
+        invoked = true;
+        return fn(controller);
+    };
+    try {
+        return Promise.resolve(subSpanImpl(opts, wrappedFn)).catch((err) => {
+            if (invoked) {
+                return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+            }
+            // log.warn (not message) for the silent-fallback path. message() goes to
+            // log.error + external notifiers (Sentry/Bugsnag/etc.) on every request,
+            // which is too noisy for a per-request recoverable failure where fn() is
+            // still executed. log.warn surfaces the broken integration without
+            // paging the on-call team for every render.
+            log_js_1.default.warn({ err }, 'subSpan implementation rejected before invoking fn(); running fn() without a span');
+            return wrappedFn(noOpSubSpanController);
+        });
+    }
+    catch (err) {
+        if (invoked) {
+            return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+        }
+        log_js_1.default.warn({ err }, 'subSpan implementation threw before invoking fn(); running fn() without a span');
+        return wrappedFn(noOpSubSpanController);
+    }
+}
+/**
+ * Resets the installed sub-span implementation back to the default pass-through.
+ * Internal integrations use this during lifecycle teardown.
+ */
+function resetSubSpan() {
+    subSpanImpl = defaultSubSpan;
+    subSpanSetupRun = false;
+}
+/**
+ * Test-only: reset the installed sub-span implementation back to the default
+ * pass-through. Not part of the public api — do not re-export from
+ * `integrations/api.ts`.
+ */
+// eslint-disable-next-line no-underscore-dangle
+function __resetSubSpanForTest() {
+    resetSubSpan();
+}
 //# sourceMappingURL=tracing.js.map

package/lib/testUtils/opentelemetry.d.ts

@@ -0,0 +1,2 @@
+export declare function resetOpenTelemetryForTest(): Promise<void>;
+//# sourceMappingURL=opentelemetry.d.ts.map