@iskra-bun/core 0.1.1 → 0.3.0

package/src/otel.ts

@@ -12,8 +12,9 @@
  * actionable error instead of an unhandled module-resolution failure.
  */
 import type { OtelConfig } from './types';
+import { nodeEnv } from './env';
 
-let sdkInstance: any = null;
+let sdkInstance: { shutdown(): Promise<void> } | null = null;
 
 /** Optional OTel package specifiers, indirected so tsc does not resolve them statically. */
 const OTEL_MODULES = {
@@ -26,9 +27,202 @@ const OTEL_MODULES = {
     semconv: '@opentelemetry/semantic-conventions',
 } as const;
 
+// The optional OTel packages are loaded by specifier, untyped; these are the
+// parts of them used here.
+type Ctor<T = unknown> = new (options: Record<string, unknown>) => T;
+interface OtelSdkNode {
+    NodeSDK: Ctor<{ start(): void; shutdown(): Promise<void> }>;
+}
+interface OtelAutoInstrumentations {
+    getNodeAutoInstrumentations(overrides: Record<string, unknown>): unknown;
+}
+interface OtelTraceExporter {
+    OTLPTraceExporter: Ctor;
+}
+interface OtelMetricExporter {
+    OTLPMetricExporter: Ctor;
+}
+interface OtelSdkMetrics {
+    PeriodicExportingMetricReader: Ctor;
+}
+interface OtelSemconv {
+    ATTR_SERVICE_NAME?: string;
+    ATTR_SERVICE_VERSION?: string;
+}
+/** `@opentelemetry/resources`: 2.x exports resourceFromAttributes(), 1.x the Resource class. */
+export interface OtelResourcesModule {
+    resourceFromAttributes?: (attributes: Record<string, string>) => unknown;
+    Resource?: new (attributes: Record<string, string>) => unknown;
+}
+
 /** Import an optional module by specifier; the indirection keeps tsc from resolving it. */
-function importOptional(specifier: string): Promise<any> {
-    return import(specifier);
+function importOptional<T>(specifier: string): Promise<T> {
+    return import(specifier) as Promise<T>;
+}
+
+const DEFAULT_ENDPOINT = 'http://localhost:4318';
+const HTTP_INSTRUMENTATION = '@opentelemetry/instrumentation-http';
+
+/**
+ * Query parameters whose values are exported as REDACTED in span URLs (see
+ * redactUrl). Names are compared without case, `-` or `_`.
+ */
+export const SECRET_QUERY_PARAMS: readonly string[] = [
+    'token',
+    'access_token',
+    'refresh_token',
+    'id_token',
+    'auth_token',
+    'session_token',
+    'api_key',
+    'key',
+    'secret',
+    'client_secret',
+    'password',
+    'passwd',
+    'code',
+    'state',
+    'ticket',
+    'otp',
+    'jwt',
+    'signature',
+    'sig',
+    'X-Amz-Signature',
+    'X-Amz-Credential',
+    'X-Amz-Security-Token',
+    'AWSAccessKeyId',
+    'X-Goog-Signature',
+    'X-Goog-Credential',
+];
+
+const normalizeParam = (name: string): string => name.toLowerCase().replace(/[-_]/g, '');
+
+function decodeParam(name: string): string {
+    try {
+        return decodeURIComponent(name.replace(/\+/g, ' '));
+    } catch {
+        return name;
+    }
+}
+
+/**
+ * `url` (absolute, or a path) with the value of each query parameter named in
+ * `params` replaced by REDACTED, the rest kept as it was. Telemetry exported
+ * URLs as they were requested: `?api_key=`, `?access_token=`, a presigned
+ * URL's signature.
+ */
+export function redactUrl(url: string, params: readonly string[] = SECRET_QUERY_PARAMS): string {
+    const start = url.indexOf('?');
+    if (start === -1 || params.length === 0) return url;
+    const names = new Set(params.map(normalizeParam));
+    const hash = url.indexOf('#', start);
+    const end = hash === -1 ? url.length : hash;
+    let redacted = false;
+    const query = url
+        .slice(start + 1, end)
+        .split('&')
+        .map((pair) => {
+            const eq = pair.indexOf('=');
+            if (eq === -1 || !names.has(normalizeParam(decodeParam(pair.slice(0, eq))))) return pair;
+            redacted = true;
+            return `${pair.slice(0, eq)}=REDACTED`;
+        })
+        .join('&');
+    return redacted ? url.slice(0, start + 1) + query + url.slice(end) : url;
+}
+
+/** The URL attributes of an HTTP span, in the stable and the older semantic conventions. */
+const URL_ATTRIBUTES = ['url.full', 'url.query', 'http.url', 'http.target'];
+
+/** Rewrites the URL attributes of a recording SDK span (it has `attributes`). */
+function redactSpanUrls(span: unknown, params: readonly string[]): void {
+    const { attributes, setAttribute } = (span ?? {}) as {
+        attributes?: Record<string, unknown>;
+        setAttribute?: (key: string, value: string) => unknown;
+    };
+    if (!attributes || typeof setAttribute !== 'function') return;
+    for (const key of URL_ATTRIBUTES) {
+        const value = attributes[key];
+        if (typeof value !== 'string') continue;
+        // url.query is the query string alone, without its "?".
+        const redacted = key === 'url.query' ? redactUrl(`?${value}`, params).slice(1) : redactUrl(value, params);
+        if (redacted !== value) setAttribute.call(span, key, redacted);
+    }
+}
+
+/**
+ * The options initOtel() passes to getNodeAutoInstrumentations(): the app's
+ * `instrumentations` over Iskra's defaults. The HTTP instrumentation redacts
+ * SECRET_QUERY_PARAMS unless `redactedQueryParams` / `redactedQueryParamsServer`
+ * are set (instrumentation-http 0.204 / 0.222 and later apply them itself;
+ * for older releases a requestHook rewrites the span's URL attributes, before
+ * the app's own requestHook runs).
+ */
+export function autoInstrumentationOptions(config: OtelConfig): Record<string, unknown> {
+    const http: Record<string, unknown> = { ...config.instrumentations?.[HTTP_INSTRUMENTATION] };
+    const list = (value: unknown) => (Array.isArray(value) ? (value as string[]) : undefined);
+    const client = list(http.redactedQueryParams) ?? SECRET_QUERY_PARAMS;
+    const server = list(http.redactedQueryParamsServer) ?? SECRET_QUERY_PARAMS;
+    const appHook = http.requestHook;
+    return {
+        '@opentelemetry/instrumentation-fs': { enabled: false },
+        ...config.instrumentations,
+        [HTTP_INSTRUMENTATION]: {
+            ...http,
+            redactedQueryParams: client,
+            redactedQueryParamsServer: server,
+            requestHook: (span: unknown, request: unknown) => {
+                // A ClientRequest (outgoing) has setHeader(); an IncomingMessage does not.
+                const outgoing = typeof (request as { setHeader?: unknown } | null)?.setHeader === 'function';
+                redactSpanUrls(span, outgoing ? client : server);
+                if (typeof appHook === 'function') appHook(span, request);
+            },
+        },
+    };
+}
+
+/** Hosts spans may reach in clear text: this machine, a private network, or a name that only resolves inside one. */
+function isPrivateHost(hostname: string): boolean {
+    const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    if (host.includes(':')) return host === '::1' || /^f[cd]/.test(host);
+    return (
+        !host.includes('.') ||
+        /\.(localhost|local|internal)$/.test(host) ||
+        /^(127|10)\./.test(host) ||
+        /^192\.168\./.test(host) ||
+        /^172\.(1[6-9]|2\d|3[01])\./.test(host)
+    );
+}
+
+/**
+ * The OTLP endpoint as it is safe to log, its origin (the path, query or
+ * userinfo can carry an API key), and whether spans travel to it in clear
+ * text beyond this machine and its private network.
+ */
+export function describeOtelEndpoint(config: OtelConfig): { origin: string; plaintext: boolean } {
+    try {
+        const url = new URL(config.endpoint || DEFAULT_ENDPOINT);
+        return { origin: url.origin, plaintext: url.protocol === 'http:' && !isPrivateHost(url.hostname) };
+    } catch {
+        return { origin: '(invalid URL)', plaintext: false };
+    }
+}
+
+/**
+ * Builds a Resource with whichever API the installed `@opentelemetry/resources`
+ * provides: 2.x only exports `resourceFromAttributes()` (`Resource` is a type
+ * there, so `new Resource()` throws), 1.x exports the `Resource` class.
+ */
+export function createResource(resources: OtelResourcesModule, attributes: Record<string, string>): unknown {
+    if (typeof resources?.resourceFromAttributes === 'function') {
+        return resources.resourceFromAttributes(attributes);
+    }
+    if (typeof resources?.Resource === 'function') {
+        return new resources.Resource(attributes);
+    }
+    throw new Error(
+        '[iskra/otel] Unsupported @opentelemetry/resources: it exports neither resourceFromAttributes() nor Resource',
+    );
 }
 
 /**
@@ -45,32 +239,29 @@ export async function initOtel(config: OtelConfig, appName: string): Promise<voi
             { OTLPTraceExporter },
             { OTLPMetricExporter },
             { PeriodicExportingMetricReader },
-            { Resource },
+            resources,
             semconv,
         ] = await Promise.all([
-            importOptional(OTEL_MODULES.sdkNode),
-            importOptional(OTEL_MODULES.autoInstrumentations),
-            importOptional(OTEL_MODULES.traceExporter),
-            importOptional(OTEL_MODULES.metricExporter),
-            importOptional(OTEL_MODULES.sdkMetrics),
-            importOptional(OTEL_MODULES.resources),
-            importOptional(OTEL_MODULES.semconv),
+            importOptional<OtelSdkNode>(OTEL_MODULES.sdkNode),
+            importOptional<OtelAutoInstrumentations>(OTEL_MODULES.autoInstrumentations),
+            importOptional<OtelTraceExporter>(OTEL_MODULES.traceExporter),
+            importOptional<OtelMetricExporter>(OTEL_MODULES.metricExporter),
+            importOptional<OtelSdkMetrics>(OTEL_MODULES.sdkMetrics),
+            importOptional<OtelResourcesModule>(OTEL_MODULES.resources),
+            importOptional<OtelSemconv>(OTEL_MODULES.semconv),
         ]);
 
         const serviceName = config.serviceName || appName;
-        const endpoint = config.endpoint || 'http://localhost:4318';
+        const endpoint = config.endpoint || DEFAULT_ENDPOINT;
 
-        const resource = new Resource({
-            [semconv.ATTR_SERVICE_NAME]: serviceName,
-            [semconv.ATTR_SERVICE_VERSION]: config.serviceVersion || '0.1.0',
-            'deployment.environment': config.environment || process.env.NODE_ENV || 'development',
+        const resource = createResource(resources, {
+            [semconv.ATTR_SERVICE_NAME ?? 'service.name']: serviceName,
+            [semconv.ATTR_SERVICE_VERSION ?? 'service.version']: config.serviceVersion || '0.1.0',
+            'deployment.environment': config.environment || nodeEnv() || 'development',
             ...config.resourceAttributes,
         });
 
-        const instrumentationOverrides: Record<string, any> = {
-            '@opentelemetry/instrumentation-fs': { enabled: false },
-            ...config.instrumentations,
-        };
+        const instrumentationOverrides = autoInstrumentationOptions(config);
 
         const sdk = new NodeSDK({
             resource,
@@ -84,14 +275,19 @@ export async function initOtel(config: OtelConfig, appName: string): Promise<voi
 
         sdk.start();
         sdkInstance = sdk;
-    } catch (err: any) {
+    } catch (err) {
         // Provide a clear error when OTel packages are not installed
-        if (err?.code === 'ERR_MODULE_NOT_FOUND' || err?.code === 'MODULE_NOT_FOUND' || err?.message?.includes('Cannot find')) {
+        const e = err as { code?: string; message?: string } | null;
+        if (
+            e?.code === 'ERR_MODULE_NOT_FOUND' ||
+            e?.code === 'MODULE_NOT_FOUND' ||
+            e?.message?.includes('Cannot find')
+        ) {
             throw new Error(
                 `[iskra/otel] OpenTelemetry packages are not installed. ` +
-                `Install them with: bun add @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node ` +
-                `@opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http ` +
-                `@opentelemetry/sdk-metrics @opentelemetry/resources @opentelemetry/semantic-conventions`,
+                    `Install them with: bun add @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node ` +
+                    `@opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http ` +
+                    `@opentelemetry/sdk-metrics @opentelemetry/resources @opentelemetry/semantic-conventions`,
             );
         }
         throw err;

package/src/traced.ts

@@ -0,0 +1,59 @@
+import { SpanStatusCode, trace, type Attributes, type Span, type Tracer } from '@opentelemetry/api';
+
+export interface TracedOptions {
+    /** Attributes of every span. */
+    attributes?: Attributes;
+    /** The tracer; default the global provider's `iskra` tracer (no spans without an OpenTelemetry SDK). */
+    tracer?: Tracer;
+}
+
+function fail(span: Span, error: unknown): void {
+    span.recordException(error instanceof Error ? error : new Error(String(error)));
+    span.setStatus({ code: SpanStatusCode.ERROR, message: error instanceof Error ? error.name : 'Error' });
+}
+
+/**
+ * Wraps `fn` in a span named `name`, by convention `layer.domain.method`
+ * (`repo.usuarios.buscar`): the span is the active one while `fn` runs, so
+ * the spans started inside (a query, a call to another service) are its
+ * children; a throw or a rejection marks it as an error. Without an
+ * OpenTelemetry SDK it costs a no-op span.
+ *
+ * ```ts
+ * const buscar = traced('repo.usuarios.buscar', async (id: number) => oracle.one(SQL, { id }));
+ * ```
+ */
+export function traced<A extends unknown[], R>(
+    name: string,
+    fn: (...args: A) => R,
+    options: TracedOptions = {},
+): (...args: A) => R {
+    return function (this: unknown, ...args: A): R {
+        const tracer = options.tracer ?? trace.getTracer('iskra');
+        return tracer.startActiveSpan(name, { attributes: options.attributes }, (span) => {
+            let result: R;
+            try {
+                result = fn.apply(this, args);
+            } catch (error) {
+                fail(span, error);
+                span.end();
+                throw error;
+            }
+            if (result instanceof Promise) {
+                return result.then(
+                    (value) => {
+                        span.end();
+                        return value;
+                    },
+                    (error: unknown) => {
+                        fail(span, error);
+                        span.end();
+                        throw error;
+                    },
+                ) as R;
+            }
+            span.end();
+            return result;
+        });
+    };
+}

package/src/types.ts

@@ -13,17 +13,42 @@ export interface Plugin {
     install(app: App): Promise<void> | void;
 }
 
-export interface Context<T = any> {
+/** What an `app.on()` handler receives; `payload` is the emitted value. */
+export interface Context<T = unknown> {
     app: App;
     logger: Logger;
     payload: T;
-    reply(data: any): void;
+    /** Emits `<event>:reply` with `data`. */
+    reply(data: unknown): void;
 }
 
+/**
+ * What each kit shares through `app.context`, by key, so `app.context.get('db')`
+ * is typed. Kits add their keys with declaration merging, and so can an app:
+ *
+ * ```ts
+ * declare module '@iskra-bun/core' {
+ *     interface AppContextRegistry {
+ *         bridge: DesktopBridge;
+ *     }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- filled by declaration merging
+export interface AppContextRegistry {}
+
+/**
+ * The payload of each app event, by name, so `app.on('process:exit', ...)`
+ * and `app.emit(...)` are typed. Kits add their events with declaration
+ * merging, and so can an app (as with AppContextRegistry).
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- filled by declaration merging
+export interface AppEvents {}
+
 export interface OtelConfig {
     /** Defaults to true when otel config is present */
     enabled?: boolean;
-    /** OTLP endpoint URL. Defaults to http://localhost:4318 */
+    /** OTLP endpoint URL. Defaults to http://localhost:4318; use https:// for a collector on another host. */
     endpoint?: string;
     /** Overrides app name for the service.name resource attribute */
     serviceName?: string;
@@ -35,8 +60,14 @@ export interface OtelConfig {
     metricIntervalMs?: number;
     /** Additional resource attributes */
     resourceAttributes?: Record<string, string>;
-    /** Auto-instrumentation overrides (passed to getNodeAutoInstrumentations) */
-    instrumentations?: Record<string, { enabled?: boolean }>;
+    /**
+     * Options of each auto-instrumentation, by package name, passed to
+     * getNodeAutoInstrumentations(): `{ enabled: false }`, or its own options
+     * (`'@opentelemetry/instrumentation-http': { ignoreIncomingRequestHook,
+     * redactedQueryParams }`). The HTTP one redacts SECRET_QUERY_PARAMS in
+     * exported URLs unless `redactedQueryParams` says otherwise.
+     */
+    instrumentations?: Record<string, { enabled?: boolean; [option: string]: unknown }>;
 }
 
 export interface AppConfig {
@@ -46,6 +77,13 @@ export interface AppConfig {
         level?: string;
     };
     otel?: OtelConfig;
+    /**
+     * Signals that trigger a graceful `stop()` and exit. Default
+     * `['SIGTERM', 'SIGINT']` (none under NODE_ENV=test); `false` disables.
+     */
+    shutdownSignals?: string[] | false;
+    /** Max time for a signal-triggered stop before forcing exit(1). Default 10000. */
+    shutdownTimeoutMs?: number;
     processes?: Record<string, ProcessConfig>;
     socket?: {
         enabled: boolean;
@@ -53,15 +91,17 @@ export interface AppConfig {
         adapter?: 'bun' | 'socket.io';
     };
     kv?: {
-        driver: 'memory' | 'redis' | 'libsql';
-        connection?: any;
+        driver: 'memory' | 'redis';
+        /** Redis: a URL string, ioredis options, or ioredis options with `url`. */
+        connection?: string | Record<string, unknown>;
     };
     db?: {
         driver: 'postgres' | 'mysql' | 'sqlite' | 'libsql';
         url: string;
         authToken?: string;
     };
-    [key: string]: any;
+    /** Sections of other kits or of the app; read them with their own type. */
+    [key: string]: unknown;
 }
 
 export interface RestartBackoffConfig {
@@ -80,7 +120,20 @@ export interface ProcessConfig {
     restartOnCrash?: boolean;
     maxRestarts?: number;
     restartCooldown?: number;
+    /** Variables set for the child, over the ones it inherits (see `inheritEnv`). */
     env?: Record<string, string>;
+    /**
+     * Which of the app's environment variables the child inherits. Default
+     * `false`: a minimal set without secrets (PATH, HOME, locale, TZ, temp
+     * dir, NODE_ENV…). A list adds those names to it; `true` passes them all
+     * (DATABASE_URL, AUTH_SECRET, cloud keys…).
+     */
+    inheritEnv?: boolean | string[];
+    /**
+     * `stdio` mode: bytes `send()` lets wait for a child that is not reading
+     * its stdin; past this it refuses messages (returns false). Default 8 MiB.
+     */
+    maxPendingStdinBytes?: number;
     /** Exponential backoff settings for restarts. Defaults to 1000 ms flat (no backoff). */
     restartBackoff?: RestartBackoffConfig;
 }