@fulmenhq/tsfulmen 0.3.2 → 0.4.0

package/dist/chunk-K2FYT43R.js

@@ -0,0 +1,837 @@
+import { createLogger } from './chunk-5HZEJGZ5.js';
+import { FulmenError } from './chunk-CW4CSNVF.js';
+import { metrics, isHistogramSummary } from './chunk-7SVYOPJ3.js';
+import { createServer } from 'http';
+
+// src/telemetry/prometheus/constants.ts
+var ADR0007_BUCKETS_MS = [1, 5, 10, 50, 100, 500, 1e3, 5e3, 1e4];
+var ADR0007_BUCKETS_SECONDS = [
+  1e-3,
+  5e-3,
+  0.01,
+  0.05,
+  0.1,
+  0.5,
+  1,
+  5,
+  10
+];
+function msToSeconds(ms) {
+  return ms / 1e3;
+}
+var PROMETHEUS_EXPORTER_METRICS = {
+  // Refresh metrics
+  REFRESH_DURATION_SECONDS: "prometheus_exporter_refresh_duration_seconds",
+  REFRESH_TOTAL: "prometheus_exporter_refresh_total",
+  REFRESH_ERRORS_TOTAL: "prometheus_exporter_refresh_errors_total",
+  REFRESH_INFLIGHT: "prometheus_exporter_refresh_inflight",
+  // HTTP metrics
+  HTTP_REQUESTS_TOTAL: "prometheus_exporter_http_requests_total",
+  HTTP_ERRORS_TOTAL: "prometheus_exporter_http_errors_total",
+  // Restart metrics
+  RESTARTS_TOTAL: "prometheus_exporter_restarts_total"
+};
+var FOUNDRY_METRICS = {
+  // MIME detection counters
+  MIME_DETECTIONS_JSON: "foundry_mime_detections_total_json",
+  MIME_DETECTIONS_XML: "foundry_mime_detections_total_xml",
+  MIME_DETECTIONS_YAML: "foundry_mime_detections_total_yaml",
+  MIME_DETECTIONS_CSV: "foundry_mime_detections_total_csv",
+  MIME_DETECTIONS_PLAIN_TEXT: "foundry_mime_detections_total_plain_text",
+  MIME_DETECTIONS_UNKNOWN: "foundry_mime_detections_total_unknown",
+  // MIME detection timing histograms
+  MIME_DETECTION_MS_JSON: "foundry_mime_detection_ms_json",
+  MIME_DETECTION_MS_XML: "foundry_mime_detection_ms_xml",
+  MIME_DETECTION_MS_YAML: "foundry_mime_detection_ms_yaml",
+  MIME_DETECTION_MS_CSV: "foundry_mime_detection_ms_csv",
+  MIME_DETECTION_MS_PLAIN_TEXT: "foundry_mime_detection_ms_plain_text",
+  MIME_DETECTION_MS_UNKNOWN: "foundry_mime_detection_ms_unknown",
+  // General lookup counter
+  LOOKUP_COUNT: "foundry_lookup_count"
+};
+var ERROR_HANDLING_METRICS = {
+  WRAPS_TOTAL: "error_handling_wraps_total",
+  WRAP_MS: "error_handling_wrap_ms"
+};
+var FULHASH_METRICS = {
+  // Algorithm-specific counters
+  OPERATIONS_XXH3_128: "fulhash_operations_total_xxh3_128",
+  OPERATIONS_SHA256: "fulhash_operations_total_sha256",
+  // General counters
+  HASH_STRING_TOTAL: "fulhash_hash_string_total",
+  BYTES_HASHED_TOTAL: "fulhash_bytes_hashed_total",
+  // Timing histogram
+  OPERATION_MS: "fulhash_operation_ms"
+};
+var EXPORTER_LABELS = {
+  // Refresh phases
+  PHASE_COLLECT: "collect",
+  PHASE_CONVERT: "convert",
+  PHASE_EXPORT: "export",
+  // Results
+  RESULT_SUCCESS: "success",
+  RESULT_ERROR: "error",
+  // Error types
+  ERROR_VALIDATION: "validation",
+  ERROR_IO: "io",
+  ERROR_TIMEOUT: "timeout",
+  ERROR_OTHER: "other",
+  // Restart reasons
+  REASON_CONFIG_CHANGE: "config_change",
+  REASON_ERROR: "error",
+  REASON_MANUAL: "manual",
+  REASON_OTHER: "other"
+};
+
+// src/telemetry/prometheus/errors.ts
+var PrometheusExporterError = class extends FulmenError {
+  constructor(message, options) {
+    super({
+      code: options?.code || "PROMETHEUS_EXPORTER_ERROR",
+      message,
+      severity: "medium",
+      context: options?.context
+    });
+    if (options?.cause) {
+      this.cause = options.cause;
+    }
+    this.name = "PrometheusExporterError";
+  }
+};
+var PromClientNotFoundError = class extends PrometheusExporterError {
+  constructor(cause) {
+    super(
+      "prom-client peer dependency not found. Install with: bun add prom-client\nFor npm: npm install prom-client\nFor more information, see: https://github.com/siimon/prom-client",
+      {
+        code: "PROM_CLIENT_NOT_FOUND",
+        cause,
+        context: {
+          suggestion: 'Run "bun add prom-client" to install the required peer dependency'
+        }
+      }
+    );
+    this.name = "PromClientNotFoundError";
+  }
+};
+var InvalidMetricNameError = class extends PrometheusExporterError {
+  constructor(metricName, reason) {
+    super(`Invalid Prometheus metric name: "${metricName}". ${reason}`, {
+      code: "INVALID_METRIC_NAME",
+      context: {
+        metricName,
+        reason,
+        suggestion: "Prometheus metric names must match: [a-zA-Z_:][a-zA-Z0-9_:]*\nSee: https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels"
+      }
+    });
+    this.name = "InvalidMetricNameError";
+  }
+};
+var InvalidLabelNameError = class extends PrometheusExporterError {
+  constructor(labelName, reason) {
+    super(`Invalid Prometheus label name: "${labelName}". ${reason}`, {
+      code: "INVALID_LABEL_NAME",
+      context: {
+        labelName,
+        reason,
+        suggestion: "Prometheus label names must match: [a-zA-Z_][a-zA-Z0-9_]*\nSee: https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels"
+      }
+    });
+    this.name = "InvalidLabelNameError";
+  }
+};
+var MetricRegistrationError = class extends PrometheusExporterError {
+  constructor(metricName, cause) {
+    super(`Failed to register Prometheus metric: "${metricName}"`, {
+      code: "METRIC_REGISTRATION_FAILED",
+      cause,
+      context: {
+        metricName,
+        suggestion: "Check for duplicate metric names or incompatible collector types"
+      }
+    });
+    this.name = "MetricRegistrationError";
+  }
+};
+var RefreshError = class extends PrometheusExporterError {
+  constructor(cause, context) {
+    super("Failed to refresh Prometheus metrics from TelemetryRegistry", {
+      code: "REFRESH_FAILED",
+      cause,
+      context
+    });
+    this.name = "RefreshError";
+  }
+};
+
+// src/telemetry/prometheus/exporter.ts
+var PrometheusExporter = class {
+  telemetryRegistry;
+  namespace;
+  subsystem;
+  defaultLabels;
+  helpText;
+  metricsEnabled;
+  recordClientLabel;
+  moduleMetricsEnabled;
+  // prom-client types unavailable at compile time (optional peer dependency)
+  // Using 'any' with runtime validation - see file header comment for rationale
+  // biome-ignore lint/suspicious/noExplicitAny: prom-client is optional peer dependency
+  promClient = null;
+  // biome-ignore lint/suspicious/noExplicitAny: prom-client Registry type unavailable at compile time
+  promRegistry = null;
+  // biome-ignore lint/suspicious/noExplicitAny: prom-client Counter type unavailable at compile time
+  counters = /* @__PURE__ */ new Map();
+  // biome-ignore lint/suspicious/noExplicitAny: prom-client Gauge type unavailable at compile time
+  gauges = /* @__PURE__ */ new Map();
+  // biome-ignore lint/suspicious/noExplicitAny: prom-client Histogram type unavailable at compile time
+  histograms = /* @__PURE__ */ new Map();
+  // Statistics
+  refreshCount = 0;
+  errorCount = 0;
+  lastRefreshTime = null;
+  // Background refresh loop
+  refreshInterval = null;
+  refreshPromise = null;
+  isRefreshing = false;
+  /**
+   * Create Prometheus exporter
+   *
+   * @param options - Exporter configuration
+   * @throws {InvalidLabelNameError} If default label names are invalid
+   */
+  constructor(options = {}) {
+    this.telemetryRegistry = options.registry || metrics;
+    this.defaultLabels = options.defaultLabels || {};
+    this.helpText = options.helpText || {};
+    this.metricsEnabled = options.metricsEnabled ?? true;
+    this.recordClientLabel = options.recordClientLabel ?? false;
+    this.moduleMetricsEnabled = options.moduleMetricsEnabled ?? true;
+    for (const labelName of Object.keys(this.defaultLabels)) {
+      this.validateLabelName(labelName);
+    }
+    this.namespace = options.namespace || "tsfulmen";
+    this.subsystem = options.subsystem || "app";
+  }
+  /**
+   * Initialize exporter (async setup)
+   *
+   * Loads prom-client and optionally loads App Identity for namespace/subsystem.
+   * Called automatically on first refresh() or getMetrics() call.
+   *
+   * @throws {PromClientNotFoundError} If prom-client not installed
+   */
+  async init() {
+    if (this.promClient) {
+      return;
+    }
+    try {
+      this.promClient = await import('./prom-client-PNEBGD3G.js');
+      this.promRegistry = new this.promClient.Registry();
+    } catch (err) {
+      throw new PromClientNotFoundError(err);
+    }
+    if (this.namespace === "tsfulmen" || this.subsystem === "app") {
+      try {
+        const { loadIdentity } = await import('./appidentity/index.js');
+        const identity = await loadIdentity({ skipValidation: true });
+        if (this.namespace === "tsfulmen" && identity.app.vendor) {
+          this.namespace = identity.app.vendor;
+        }
+        if (this.subsystem === "app" && identity.app.binary_name) {
+          this.subsystem = identity.app.binary_name;
+        }
+      } catch {
+      }
+    }
+  }
+  /**
+   * Safely emit instrumentation metric (silently fails if registry doesn't support it)
+   * Used to avoid breaking tests that use mock registries
+   */
+  safeInstrument(fn) {
+    try {
+      fn();
+    } catch {
+    }
+  }
+  /**
+   * Refresh metrics from TelemetryRegistry
+   *
+   * Exports current metrics from TelemetryRegistry and updates Prometheus collectors.
+   * Emits instrumentation metrics per Crucible v0.2.7 taxonomy.
+   *
+   * @throws {RefreshError} If refresh operation fails. Inspect `error.cause` for the
+   * underlying error (InvalidMetricNameError, MetricRegistrationError, etc.) to handle
+   * specific failure conditions.
+   */
+  async refresh() {
+    const startTime = performance.now();
+    this.safeInstrument(() => {
+      this.telemetryRegistry.gauge(PROMETHEUS_EXPORTER_METRICS.REFRESH_INFLIGHT).set(1);
+    });
+    try {
+      await this.init();
+      const events = await this.telemetryRegistry.export();
+      for (const event of events) {
+        this.updateCollector(event);
+      }
+      this.refreshCount++;
+      this.lastRefreshTime = (/* @__PURE__ */ new Date()).toISOString();
+      const durationMs = performance.now() - startTime;
+      this.safeInstrument(() => {
+        this.telemetryRegistry.counter(PROMETHEUS_EXPORTER_METRICS.REFRESH_TOTAL).inc(1, { result: EXPORTER_LABELS.RESULT_SUCCESS });
+        this.telemetryRegistry.histogram(PROMETHEUS_EXPORTER_METRICS.REFRESH_DURATION_SECONDS, {
+          buckets: [...ADR0007_BUCKETS_SECONDS]
+        }).observe(msToSeconds(durationMs), {
+          phase: EXPORTER_LABELS.PHASE_EXPORT,
+          result: EXPORTER_LABELS.RESULT_SUCCESS
+        });
+      });
+    } catch (err) {
+      this.errorCount++;
+      const durationMs = performance.now() - startTime;
+      let errorType = EXPORTER_LABELS.ERROR_OTHER;
+      if (err instanceof InvalidMetricNameError || err instanceof InvalidLabelNameError) {
+        errorType = EXPORTER_LABELS.ERROR_VALIDATION;
+      } else if (err instanceof MetricRegistrationError) {
+        errorType = EXPORTER_LABELS.ERROR_OTHER;
+      }
+      this.safeInstrument(() => {
+        this.telemetryRegistry.counter(PROMETHEUS_EXPORTER_METRICS.REFRESH_TOTAL).inc(1, { result: EXPORTER_LABELS.RESULT_ERROR });
+        this.telemetryRegistry.counter(PROMETHEUS_EXPORTER_METRICS.REFRESH_ERRORS_TOTAL).inc(1, { error_type: errorType });
+        this.telemetryRegistry.histogram(PROMETHEUS_EXPORTER_METRICS.REFRESH_DURATION_SECONDS, {
+          buckets: [...ADR0007_BUCKETS_SECONDS]
+        }).observe(msToSeconds(durationMs), {
+          phase: EXPORTER_LABELS.PHASE_EXPORT,
+          result: EXPORTER_LABELS.RESULT_ERROR
+        });
+      });
+      throw new RefreshError(err, {
+        refreshCount: this.refreshCount,
+        errorCount: this.errorCount
+      });
+    } finally {
+      this.safeInstrument(() => {
+        this.telemetryRegistry.gauge(PROMETHEUS_EXPORTER_METRICS.REFRESH_INFLIGHT).set(0);
+      });
+    }
+  }
+  /**
+   * Get Prometheus metrics in text format
+   *
+   * Returns metrics in Prometheus exposition text format.
+   *
+   * @returns Prometheus text format string
+   */
+  async getMetrics() {
+    await this.init();
+    if (!this.promRegistry) {
+      throw new Error("Prometheus registry not initialized");
+    }
+    return this.promRegistry.metrics();
+  }
+  /**
+   * Get exporter statistics
+   */
+  getStats() {
+    return {
+      refreshCount: this.refreshCount,
+      errorCount: this.errorCount,
+      lastRefreshTime: this.lastRefreshTime,
+      metricsCount: this.counters.size + this.gauges.size + this.histograms.size,
+      isRefreshing: this.isRefreshing
+    };
+  }
+  /**
+   * Get current metrics configuration
+   *
+   * Returns effective configuration being used by exporter,
+   * including defaults for any unspecified options.
+   *
+   * @returns Current metrics configuration
+   */
+  getMetricsConfig() {
+    return {
+      metricsEnabled: this.metricsEnabled,
+      recordClientLabel: this.recordClientLabel,
+      moduleMetricsEnabled: this.moduleMetricsEnabled,
+      namespace: this.namespace,
+      subsystem: this.subsystem,
+      defaultLabels: { ...this.defaultLabels },
+      helpText: { ...this.helpText }
+    };
+  }
+  /**
+   * Get underlying prom-client Registry
+   *
+   * Returns null if not yet initialized.
+   * Use for advanced prom-client operations.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: Returns prom-client Registry type (optional peer dependency)
+  getRegistry() {
+    return this.promRegistry;
+  }
+  /**
+   * Get telemetry registry for self-instrumentation
+   *
+   * Returns the MetricsRegistry instance used for exporter self-instrumentation.
+   * Useful for HTTP handler instrumentation.
+   *
+   * @internal
+   */
+  getTelemetryRegistry() {
+    return this.telemetryRegistry;
+  }
+  /**
+   * Emit restart metric
+   *
+   * Records a restart event for tracking exporter or server restarts.
+   * Use this when restarting the HTTP metrics server or other exporter components.
+   *
+   * @param reason - Reason for restart (config_change, error, manual, other)
+   *
+   * @example
+   * ```typescript
+   * // Restart server after config change
+   * await stopMetricsServer(server);
+   * exporter.recordRestart('config_change');
+   * const newServer = await startMetricsServer(exporter, newConfig);
+   * ```
+   */
+  recordRestart(reason) {
+    this.safeInstrument(() => {
+      this.telemetryRegistry.counter(PROMETHEUS_EXPORTER_METRICS.RESTARTS_TOTAL).inc(1, { reason });
+    });
+  }
+  /**
+   * Reset all metrics
+   */
+  reset() {
+    if (this.promRegistry) {
+      this.promRegistry.clear();
+    }
+    this.counters.clear();
+    this.gauges.clear();
+    this.histograms.clear();
+  }
+  /**
+   * Start background refresh loop
+   *
+   * Automatically refreshes metrics from TelemetryRegistry at specified interval.
+   * Useful for long-running services where metrics should be continuously updated.
+   *
+   * @param options - Refresh configuration (interval, error handler)
+   *
+   * @example
+   * ```typescript
+   * const exporter = new PrometheusExporter({ registry: metrics });
+   *
+   * // Start refreshing every 15 seconds (default)
+   * exporter.startRefresh();
+   *
+   * // Custom interval and error handling
+   * exporter.startRefresh({
+   *   intervalMs: 10000,
+   *   onError: (err) => logger.error('Refresh failed:', err)
+   * });
+   * ```
+   */
+  startRefresh(options = {}) {
+    const intervalMs = options.intervalMs ?? 15e3;
+    !!this.refreshInterval;
+    if (this.refreshInterval) {
+      this.stopRefresh();
+      this.safeInstrument(() => {
+        this.telemetryRegistry.counter(PROMETHEUS_EXPORTER_METRICS.RESTARTS_TOTAL).inc(1, {
+          reason: options.restartReason || EXPORTER_LABELS.REASON_OTHER
+        });
+      });
+    }
+    this.refreshInterval = setInterval(() => {
+      if (this.refreshPromise) {
+        return;
+      }
+      this.refreshPromise = this.refresh().catch((err) => {
+        if (options.onError) {
+          options.onError(err);
+        }
+      }).finally(() => {
+        this.refreshPromise = null;
+      });
+    }, intervalMs);
+    this.isRefreshing = true;
+  }
+  /**
+   * Stop background refresh loop
+   *
+   * Clears the refresh interval and performs one final refresh to capture
+   * the latest metrics state before stopping.
+   *
+   * @example
+   * ```typescript
+   * // Graceful shutdown
+   * await exporter.stopRefresh();
+   * ```
+   */
+  async stopRefresh() {
+    if (this.refreshInterval) {
+      clearInterval(this.refreshInterval);
+      this.refreshInterval = null;
+    }
+    if (this.refreshPromise) {
+      await this.refreshPromise;
+    }
+    try {
+      await this.refresh();
+    } catch (_err) {
+    }
+    this.isRefreshing = false;
+  }
+  /**
+   * Update Prometheus collector from MetricsEvent
+   */
+  updateCollector(event) {
+    const metricName = this.formatMetricName(event.name);
+    const help = this.getHelpText(event.name);
+    const labelNames = Object.keys(this.defaultLabels);
+    if (isHistogramSummary(event.value)) {
+      this.updateHistogram(metricName, help, labelNames, event.value);
+    } else if (typeof event.value === "number") {
+      this.updateGauge(metricName, help, labelNames, event.value);
+    }
+  }
+  /**
+   * Update or create Prometheus Gauge
+   */
+  updateGauge(name, help, labelNames, value) {
+    let gauge = this.gauges.get(name);
+    if (!gauge) {
+      try {
+        gauge = new this.promClient.Gauge({
+          name,
+          help,
+          labelNames,
+          registers: [this.promRegistry]
+        });
+        this.gauges.set(name, gauge);
+      } catch (err) {
+        throw new MetricRegistrationError(name, err);
+      }
+    }
+    gauge.labels(this.defaultLabels).set(value);
+  }
+  /**
+   * Update or create Prometheus Histogram
+   *
+   * CRITICAL: Converts OTLP cumulative buckets to Prometheus format.
+   * This is an approximation - see Phase 0 investigation for details.
+   *
+   * LIMITATION: Original observations cannot be perfectly reconstructed from bucket summary.
+   * Percentiles will be approximate based on bucket midpoints.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: summary is HistogramSummary from TelemetryRegistry
+  updateHistogram(name, help, labelNames, summary) {
+    const buckets = summary.buckets.map((b) => b.le);
+    let histogram = this.histograms.get(name);
+    if (!histogram) {
+      try {
+        histogram = new this.promClient.Histogram({
+          name,
+          help,
+          labelNames,
+          buckets,
+          registers: [this.promRegistry]
+        });
+        this.histograms.set(name, histogram);
+      } catch (err) {
+        throw new MetricRegistrationError(name, err);
+      }
+    }
+    const observations = this.reconstructObservations(summary);
+    for (const value of observations) {
+      histogram.labels(this.defaultLabels).observe(value);
+    }
+  }
+  /**
+   * Reconstruct observations from histogram summary
+   *
+   * Converts OTLP cumulative bucket counts to approximate observation values.
+   * Uses bucket midpoints to generate synthetic observations.
+   *
+   * LIMITATION: This is an approximation. Original observation values cannot be
+   * perfectly reconstructed from bucket summaries. Percentiles will be approximate
+   * based on bucket boundaries. This is acceptable for v0.1.8 initial release.
+   *
+   * TODO: Future enhancement - capture raw observations in TelemetryRegistry
+   * for lossless Prometheus export. Track in Phase 2+ planning.
+   * See: .plans/active/v0.2.x-plans/prometheus-type-safety-enhancement.md
+   *
+   * Algorithm:
+   * 1. Calculate non-cumulative count for each bucket (delta between adjacent buckets)
+   * 2. For each bucket, place observations at the midpoint between bucket boundaries
+   * 3. Return array of synthetic observation values
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: summary is HistogramSummary from TelemetryRegistry
+  reconstructObservations(summary) {
+    const observations = [];
+    const buckets = summary.buckets;
+    if (!buckets || buckets.length === 0) {
+      return observations;
+    }
+    let prevCount = 0;
+    for (let i = 0; i < buckets.length; i++) {
+      const bucket = buckets[i];
+      const count = bucket.count - prevCount;
+      if (count > 0) {
+        let value;
+        if (i === 0) {
+          value = bucket.le / 2;
+        } else {
+          const prevLe = buckets[i - 1].le;
+          value = (prevLe + bucket.le) / 2;
+        }
+        for (let j = 0; j < count; j++) {
+          observations.push(value);
+        }
+      }
+      prevCount = bucket.count;
+    }
+    return observations;
+  }
+  /**
+   * Format metric name with namespace and subsystem prefix
+   *
+   * Format: {namespace}_{subsystem}_{metric}
+   * Example: fulmen_myapp_schema_validations
+   */
+  formatMetricName(name) {
+    this.validateMetricName(name);
+    return `${this.namespace}_${this.subsystem}_${name}`;
+  }
+  /**
+   * Get help text for metric
+   *
+   * Uses custom help text if provided, otherwise generates default.
+   */
+  getHelpText(name) {
+    if (this.helpText[name]) {
+      return this.helpText[name];
+    }
+    return `TSFulmen metric: ${name}`;
+  }
+  /**
+   * Validate Prometheus metric name
+   *
+   * Rules: Must start with [a-zA-Z_:] and contain only [a-zA-Z0-9_:]
+   *
+   * @throws {InvalidMetricNameError} If name is invalid
+   */
+  validateMetricName(name) {
+    const validPattern = /^[a-zA-Z_:][a-zA-Z0-9_:]*$/;
+    if (!validPattern.test(name)) {
+      throw new InvalidMetricNameError(
+        name,
+        "Metric names must start with [a-zA-Z_:] and contain only [a-zA-Z0-9_:]"
+      );
+    }
+  }
+  /**
+   * Validate Prometheus label name
+   *
+   * Rules: Must start with [a-zA-Z_] and contain only [a-zA-Z0-9_]
+   *
+   * @throws {InvalidLabelNameError} If name is invalid
+   */
+  validateLabelName(name) {
+    const validPattern = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+    if (!validPattern.test(name)) {
+      throw new InvalidLabelNameError(
+        name,
+        "Label names must start with [a-zA-Z_] and contain only [a-zA-Z0-9_]"
+      );
+    }
+  }
+};
+
+// src/telemetry/prometheus/lifecycle.ts
+async function registerPrometheusShutdown(exporter, manager) {
+  const shutdownHandler = async () => {
+    await exporter.stopRefresh();
+  };
+  await manager.register("SIGTERM", shutdownHandler);
+  await manager.register("SIGINT", shutdownHandler);
+}
+function safeInstrumentHTTP(registry, fn) {
+  if (!registry) return;
+  try {
+    fn();
+  } catch {
+  }
+}
+function getExporterLogger(exporter) {
+  const exporterAny = exporter;
+  const logger = exporterAny.logger;
+  return exporterAny.metricsEnabled ? logger : null;
+}
+function extractRequestContext(req) {
+  return {
+    method: req.method,
+    url: req.url,
+    headers: req.headers,
+    remoteAddress: req.socket.remoteAddress
+  };
+}
+function createMetricsHandler(exporter, options = {}) {
+  const path = options.path ?? "/metrics";
+  const refreshOnScrape = options.refreshOnScrape ?? false;
+  const logger = getExporterLogger(exporter);
+  return async (req, res) => {
+    const telemetryRegistry = exporter.getTelemetryRegistry();
+    let _statusCode = 200;
+    const startTime = performance.now();
+    try {
+      const context = extractRequestContext(req);
+      if (req.url !== path) {
+        _statusCode = 404;
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not Found");
+        safeInstrumentHTTP(telemetryRegistry, () => {
+          telemetryRegistry.counter(PROMETHEUS_EXPORTER_METRICS.HTTP_REQUESTS_TOTAL).inc(1, { status: "404", path: req.url || "unknown" });
+        });
+        return;
+      }
+      if (options.authenticate) {
+        const authResult = await options.authenticate(context);
+        if (!authResult) {
+          _statusCode = 401;
+          res.writeHead(401, {
+            "Content-Type": "text/plain",
+            "WWW-Authenticate": "Bearer"
+          });
+          res.end("Unauthorized");
+          safeInstrumentHTTP(telemetryRegistry, () => {
+            telemetryRegistry.counter(PROMETHEUS_EXPORTER_METRICS.HTTP_REQUESTS_TOTAL).inc(1, { status: "401", path });
+            telemetryRegistry.counter(PROMETHEUS_EXPORTER_METRICS.HTTP_ERRORS_TOTAL).inc(1, { status: "401", path });
+          });
+          return;
+        }
+      }
+      if (options.rateLimit) {
+        const rateLimitResult = await options.rateLimit(context);
+        if (!rateLimitResult) {
+          _statusCode = 429;
+          res.writeHead(429, {
+            "Content-Type": "text/plain",
+            "Retry-After": "60"
+          });
+          res.end("Too Many Requests");
+          safeInstrumentHTTP(telemetryRegistry, () => {
+            telemetryRegistry.counter(PROMETHEUS_EXPORTER_METRICS.HTTP_REQUESTS_TOTAL).inc(1, { status: "429", path });
+          });
+          return;
+        }
+      }
+      if (refreshOnScrape) {
+        await exporter.refresh();
+      }
+      const metrics2 = await exporter.getMetrics();
+      _statusCode = 200;
+      res.writeHead(200, {
+        "Content-Type": "text/plain; version=0.0.4; charset=utf-8",
+        "Content-Length": Buffer.byteLength(metrics2, "utf-8")
+      });
+      res.end(metrics2);
+      safeInstrumentHTTP(telemetryRegistry, () => {
+        telemetryRegistry.counter(PROMETHEUS_EXPORTER_METRICS.HTTP_REQUESTS_TOTAL).inc(1, { status: "200", path });
+      });
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : "Internal Server Error";
+      _statusCode = 500;
+      res.writeHead(500, { "Content-Type": "text/plain" });
+      res.end(`Error: ${errorMessage}`);
+      safeInstrumentHTTP(telemetryRegistry, () => {
+        telemetryRegistry.counter(PROMETHEUS_EXPORTER_METRICS.HTTP_REQUESTS_TOTAL).inc(1, { status: "500", path });
+        telemetryRegistry.counter(PROMETHEUS_EXPORTER_METRICS.HTTP_ERRORS_TOTAL).inc(1, { status: "500", path });
+      });
+    } finally {
+      if (logger) {
+        const durationMs = performance.now() - startTime;
+        const context = extractRequestContext(req);
+        logger.info("HTTP request processed", {
+          metric_name: PROMETHEUS_EXPORTER_METRICS.HTTP_REQUESTS_TOTAL,
+          status: _statusCode.toString(),
+          path: req.url || "unknown",
+          method: context.method || "GET",
+          duration_ms: Math.round(durationMs),
+          remote_address: context.remoteAddress
+        });
+      }
+    }
+  };
+}
+async function startMetricsServer(exporter, options = {}) {
+  const host = options.host ?? "127.0.0.1";
+  const port = options.port ?? 9464;
+  const path = options.path ?? "/metrics";
+  const handler = createMetricsHandler(exporter, options);
+  const server = createServer(handler);
+  const exporterLogger = getExporterLogger(exporter);
+  const logger = exporterLogger || createLogger({
+    service: "prometheus_exporter",
+    profile: "structured" /* STRUCTURED */
+  });
+  return new Promise((resolve, reject) => {
+    server.listen(port, host, () => {
+      logger.info("Prometheus metrics server started", {
+        host,
+        port,
+        path,
+        url: `http://${host}:${port}${path}`
+      });
+      resolve(server);
+    });
+    server.on("error", (err) => {
+      logger.error("Prometheus metrics server error", err, {
+        host,
+        port,
+        path
+      });
+      reject(err);
+    });
+  });
+}
+async function stopMetricsServer(server, timeoutMs = 5e3, exporter) {
+  const exporterLogger = exporter ? getExporterLogger(exporter) : null;
+  const logger = exporterLogger || createLogger({
+    service: "prometheus_exporter",
+    profile: "structured" /* STRUCTURED */
+  });
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      logger.warn("Prometheus metrics server shutdown timed out, forcing close", {
+        timeout_ms: timeoutMs
+      });
+      server.closeAllConnections?.();
+      reject(new Error(`Server shutdown timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+    server.close((err) => {
+      clearTimeout(timeout);
+      if (err) {
+        logger.error("Error stopping Prometheus metrics server", err, {
+          timeout_ms: timeoutMs
+        });
+        reject(err);
+      } else {
+        logger.info("Prometheus metrics server stopped", {
+          timeout_ms: timeoutMs
+        });
+        resolve();
+      }
+    });
+    server.closeAllConnections?.();
+  });
+}
+
+export { ADR0007_BUCKETS_MS, ADR0007_BUCKETS_SECONDS, ERROR_HANDLING_METRICS, EXPORTER_LABELS, FOUNDRY_METRICS, FULHASH_METRICS, InvalidLabelNameError, InvalidMetricNameError, MetricRegistrationError, PROMETHEUS_EXPORTER_METRICS, PromClientNotFoundError, PrometheusExporter, PrometheusExporterError, RefreshError, createMetricsHandler, msToSeconds, registerPrometheusShutdown, startMetricsServer, stopMetricsServer };
+//# sourceMappingURL=chunk-K2FYT43R.js.map
+//# sourceMappingURL=chunk-K2FYT43R.js.map