@avtechno/sfr 1.0.17 → 2.0.0

package/src/mq.mts

@@ -6,6 +6,7 @@ import { ChannelModel, Options, connect, Channel, ConsumeMessage } from "amqplib
 export class MQLib {
   private connection?: ChannelModel;
   private channel?: Channel;
+  private is_closing = false;
 
   /**
    * Initializes the connection and channel to the message queue.
@@ -41,6 +42,54 @@ export class MQLib {
   get_channel() {
     return this.channel;
   }
+
+  /**
+   * Gracefully disconnects from the message queue.
+   * Closes the channel first, then the connection.
+   * 
+   * @param timeout - Optional timeout in ms to wait for in-flight messages (default: 5000)
+   * @example
+   * const mqLib = new MQLib();
+   * await mqLib.init("amqp://localhost");
+   * // ... do work ...
+   * await mqLib.disconnect();
+   */
+  async disconnect(timeout = 5000): Promise<void> {
+    if (this.is_closing) return;
+    this.is_closing = true;
+
+    // Allow time for in-flight messages to complete
+    await new Promise(resolve => setTimeout(resolve, Math.min(timeout, 1000)));
+
+    try {
+      if (this.channel) {
+        await this.channel.close();
+        this.channel = undefined;
+      }
+    } catch (err) {
+      // Channel may already be closed
+    }
+
+    try {
+      if (this.connection) {
+        await this.connection.close();
+        this.connection = undefined;
+      }
+    } catch (err) {
+      // Connection may already be closed
+    }
+
+    this.is_closing = false;
+  }
+
+  /**
+   * Checks if the connection is currently active.
+   * 
+   * @returns true if connected, false otherwise
+   */
+  is_connected(): boolean {
+    return !!this.connection && !!this.channel && !this.is_closing;
+  }
 }
 
 export class BaseMQ{

package/src/observability/index.mts

@@ -0,0 +1,184 @@
+/**
+ * SFR Observability Module
+ * 
+ * Provides OpenTelemetry-compatible tracing, metrics, and logging.
+ * Configuration is automatically extracted from SFR's OASConfig.
+ */
+
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { Resource } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
+
+import { init_metrics } from "./metrics.mjs";
+import { init_logger } from "./logger.mjs";
+
+export interface ObservabilityOptions {
+  /** Enable/disable observability (default: true) */
+  enabled?: boolean;
+  /** OTLP endpoint URL (default: http://localhost:4318) */
+  otlp_endpoint?: string;
+  /** Enable auto-instrumentation for common libraries (default: true) */
+  auto_instrumentation?: boolean;
+  /** Sampling ratio 0.0 - 1.0 (default: 1.0) */
+  sampling_ratio?: number;
+  /** Log format: 'json' for production, 'pretty' for development */
+  log_format?: "json" | "pretty";
+  /** Additional resource attributes */
+  resource_attributes?: Record<string, string>;
+  /** Enable debug logging for OTel SDK */
+  debug?: boolean;
+}
+
+let sdk: NodeSDK | null = null;
+let is_initialized = false;
+
+/**
+ * Extracts observability configuration from SFR's OASConfig.
+ * 
+ * @param oas_cfg - The OASConfig passed to SFR
+ * @param options - Additional observability options
+ */
+function extract_config_from_oas(oas_cfg: OASConfig, options: ObservabilityOptions = {}) {
+  const service_name = oas_cfg.meta?.service || oas_cfg.title || "sfr-service";
+  const service_version = oas_cfg.version || "1.0.0";
+  const environment = process.env.NODE_ENV || "development";
+
+  return {
+    service_name,
+    service_version,
+    environment,
+    domain: oas_cfg.meta?.domain,
+    service_type: oas_cfg.meta?.type,
+    language: oas_cfg.meta?.language,
+    port: oas_cfg.meta?.port,
+    ...options
+  };
+}
+
+/**
+ * Initializes the OpenTelemetry SDK with configuration derived from OASConfig.
+ * Must be called before SFR initialization for full instrumentation.
+ * 
+ * @param oas_cfg - The OASConfig that will be passed to SFR
+ * @param options - Additional observability options
+ */
+export function init_observability(oas_cfg: OASConfig, options: ObservabilityOptions = {}): void {
+  if (is_initialized) {
+    console.warn("[SFR Observability] Already initialized, skipping...");
+    return;
+  }
+
+  if (options.enabled === false || process.env.SFR_TELEMETRY_ENABLED === "false") {
+    console.log("[SFR Observability] Telemetry disabled");
+    return;
+  }
+
+  const config = extract_config_from_oas(oas_cfg, options);
+
+  // Enable debug logging if requested
+  if (options.debug || process.env.OTEL_LOG_LEVEL === "debug") {
+    diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
+  }
+
+  const otlp_endpoint = options.otlp_endpoint 
+    || process.env.OTEL_EXPORTER_OTLP_ENDPOINT 
+    || "http://localhost:4318";
+
+  // Build resource attributes from OASConfig
+  const resource_attributes: Record<string, string> = {
+    [ATTR_SERVICE_NAME]: config.service_name,
+    [ATTR_SERVICE_VERSION]: config.service_version,
+    "deployment.environment": config.environment,
+    "sfr.domain": config.domain || "unknown",
+    "sfr.service.type": config.service_type || "backend",
+    "sfr.language": config.language || "typescript",
+    ...options.resource_attributes
+  };
+
+  if (config.port) {
+    resource_attributes["sfr.port"] = String(config.port);
+  }
+
+  const resource = new Resource(resource_attributes);
+
+  // Configure exporters
+  const trace_exporter = new OTLPTraceExporter({
+    url: `${otlp_endpoint}/v1/traces`
+  });
+
+  // Build instrumentations
+  const instrumentations = options.auto_instrumentation !== false
+    ? [getNodeAutoInstrumentations({
+        "@opentelemetry/instrumentation-fs": { enabled: false }, // Too noisy
+        "@opentelemetry/instrumentation-express": { enabled: true },
+        "@opentelemetry/instrumentation-http": { enabled: true },
+        "@opentelemetry/instrumentation-amqplib": { enabled: true }
+      })]
+    : [];
+
+  const metric_reader = new PeriodicExportingMetricReader({
+    exporter: new OTLPMetricExporter({
+      url: `${otlp_endpoint}/v1/metrics`
+    }),
+    exportIntervalMillis: 60000 // Export every 60 seconds
+  });
+
+  sdk = new NodeSDK({
+    resource,
+    traceExporter: trace_exporter,
+    // @ts-expect-error - Type mismatch between SDK packages, but compatible at runtime
+    metricReader: metric_reader,
+    instrumentations
+  });
+
+  sdk.start();
+  is_initialized = true;
+
+  // Initialize SFR-specific metrics
+  init_metrics(config.service_name);
+
+  // Initialize logger with service context
+  init_logger({
+    service_name: config.service_name,
+    format: options.log_format
+  });
+
+  console.log(`[SFR Observability] Initialized for service: ${config.service_name} v${config.service_version}`);
+}
+
+/**
+ * Gracefully shuts down the OpenTelemetry SDK.
+ * Flushes all pending telemetry data before closing.
+ */
+export async function shutdown_observability(): Promise<void> {
+  if (!sdk) return;
+  
+  try {
+    await sdk.shutdown();
+    is_initialized = false;
+    console.log("[SFR Observability] Shutdown complete");
+  } catch (error) {
+    console.error("[SFR Observability] Error during shutdown:", error);
+  }
+}
+
+/**
+ * Checks if observability has been initialized.
+ */
+export function is_observability_enabled(): boolean {
+  return is_initialized;
+}
+
+// Re-export submodules
+export { get_tracer, with_span, get_trace_context, inject_trace_context } from "./tracer.mjs";
+export { get_sfr_metrics, init_metrics, type SFRMetrics } from "./metrics.mjs";
+export { sfr_logger, create_child_logger, init_logger } from "./logger.mjs";
+export { sfr_rest_telemetry } from "./middleware/rest.mjs";
+export { instrument_socket_io } from "./middleware/ws.mjs";
+export { wrap_mq_handler, inject_mq_trace_context } from "./middleware/mq.mjs";
+

package/src/observability/logger.mts

@@ -0,0 +1,169 @@
+/**
+ * SFR Logger Module
+ * 
+ * Enhanced Winston logger with automatic OpenTelemetry trace context injection.
+ */
+
+import winston from "winston";
+import { trace } from "@opentelemetry/api";
+
+// Define log levels matching standard syslog levels
+const levels = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  http: 3,
+  verbose: 4,
+  debug: 5,
+  silly: 6
+};
+
+const colors = {
+  error: "red",
+  warn: "yellow",
+  info: "green",
+  http: "magenta",
+  verbose: "cyan",
+  debug: "blue",
+  silly: "gray"
+};
+
+winston.addColors(colors);
+
+export interface LoggerConfig {
+  service_name?: string;
+  level?: string;
+  format?: "json" | "pretty";
+  transports?: winston.transport[];
+}
+
+let logger_instance: winston.Logger | null = null;
+let service_name = "@avtechno/sfr";
+
+/**
+ * Custom format that injects OpenTelemetry trace context into log entries.
+ */
+const trace_context_format = winston.format((info) => {
+  const span = trace.getActiveSpan();
+  if (span) {
+    const ctx = span.spanContext();
+    info.trace_id = ctx.traceId;
+    info.span_id = ctx.spanId;
+    info.trace_flags = ctx.traceFlags;
+  }
+  return info;
+});
+
+/**
+ * Structured JSON format for production environments.
+ * Includes trace context, timestamp, and service metadata.
+ */
+const json_format = winston.format.combine(
+  trace_context_format(),
+  winston.format.timestamp({ format: "YYYY-MM-DDTHH:mm:ss.SSSZ" }),
+  winston.format.errors({ stack: true }),
+  winston.format.json()
+);
+
+/**
+ * Human-readable format for development.
+ * Includes colorized output and truncated trace IDs.
+ */
+const pretty_format = winston.format.combine(
+  trace_context_format(),
+  winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss.SSS" }),
+  winston.format.colorize({ all: true }),
+  winston.format.printf((info) => {
+    const trace_suffix = info.trace_id
+      ? ` [${String(info.trace_id).slice(0, 8)}]`
+      : "";
+
+    let meta_str = "";
+    const meta_keys = Object.keys(info).filter(
+      (k) => !["level", "message", "timestamp", "trace_id", "span_id", "trace_flags", "service"].includes(k)
+    );
+
+    if (meta_keys.length > 0) {
+      const meta_obj: Record<string, any> = {};
+      meta_keys.forEach((k) => (meta_obj[k] = info[k]));
+      meta_str = ` ${JSON.stringify(meta_obj)}`;
+    }
+
+    return `${info.timestamp} ${info.level}${trace_suffix}: ${info.message}${meta_str}`;
+  })
+);
+
+/**
+ * Initializes the SFR logger with the given configuration.
+ * Called automatically by init_observability.
+ */
+export function init_logger(config: LoggerConfig = {}): winston.Logger {
+  const is_dev = process.env.NODE_ENV === "development";
+  const is_debug = Boolean(process.env.DEBUG_SFR);
+  const env_format = process.env.SFR_LOG_FORMAT as "json" | "pretty" | undefined;
+
+  service_name = config.service_name || service_name;
+
+  const format_to_use = config.format || env_format || (is_dev ? "pretty" : "json");
+
+  logger_instance = winston.createLogger({
+    level: config.level ?? (is_dev && is_debug ? "debug" : "info"),
+    levels,
+    format: format_to_use === "json" ? json_format : pretty_format,
+    defaultMeta: { service: service_name },
+    transports: config.transports ?? [new winston.transports.Console()]
+  });
+
+  return logger_instance;
+}
+
+/**
+ * Gets the SFR logger instance.
+ * Creates a default instance if not initialized.
+ */
+export function get_logger(): winston.Logger {
+  if (!logger_instance) {
+    init_logger();
+  }
+  return logger_instance!;
+}
+
+/**
+ * Creates a child logger with additional context.
+ * Child loggers inherit parent configuration and add their own metadata.
+ * 
+ * @example
+ * ```typescript
+ * const route_logger = create_child_logger({ 
+ *   protocol: "REST", 
+ *   route: "/api/users" 
+ * });
+ * route_logger.info("Processing request");
+ * ```
+ */
+export function create_child_logger(meta: Record<string, any>): winston.Logger {
+  return get_logger().child(meta);
+}
+
+/**
+ * The default SFR logger instance.
+ * Automatically includes trace context when available.
+ */
+export const sfr_logger = {
+  error: (message: string, meta?: Record<string, any>) => get_logger().error(message, meta),
+  warn: (message: string, meta?: Record<string, any>) => get_logger().warn(message, meta),
+  info: (message: string, meta?: Record<string, any>) => get_logger().info(message, meta),
+  http: (message: string, meta?: Record<string, any>) => get_logger().http(message, meta),
+  verbose: (message: string, meta?: Record<string, any>) => get_logger().verbose(message, meta),
+  debug: (message: string, meta?: Record<string, any>) => get_logger().debug(message, meta),
+  silly: (message: string, meta?: Record<string, any>) => get_logger().silly(message, meta),
+
+  /**
+   * Creates a child logger with additional context.
+   */
+  child: (meta: Record<string, any>) => create_child_logger(meta)
+};
+
+// Legacy export for backward compatibility with existing logger.mts
+export { sfr_logger as logger };
+

