@iskra-bun/core 0.1.1 → 0.3.0

package/dist/index.js

@@ -3,39 +3,146 @@ import mitt from "mitt";
 
 // src/logger/index.ts
 import pino from "pino";
+import pretty from "pino-pretty";
+
+// src/env.ts
+var NODE_ENV = "NODE_ENV";
+function nodeEnv() {
+  return process.env[NODE_ENV] || void 0;
+}
+function isDevelopmentEnv(env = nodeEnv()) {
+  return env === "development" || env === "test";
+}
+function isProductionEnv(env = nodeEnv()) {
+  return !isDevelopmentEnv(env);
+}
+
+// src/logger/index.ts
+var REDACTED_KEYS = [
+  "password",
+  "pass",
+  "passwd",
+  "apiKey",
+  "apiSecret",
+  "token",
+  "authToken",
+  "accessToken",
+  "refreshToken",
+  "idToken",
+  "secret",
+  "clientSecret",
+  "secretKey",
+  "privateKey",
+  "authorization",
+  "proxyAuthorization",
+  "cookie",
+  "setCookie",
+  "sessionId"
+];
+var REDACTED_SUFFIXES = ["password", "passwd", "secret", "token", "apikey", "secretkey", "privatekey", "accesskey"];
+var normalizeKey = (key) => key.toLowerCase().replace(/[-_]/g, "");
+var SENSITIVE = new Set(REDACTED_KEYS.map(normalizeKey));
+var isSensitive = (key) => {
+  const normalized = normalizeKey(key);
+  return SENSITIVE.has(normalized) || REDACTED_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
+};
+var CENSOR = "[REDACTED]";
+var MAX_DEPTH = 8;
+var IN_PROGRESS = /* @__PURE__ */ Symbol("in progress");
+var SERIALIZED_ERROR_PROTO = Object.getPrototypeOf(pino.stdSerializers.err(new Error()));
+var isPlainObject = (value) => {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null || proto === SERIALIZED_ERROR_PROTO;
+};
+var SECRET_PARAM = /pass|secret|token|key|sig|auth/i;
+function maskCredentials(text) {
+  return text.replace(/\b([a-z][\w+.-]{0,30}:\/\/[^\s:@/]{0,256}):[^\s@/]{1,256}@/gi, "$1:[REDACTED]@").replace(
+    /([?&])([\w.-]{1,100})=([^&\s'"#]+)/g,
+    (match, sep, name) => SECRET_PARAM.test(name) ? `${sep}${name}=[REDACTED]` : match
+  );
+}
+function scrubError(err, depth, done) {
+  const serialized = { ...pino.stdSerializers.err(err) };
+  if (typeof serialized.message === "string") serialized.message = maskCredentials(serialized.message);
+  if (typeof serialized.stack === "string") serialized.stack = maskCredentials(serialized.stack);
+  return scrubEntries(serialized, depth, done, true);
+}
+function scrub(value, depth, done, deep = false) {
+  if (value === null || typeof value !== "object" || depth > MAX_DEPTH) return value;
+  if (done.has(value)) {
+    const result2 = done.get(value);
+    return result2 === IN_PROGRESS ? "[Circular]" : result2;
+  }
+  const isError = value instanceof Error;
+  const toJSON = value.toJSON;
+  const walk = isError || Array.isArray(value) || isPlainObject(value) || typeof toJSON === "function" || deep;
+  if (!walk) return value;
+  done.set(value, IN_PROGRESS);
+  let result;
+  if (isError) {
+    result = scrubError(value, depth, done);
+  } else if (Array.isArray(value)) {
+    let copy;
+    value.forEach((item, i) => {
+      const scrubbed = scrub(item, depth + 1, done, deep);
+      if (scrubbed !== item) (copy ??= value.slice())[i] = scrubbed;
+    });
+    result = copy ?? value;
+  } else if (isPlainObject(value)) {
+    result = scrubEntries(value, depth, done, deep);
+  } else if (typeof toJSON === "function") {
+    result = scrub(toJSON.call(value), depth, done, deep);
+  } else {
+    result = scrubEntries({ ...value }, depth, done, deep);
+  }
+  done.set(value, result);
+  return result;
+}
+function scrubEntries(value, depth, done, deep = false) {
+  let copy;
+  for (const [key, item] of Object.entries(value)) {
+    const scrubbed = isSensitive(key) ? CENSOR : scrub(item, depth + 1, done, deep);
+    if (scrubbed !== item) (copy ??= { ...value })[key] = scrubbed;
+  }
+  return copy ?? (Object.getPrototypeOf(value) === SERIALIZED_ERROR_PROTO ? { ...value } : value);
+}
 var createLogger = (name, level = "info") => {
-  const isDev = process.env.NODE_ENV !== "production";
-  return pino({
+  const isDev = isDevelopmentEnv();
+  const options = {
     name,
     level,
-    redact: {
-      paths: [
-        "password",
-        "*.password",
-        "pass",
-        "*.pass",
-        "apiKey",
-        "*.apiKey",
-        "*.apiSecret",
-        "token",
-        "*.token",
-        "*.authToken",
-        "secret",
-        "*.secret",
-        "config.env",
-        "*.data"
-      ],
-      censor: "[REDACTED]"
+    formatters: {
+      log: (object) => scrub(object, 0, /* @__PURE__ */ new WeakMap())
+    },
+    // The formatter above already serialized errors (scrubbed): pino's own
+    // err serializer would take that plain object for an error again and
+    // rewrite its `type` as "Object".
+    serializers: {
+      err: (value) => value instanceof Error ? scrub(value, 0, /* @__PURE__ */ new WeakMap()) : value
     },
-    ...isDev && {
-      transport: {
-        target: "pino-pretty",
-        options: {
-          colorize: true
+    hooks: {
+      // Messages are strings the formatter never sees: mask connection
+      // string passwords there too, including the message pino takes
+      // from an error logged on its own (`logger.error(err)`).
+      logMethod(args, method) {
+        const masked = args.map((arg) => typeof arg === "string" ? maskCredentials(arg) : arg);
+        if (masked[0] instanceof Error && typeof masked[1] !== "string") {
+          masked.splice(1, 0, maskCredentials(masked[0].message));
         }
+        return method.apply(this, masked);
       }
+    },
+    redact: {
+      paths: ["config.env", "*.data"],
+      censor: CENSOR
     }
-  });
+  };
+  const logger = isDev ? pino(options, pretty({ colorize: true })) : pino(options);
+  const child = logger.child;
+  logger.child = function(bindings, childOptions) {
+    return child.call(this, scrub(bindings, 0, /* @__PURE__ */ new WeakMap()), childOptions);
+  };
+  return logger;
 };
 
 // src/config/loader.ts
@@ -43,12 +150,17 @@ import { loadConfig } from "c12";
 
 // src/config/schema.ts
 import { z } from "zod";
+var RestartBackoffSchema = z.object({
+  initialMs: z.number().positive().optional(),
+  maxMs: z.number().positive().optional(),
+  factor: z.number().positive().optional()
+});
 var AppConfigSchema = z.object({
   name: z.string().default("IskraApp"),
   debug: z.boolean().default(false),
   logger: z.object({
     level: z.string().default("info")
-  }).default({}),
+  }).passthrough().default({}),
   otel: z.object({
     enabled: z.boolean().default(true),
     endpoint: z.string().default("http://localhost:4318"),
@@ -57,16 +169,40 @@ var AppConfigSchema = z.object({
     environment: z.string().optional(),
     metricIntervalMs: z.number().default(6e4),
     resourceAttributes: z.record(z.string()).optional(),
-    instrumentations: z.record(z.object({ enabled: z.boolean().optional() })).optional()
-  }).optional(),
-  processes: z.record(z.object({
-    command: z.string(),
-    args: z.array(z.string()).optional(),
-    mode: z.enum(["daemon", "oneshot", "stdio"]).default("daemon"),
-    restartOnCrash: z.boolean().default(false),
-    env: z.record(z.string()).optional()
-  })).optional()
-});
+    // passthrough: the instrumentations' own options (hooks, redactedQueryParams) were stripped.
+    instrumentations: z.record(z.object({ enabled: z.boolean().optional() }).passthrough()).optional()
+  }).passthrough().optional(),
+  shutdownSignals: z.union([z.array(z.string()), z.literal(false)]).optional(),
+  shutdownTimeoutMs: z.number().positive().optional(),
+  processes: z.record(
+    z.object({
+      command: z.string(),
+      args: z.array(z.string()).optional(),
+      mode: z.enum(["daemon", "oneshot", "stdio"]).default("daemon"),
+      restartOnCrash: z.boolean().default(false),
+      maxRestarts: z.number().int().nonnegative().optional(),
+      restartCooldown: z.number().nonnegative().optional(),
+      restartBackoff: RestartBackoffSchema.optional(),
+      env: z.record(z.string()).optional(),
+      inheritEnv: z.union([z.boolean(), z.array(z.string())]).optional(),
+      maxPendingStdinBytes: z.number().int().positive().optional()
+    }).passthrough()
+  ).optional(),
+  socket: z.object({
+    enabled: z.boolean(),
+    port: z.number().optional(),
+    adapter: z.enum(["bun", "socket.io"]).optional()
+  }).passthrough().optional(),
+  kv: z.object({
+    driver: z.enum(["memory", "redis"]),
+    connection: z.any().optional()
+  }).passthrough().optional(),
+  db: z.object({
+    driver: z.enum(["postgres", "mysql", "sqlite", "libsql"]),
+    url: z.string(),
+    authToken: z.string().optional()
+  }).passthrough().optional()
+}).passthrough();
 
 // src/config/loader.ts
 async function loadAppConfig(cwd = process.cwd()) {
@@ -74,7 +210,14 @@ async function loadAppConfig(cwd = process.cwd()) {
     name: "app",
     configFile: "app.config",
     cwd,
-    dotenv: true
+    dotenv: true,
+    // c12 would also merge a `.apprc` file from the working directory (a
+    // plain key=value file that could add `processes` to spawn or move
+    // `otel.endpoint`), and download and run `extends` layers from
+    // github:/gitlab:/https:// sources on every start. Local `extends`
+    // paths still work.
+    rcFile: false,
+    giget: false
   });
   const validConfig = AppConfigSchema.parse(config || {});
   return validConfig;
@@ -104,8 +247,14 @@ var ErrorCodes = {
   UNAUTHORIZED: "UNAUTHORIZED",
   FORBIDDEN: "FORBIDDEN",
   NOT_FOUND: "NOT_FOUND",
+  METHOD_NOT_ALLOWED: "METHOD_NOT_ALLOWED",
   CONFLICT: "CONFLICT",
+  PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE",
+  UNSUPPORTED_MEDIA_TYPE: "UNSUPPORTED_MEDIA_TYPE",
   VALIDATION_ERROR: "VALIDATION_ERROR",
+  RATE_LIMITED: "RATE_LIMITED",
+  SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
+  TIMEOUT: "TIMEOUT",
   // Data
   DATABASE_ERROR: "DATABASE_ERROR",
   CONNECTION_ERROR: "CONNECTION_ERROR",
@@ -150,7 +299,11 @@ var ConfigError = class extends IskraError {
 };
 var DriverError = class extends IskraError {
   constructor(message, options) {
-    super(message, { code: options?.code ?? ErrorCodes.DRIVER_INIT_FAILED, cause: options?.cause, context: options?.context });
+    super(message, {
+      code: options?.code ?? ErrorCodes.DRIVER_INIT_FAILED,
+      cause: options?.cause,
+      context: options?.context
+    });
     this.name = "DriverError";
   }
 };
@@ -183,6 +336,114 @@ var OTEL_MODULES = {
 function importOptional(specifier) {
   return import(specifier);
 }
+var DEFAULT_ENDPOINT = "http://localhost:4318";
+var HTTP_INSTRUMENTATION = "@opentelemetry/instrumentation-http";
+var SECRET_QUERY_PARAMS = [
+  "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"
+];
+var normalizeParam = (name) => name.toLowerCase().replace(/[-_]/g, "");
+function decodeParam(name) {
+  try {
+    return decodeURIComponent(name.replace(/\+/g, " "));
+  } catch {
+    return name;
+  }
+}
+function redactUrl(url, params = SECRET_QUERY_PARAMS) {
+  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;
+}
+var URL_ATTRIBUTES = ["url.full", "url.query", "http.url", "http.target"];
+function redactSpanUrls(span, params) {
+  const { attributes, setAttribute } = span ?? {};
+  if (!attributes || typeof setAttribute !== "function") return;
+  for (const key of URL_ATTRIBUTES) {
+    const value = attributes[key];
+    if (typeof value !== "string") continue;
+    const redacted = key === "url.query" ? redactUrl(`?${value}`, params).slice(1) : redactUrl(value, params);
+    if (redacted !== value) setAttribute.call(span, key, redacted);
+  }
+}
+function autoInstrumentationOptions(config) {
+  const http = { ...config.instrumentations?.[HTTP_INSTRUMENTATION] };
+  const list = (value) => Array.isArray(value) ? value : void 0;
+  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, request) => {
+        const outgoing = typeof request?.setHeader === "function";
+        redactSpanUrls(span, outgoing ? client : server);
+        if (typeof appHook === "function") appHook(span, request);
+      }
+    }
+  };
+}
+function isPrivateHost(hostname) {
+  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);
+}
+function describeOtelEndpoint(config) {
+  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 };
+  }
+}
+function createResource(resources, attributes) {
+  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"
+  );
+}
 async function initOtel(config, appName) {
   if (sdkInstance) return;
   try {
@@ -192,7 +453,7 @@ async function initOtel(config, appName) {
       { OTLPTraceExporter },
       { OTLPMetricExporter },
       { PeriodicExportingMetricReader },
-      { Resource },
+      resources,
       semconv
     ] = await Promise.all([
       importOptional(OTEL_MODULES.sdkNode),
@@ -204,17 +465,14 @@ async function initOtel(config, appName) {
       importOptional(OTEL_MODULES.semconv)
     ]);
     const serviceName = config.serviceName || appName;
-    const endpoint = config.endpoint || "http://localhost:4318";
-    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 endpoint = config.endpoint || DEFAULT_ENDPOINT;
+    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 = {
-      "@opentelemetry/instrumentation-fs": { enabled: false },
-      ...config.instrumentations
-    };
+    const instrumentationOverrides = autoInstrumentationOptions(config);
     const sdk = new NodeSDK({
       resource,
       traceExporter: new OTLPTraceExporter({ url: `${endpoint}/v1/traces` }),
@@ -227,7 +485,8 @@ async function initOtel(config, appName) {
     sdk.start();
     sdkInstance = sdk;
   } catch (err) {
-    if (err?.code === "ERR_MODULE_NOT_FOUND" || err?.code === "MODULE_NOT_FOUND" || err?.message?.includes("Cannot find")) {
+    const e = err;
+    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`
       );
@@ -243,12 +502,29 @@ async function shutdownOtel() {
 }
 
 // src/app.ts
+var AppContext = class extends Map {
+  get(key) {
+    return super.get(key);
+  }
+  set(key, value) {
+    return super.set(key, value);
+  }
+};
+var DEFAULT_SHUTDOWN_SIGNALS = ["SIGTERM", "SIGINT"];
+var DEFAULT_SHUTDOWN_TIMEOUT_MS = 1e4;
 var App = class {
   config;
   logger;
   events;
   drivers = [];
-  context = /* @__PURE__ */ new Map();
+  /** Drivers whose start() succeeded, in start order; null until start() runs. */
+  startedDrivers = null;
+  pendingInstalls = [];
+  /** The shutdown in progress, shared by concurrent stop() calls. */
+  stopping = null;
+  signalHandler;
+  signals = [];
+  context = new AppContext();
   constructor(config) {
     this.events = mitt();
     this.config = config || { name: "Bootstrapping", logger: { level: "info" } };
@@ -261,13 +537,32 @@ var App = class {
     }
     if (this.config.otel && this.config.otel.enabled !== false) {
       await initOtel(this.config.otel, this.config.name);
-      this.logger.info({ endpoint: this.config.otel.endpoint }, "OpenTelemetry initialized");
+      const { origin, plaintext } = describeOtelEndpoint(this.config.otel);
+      this.logger.info({ endpoint: origin }, "OpenTelemetry initialized");
+      if (plaintext) {
+        this.logger.warn(
+          { endpoint: origin },
+          "OpenTelemetry endpoint is plain http:// on a remote host: spans (URLs, captured headers) travel unencrypted; use https://"
+        );
+      }
     }
     this.logger.info("Initializing App...");
+    await Promise.all(this.pendingInstalls);
+    this.pendingInstalls = [];
+    const initialized = [];
     for (const driver of this.drivers) {
-      if (driver.init) {
-        this.logger.debug(`Initializing driver: ${driver.name}`);
+      if (!driver.init) continue;
+      this.logger.debug(`Initializing driver: ${driver.name}`);
+      initialized.push(driver);
+      try {
         await driver.init(this);
+      } catch (err) {
+        this.logger.error(
+          { err, driver: driver.name },
+          "Driver failed to initialize; stopping the drivers already initialized"
+        );
+        await this.rollback(initialized.reverse());
+        throw err;
       }
     }
   }
@@ -276,7 +571,13 @@ var App = class {
     return this;
   }
   use(plugin) {
-    plugin.install(this);
+    const result = plugin.install(this);
+    if (result && typeof result.then === "function") {
+      const install = Promise.resolve(result);
+      install.catch(() => {
+      });
+      this.pendingInstalls.push(install);
+    }
     return this;
   }
   on(event, handler) {
@@ -298,39 +599,202 @@ var App = class {
   emit(event, payload) {
     this.events.emit(event, payload);
   }
+  /**
+   * Starts drivers one at a time, in registration order, so a driver can rely
+   * on the ones registered before it (e.g. the DB before the web server). If
+   * one fails, every driver is stopped in reverse order (all were initialized
+   * and may hold connections, including the failing one), OpenTelemetry is
+   * shut down and the error is rethrown, instead of leaving ports bound and
+   * children running.
+   */
   async start() {
     await this.init();
+    if (!nodeEnv()) {
+      this.logger.warn(
+        "NODE_ENV is not set: production defaults apply (Secure cookies, no sample secrets, JSON logs). Set NODE_ENV=development for local development."
+      );
+    }
     this.logger.info("Starting drivers...");
-    await Promise.all(this.drivers.map((d) => d.start ? d.start() : Promise.resolve()));
+    const started = [];
+    for (const driver of this.drivers) {
+      try {
+        if (driver.start) await driver.start();
+        started.push(driver);
+      } catch (err) {
+        this.logger.error({ err, driver: driver.name }, "Driver failed to start; stopping every driver");
+        await this.rollback([...this.drivers].reverse());
+        throw err;
+      }
+    }
+    this.startedDrivers = started;
+    this.installSignalHandlers();
     this.logger.info("App started successfully \u{1F680}");
   }
-  async stop() {
+  /**
+   * Stops drivers in reverse start order (the web server before the DB it
+   * uses), continuing past failures, and always flushes OpenTelemetry.
+   *
+   * A call made while a stop is in progress (e.g. an app's own signal
+   * handler next to the App's) gets that same stop: it resolves only once
+   * every driver has stopped, instead of right away with nothing left to do.
+   */
+  stop() {
+    this.stopping ??= this.stopOnce().finally(() => {
+      this.stopping = null;
+    });
+    return this.stopping;
+  }
+  async stopOnce() {
     this.logger.info("Stopping app...");
-    const results = await Promise.allSettled(this.drivers.map((d) => d.stop ? d.stop() : Promise.resolve()));
-    const failures = results.filter((r) => r.status === "rejected");
+    const toStop = [...this.startedDrivers ?? this.drivers].reverse();
+    this.startedDrivers = [];
+    let failures;
+    try {
+      failures = await this.stopDrivers(toStop);
+    } finally {
+      await shutdownOtel();
+      this.removeSignalHandlers();
+    }
     if (failures.length > 0) {
       this.logger.error({ failures }, "Some drivers failed to stop");
       throw new LifecycleError("Some drivers failed to stop", {
         failures,
-        context: { driverCount: this.drivers.length, failedCount: failures.length }
+        context: { driverCount: toStop.length, failedCount: failures.length }
       });
     }
-    await shutdownOtel();
     this.logger.info("App stopped.");
   }
+  /**
+   * Stops `drivers` after a failed init() or start() and shuts down
+   * OpenTelemetry. Failures to stop are logged, not thrown: the caller
+   * rethrows the original error. A later stop() stops nothing more.
+   */
+  async rollback(drivers) {
+    this.startedDrivers = [];
+    await this.stopDrivers(drivers);
+    try {
+      await shutdownOtel();
+    } catch (err) {
+      this.logger.error({ err }, "OpenTelemetry failed to shut down");
+    }
+  }
+  async stopDrivers(drivers) {
+    const failures = [];
+    for (const driver of drivers) {
+      try {
+        if (driver.stop) await driver.stop();
+      } catch (reason) {
+        this.logger.error({ err: reason, driver: driver.name }, "Driver failed to stop");
+        failures.push({ status: "rejected", reason });
+      }
+    }
+    return failures;
+  }
+  /**
+   * Stops the app gracefully on SIGTERM/SIGINT (configurable with
+   * `shutdownSignals`, off by default under NODE_ENV=test). Once a listener
+   * exists the runtime no longer exits on its own, so the handler exits with
+   * 0 after a clean stop, or 1 on failure / after `shutdownTimeoutMs`. A
+   * second signal forces exit.
+   */
+  installSignalHandlers() {
+    const configured = this.config.shutdownSignals;
+    const signals = configured === false ? [] : configured ?? (nodeEnv() === "test" ? [] : DEFAULT_SHUTDOWN_SIGNALS);
+    if (signals.length === 0 || this.signalHandler) return;
+    const timeoutMs = this.config.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
+    let shuttingDown = false;
+    this.signalHandler = (signal) => {
+      if (shuttingDown) {
+        this.logger.warn({ signal }, "Second shutdown signal; exiting immediately");
+        process.exit(1);
+      }
+      shuttingDown = true;
+      this.logger.info({ signal }, "Shutdown signal received; stopping app");
+      const timer = setTimeout(() => {
+        this.logger.error({ timeoutMs }, "Graceful shutdown timed out; exiting");
+        process.exit(1);
+      }, timeoutMs);
+      this.stop().then(
+        () => {
+          clearTimeout(timer);
+          process.exit(0);
+        },
+        (err) => {
+          clearTimeout(timer);
+          this.logger.error({ err }, "Graceful shutdown failed");
+          process.exit(1);
+        }
+      );
+    };
+    this.signals = signals;
+    for (const signal of this.signals) process.on(signal, this.signalHandler);
+  }
+  removeSignalHandlers() {
+    if (!this.signalHandler) return;
+    for (const signal of this.signals) process.off(signal, this.signalHandler);
+    this.signalHandler = void 0;
+    this.signals = [];
+  }
 };
+
+// src/traced.ts
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+function fail(span, error) {
+  span.recordException(error instanceof Error ? error : new Error(String(error)));
+  span.setStatus({ code: SpanStatusCode.ERROR, message: error instanceof Error ? error.name : "Error" });
+}
+function traced(name, fn, options = {}) {
+  return function(...args) {
+    const tracer = options.tracer ?? trace.getTracer("iskra");
+    return tracer.startActiveSpan(name, { attributes: options.attributes }, (span) => {
+      let result;
+      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) => {
+            fail(span, error);
+            span.end();
+            throw error;
+          }
+        );
+      }
+      span.end();
+      return result;
+    });
+  };
+}
 export {
   App,
   AppConfigSchema,
+  AppContext,
   ConfigError,
   DriverError,
   ErrorCodes,
   IskraError,
   LifecycleError,
   PluginError,
+  SECRET_QUERY_PARAMS,
+  autoInstrumentationOptions,
   createLogger,
+  createResource,
+  describeOtelEndpoint,
   initOtel,
+  isDevelopmentEnv,
+  isProductionEnv,
   loadAppConfig,
-  shutdownOtel
+  nodeEnv,
+  redactUrl,
+  shutdownOtel,
+  traced
 };
 //# sourceMappingURL=index.js.map