@avtechno/sfr 1.0.18 → 2.0.1

package/dist/index.mjs

@@ -40,6 +40,8 @@ async function write_service_discovery(cfg, documents) {
                 break;
             case "WS":
                 {
+                    documentation = documentation;
+                    write_to_file(cfg, "ws/index.yaml", documentation);
                 }
                 break;
             case "MQ": {
@@ -60,7 +62,7 @@ async function write_to_file(cfg, dir, data) {
     else { //Indicates a nested file
         const file = paths.pop(); //Pops the path array to be used for dir creation
         await fs.mkdir(path.join(cwd, cfg.out, ...paths), { recursive: true });
-        fs.writeFile(path.join(cwd, cfg.out, ...paths, `${file}.yml`), yaml.dump(data), { flag: "w+" });
+        await fs.writeFile(path.join(cwd, cfg.out, ...paths, `${file}.yml`), yaml.dump(data), { flag: "w+" });
     }
 }
 function inject(injections) {
@@ -72,6 +74,14 @@ function inject(injections) {
         ...SFRPipeline.injections.rest.controllers,
         ...injections.controllers
     };
+    SFRPipeline.injections.ws.handlers = {
+        ...SFRPipeline.injections.ws.handlers,
+        ...injections.handlers
+    };
+    SFRPipeline.injections.ws.controllers = {
+        ...SFRPipeline.injections.ws.controllers,
+        ...injections.controllers
+    };
     SFRPipeline.injections.mq.handlers = {
         ...SFRPipeline.injections.mq.handlers,
         ...injections.handlers
@@ -81,4 +91,12 @@ function inject(injections) {
         ...injections.controllers
     };
 }
-export { REST, WS, MQ, MQLib, BroadcastMQ, TargetedMQ, inject };
+const set_auth_middleware = SFRPipeline.set_auth_middleware.bind(SFRPipeline);
+const set_rate_limit_config = SFRPipeline.set_rate_limit_config.bind(SFRPipeline);
+const set_observability_options = SFRPipeline.set_observability_options.bind(SFRPipeline);
+// Observability exports
+export { init_observability, shutdown_observability, is_observability_enabled } from "./observability/index.mjs";
+export { get_tracer, with_span, with_span_sync, get_trace_context, inject_trace_context, extract_trace_context, add_span_attributes, add_span_event, set_span_error, SpanKind } from "./observability/tracer.mjs";
+export { get_sfr_metrics, get_meter, record_rest_request, record_ws_event, record_mq_message } from "./observability/metrics.mjs";
+export { sfr_logger, create_child_logger, init_logger } from "./observability/logger.mjs";
+export { REST, WS, MQ, MQLib, BroadcastMQ, TargetedMQ, inject, set_auth_middleware, set_rate_limit_config, set_observability_options };

package/dist/logger.mjs

@@ -1,37 +1,9 @@
-import winston from 'winston';
-// Define log levels
-const levels = {
-    error: 0,
-    warn: 1,
-    info: 2,
-    http: 3,
-    verbose: 4,
-    debug: 5,
-    silly: 6,
-};
-// Define colors for each level
-const colors = {
-    error: 'red',
-    warn: 'yellow',
-    info: 'green',
-    http: 'magenta',
-    verbose: 'cyan',
-    debug: 'blue',
-    silly: 'gray',
-};
-// Add colors to Winston
-winston.addColors(colors);
-// Define the format for logs
-const format = winston.format.combine(winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss:ms' }), winston.format.colorize({ all: true }), winston.format.printf((info) => `${info.timestamp} ${info.level}: ${info.message}${info.metadata ? ` ${JSON.stringify(info.metadata)}` : ''}`));
-// Create the Winston logger
-const logger = winston.createLogger({
-    level: process.env.NODE_ENV === 'development' && Boolean(process.env.DEBUG_SFR) ? 'debug' : 'info',
-    levels,
-    format,
-    transports: [
-        // Console transport
-        new winston.transports.Console(),
-    ],
-});
-// Export the logger
-export { logger };
+/**
+ * SFR Logger Module (Backward Compatibility)
+ *
+ * This module re-exports the new observability logger for backward compatibility.
+ * New code should import from "./observability/logger.mjs" directly.
+ *
+ * @deprecated Use imports from "./observability/logger.mjs" instead
+ */
+export { sfr_logger as logger, sfr_logger, create_child_logger, init_logger, get_logger } from "./observability/logger.mjs";

package/dist/mq.mjs

@@ -5,6 +5,7 @@ import { connect } from "amqplib";
 export class MQLib {
     connection;
     channel;
+    is_closing = false;
     /**
      * Initializes the connection and channel to the message queue.
      *
@@ -37,6 +38,51 @@ 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) {
+        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() {
+        return !!this.connection && !!this.channel && !this.is_closing;
+    }
 }
 export class BaseMQ {
     channel;

package/dist/observability/index.mjs

@@ -0,0 +1,143 @@
+/**
+ * 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";
+let sdk = 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, options = {}) {
+    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, options = {}) {
+    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 = {
+        [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() {
+    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() {
+    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 } 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/dist/observability/logger.mjs

@@ -0,0 +1,128 @@
+/**
+ * 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);
+let logger_instance = 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 = {};
+        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 = {}) {
+    const is_dev = process.env.NODE_ENV === "development";
+    const is_debug = Boolean(process.env.DEBUG_SFR);
+    const env_format = process.env.SFR_LOG_FORMAT;
+    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() {
+    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) {
+    return get_logger().child(meta);
+}
+/**
+ * The default SFR logger instance.
+ * Automatically includes trace context when available.
+ */
+export const sfr_logger = {
+    error: (message, meta) => get_logger().error(message, meta),
+    warn: (message, meta) => get_logger().warn(message, meta),
+    info: (message, meta) => get_logger().info(message, meta),
+    http: (message, meta) => get_logger().http(message, meta),
+    verbose: (message, meta) => get_logger().verbose(message, meta),
+    debug: (message, meta) => get_logger().debug(message, meta),
+    silly: (message, meta) => get_logger().silly(message, meta),
+    /**
+     * Creates a child logger with additional context.
+     */
+    child: (meta) => create_child_logger(meta)
+};
+// Legacy export for backward compatibility with existing logger.mts
+export { sfr_logger as logger };

package/dist/observability/metrics.mjs

@@ -0,0 +1,177 @@
+/**
+ * SFR Metrics Module
+ *
+ * Provides pre-defined metrics for REST, WebSocket, and MQ protocols.
+ */
+import { metrics } from "@opentelemetry/api";
+const METER_NAME = "@avtechno/sfr";
+const METER_VERSION = "1.0.0";
+let sfr_metrics = null;
+let meter = null;
+/**
+ * Gets the SFR meter instance.
+ */
+export function get_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) {
+    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() {
+    return sfr_metrics;
+}
+/**
+ * Convenience function to record a REST request.
+ */
+export function record_rest_request(attributes) {
+    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) {
+    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) {
+    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);
+    }
+}