package/src/observability/metrics.mts

@@ -0,0 +1,266 @@
+/**
+ * SFR Metrics Module
+ * 
+ * Provides pre-defined metrics for REST, WebSocket, and MQ protocols.
+ */
+
+import { 
+  metrics, 
+  type Counter, 
+  type Histogram, 
+  type UpDownCounter,
+  type Meter
+} from "@opentelemetry/api";
+
+const METER_NAME = "@avtechno/sfr";
+const METER_VERSION = "1.0.0";
+
+/**
+ * Pre-defined SFR metrics for all protocols.
+ */
+export interface SFRMetrics {
+  // REST Metrics
+  rest_requests_total: Counter;
+  rest_request_duration: Histogram;
+  rest_errors_total: Counter;
+  rest_request_size: Histogram;
+  rest_response_size: Histogram;
+
+  // WebSocket Metrics
+  ws_connections_active: UpDownCounter;
+  ws_connections_total: Counter;
+  ws_events_total: Counter;
+  ws_event_duration: Histogram;
+  ws_errors_total: Counter;
+
+  // MQ Metrics
+  mq_messages_received: Counter;
+  mq_messages_published: Counter;
+  mq_processing_duration: Histogram;
+  mq_errors_total: Counter;
+  mq_messages_rejected: Counter;
+  mq_messages_acked: Counter;
+}
+
+let sfr_metrics: SFRMetrics | null = null;
+let meter: Meter | null = null;
+
+/**
+ * Gets the SFR meter instance.
+ */
+export function get_meter(): Meter {
+  if (!meter) {
+    meter = metrics.getMeter(METER_NAME, METER_VERSION);
+  }
+  return meter;
+}
+
+/**
+ * Initializes all SFR metrics.
+ * Called automatically by init_observability.
+ * 
+ * @param service_name - Service name for metric labels
+ */
+export function init_metrics(service_name: string): SFRMetrics {
+  if (sfr_metrics) return sfr_metrics;
+
+  const m = get_meter();
+
+  sfr_metrics = {
+    // REST Metrics
+    rest_requests_total: m.createCounter("sfr.rest.requests.total", {
+      description: "Total number of REST requests processed",
+      unit: "requests"
+    }),
+
+    rest_request_duration: m.createHistogram("sfr.rest.request.duration", {
+      description: "Duration of REST request processing",
+      unit: "ms",
+      advice: {
+        explicitBucketBoundaries: [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000]
+      }
+    }),
+
+    rest_errors_total: m.createCounter("sfr.rest.errors.total", {
+      description: "Total number of REST request errors",
+      unit: "errors"
+    }),
+
+    rest_request_size: m.createHistogram("sfr.rest.request.size", {
+      description: "Size of REST request bodies",
+      unit: "bytes"
+    }),
+
+    rest_response_size: m.createHistogram("sfr.rest.response.size", {
+      description: "Size of REST response bodies",
+      unit: "bytes"
+    }),
+
+    // WebSocket Metrics
+    ws_connections_active: m.createUpDownCounter("sfr.ws.connections.active", {
+      description: "Number of currently active WebSocket connections",
+      unit: "connections"
+    }),
+
+    ws_connections_total: m.createCounter("sfr.ws.connections.total", {
+      description: "Total number of WebSocket connections established",
+      unit: "connections"
+    }),
+
+    ws_events_total: m.createCounter("sfr.ws.events.total", {
+      description: "Total number of WebSocket events processed",
+      unit: "events"
+    }),
+
+    ws_event_duration: m.createHistogram("sfr.ws.event.duration", {
+      description: "Duration of WebSocket event processing",
+      unit: "ms",
+      advice: {
+        explicitBucketBoundaries: [1, 5, 10, 25, 50, 100, 250, 500, 1000]
+      }
+    }),
+
+    ws_errors_total: m.createCounter("sfr.ws.errors.total", {
+      description: "Total number of WebSocket errors",
+      unit: "errors"
+    }),
+
+    // MQ Metrics
+    mq_messages_received: m.createCounter("sfr.mq.messages.received", {
+      description: "Total number of MQ messages received",
+      unit: "messages"
+    }),
+
+    mq_messages_published: m.createCounter("sfr.mq.messages.published", {
+      description: "Total number of MQ messages published",
+      unit: "messages"
+    }),
+
+    mq_processing_duration: m.createHistogram("sfr.mq.processing.duration", {
+      description: "Duration of MQ message processing",
+      unit: "ms",
+      advice: {
+        explicitBucketBoundaries: [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000]
+      }
+    }),
+
+    mq_errors_total: m.createCounter("sfr.mq.errors.total", {
+      description: "Total number of MQ processing errors",
+      unit: "errors"
+    }),
+
+    mq_messages_rejected: m.createCounter("sfr.mq.messages.rejected", {
+      description: "Total number of MQ messages rejected",
+      unit: "messages"
+    }),
+
+    mq_messages_acked: m.createCounter("sfr.mq.messages.acked", {
+      description: "Total number of MQ messages acknowledged",
+      unit: "messages"
+    })
+  };
+
+  return sfr_metrics;
+}
+
+/**
+ * Gets the SFR metrics instance.
+ * Initializes with default values if not already initialized.
+ */
+export function get_sfr_metrics(): SFRMetrics | null {
+  return sfr_metrics;
+}
+
+/**
+ * Convenience function to record a REST request.
+ */
+export function record_rest_request(attributes: {
+  method: string;
+  route: string;
+  status_code: number;
+  duration_ms: number;
+  request_size?: number;
+  response_size?: number;
+}): void {
+  if (!sfr_metrics) return;
+
+  const labels = {
+    method: attributes.method,
+    route: attributes.route,
+    status_code: String(attributes.status_code)
+  };
+
+  sfr_metrics.rest_requests_total.add(1, labels);
+  sfr_metrics.rest_request_duration.record(attributes.duration_ms, labels);
+
+  if (attributes.status_code >= 400) {
+    sfr_metrics.rest_errors_total.add(1, labels);
+  }
+
+  if (attributes.request_size !== undefined) {
+    sfr_metrics.rest_request_size.record(attributes.request_size, { method: attributes.method });
+  }
+
+  if (attributes.response_size !== undefined) {
+    sfr_metrics.rest_response_size.record(attributes.response_size, { method: attributes.method });
+  }
+}
+
+/**
+ * Convenience function to record a WebSocket event.
+ */
+export function record_ws_event(attributes: {
+  namespace: string;
+  event: string;
+  duration_ms: number;
+  error?: boolean;
+}): void {
+  if (!sfr_metrics) return;
+
+  const labels = {
+    namespace: attributes.namespace,
+    event: attributes.event
+  };
+
+  sfr_metrics.ws_events_total.add(1, labels);
+  sfr_metrics.ws_event_duration.record(attributes.duration_ms, labels);
+
+  if (attributes.error) {
+    sfr_metrics.ws_errors_total.add(1, labels);
+  }
+}
+
+/**
+ * Convenience function to record an MQ message.
+ */
+export function record_mq_message(attributes: {
+  queue: string;
+  pattern: string;
+  duration_ms: number;
+  error?: boolean;
+  rejected?: boolean;
+  acked?: boolean;
+}): void {
+  if (!sfr_metrics) return;
+
+  const labels = {
+    queue: attributes.queue,
+    pattern: attributes.pattern
+  };
+
+  sfr_metrics.mq_messages_received.add(1, labels);
+  sfr_metrics.mq_processing_duration.record(attributes.duration_ms, labels);
+
+  if (attributes.error) {
+    sfr_metrics.mq_errors_total.add(1, labels);
+  }
+
+  if (attributes.rejected) {
+    sfr_metrics.mq_messages_rejected.add(1, labels);
+  }
+
+  if (attributes.acked) {
+    sfr_metrics.mq_messages_acked.add(1, labels);
+  }
+}
+