@avtechno/sfr 1.0.18 → 2.0.1

package/dist/types/observability/logger.d.mts

@@ -0,0 +1,54 @@
+/**
+ * SFR Logger Module
+ *
+ * Enhanced Winston logger with automatic OpenTelemetry trace context injection.
+ */
+import winston from "winston";
+export interface LoggerConfig {
+    service_name?: string;
+    level?: string;
+    format?: "json" | "pretty";
+    transports?: winston.transport[];
+}
+/**
+ * Initializes the SFR logger with the given configuration.
+ * Called automatically by init_observability.
+ */
+export declare function init_logger(config?: LoggerConfig): winston.Logger;
+/**
+ * Gets the SFR logger instance.
+ * Creates a default instance if not initialized.
+ */
+export declare function get_logger(): winston.Logger;
+/**
+ * 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 declare function create_child_logger(meta: Record<string, any>): winston.Logger;
+/**
+ * The default SFR logger instance.
+ * Automatically includes trace context when available.
+ */
+export declare const sfr_logger: {
+    error: (message: string, meta?: Record<string, any>) => winston.Logger;
+    warn: (message: string, meta?: Record<string, any>) => winston.Logger;
+    info: (message: string, meta?: Record<string, any>) => winston.Logger;
+    http: (message: string, meta?: Record<string, any>) => winston.Logger;
+    verbose: (message: string, meta?: Record<string, any>) => winston.Logger;
+    debug: (message: string, meta?: Record<string, any>) => winston.Logger;
+    silly: (message: string, meta?: Record<string, any>) => winston.Logger;
+    /**
+     * Creates a child logger with additional context.
+     */
+    child: (meta: Record<string, any>) => winston.Logger;
+};
+export { sfr_logger as logger };

package/dist/types/observability/metrics.d.mts

@@ -0,0 +1,74 @@
+/**
+ * SFR Metrics Module
+ *
+ * Provides pre-defined metrics for REST, WebSocket, and MQ protocols.
+ */
+import { type Counter, type Histogram, type UpDownCounter, type Meter } from "@opentelemetry/api";
+/**
+ * Pre-defined SFR metrics for all protocols.
+ */
+export interface SFRMetrics {
+    rest_requests_total: Counter;
+    rest_request_duration: Histogram;
+    rest_errors_total: Counter;
+    rest_request_size: Histogram;
+    rest_response_size: Histogram;
+    ws_connections_active: UpDownCounter;
+    ws_connections_total: Counter;
+    ws_events_total: Counter;
+    ws_event_duration: Histogram;
+    ws_errors_total: Counter;
+    mq_messages_received: Counter;
+    mq_messages_published: Counter;
+    mq_processing_duration: Histogram;
+    mq_errors_total: Counter;
+    mq_messages_rejected: Counter;
+    mq_messages_acked: Counter;
+}
+/**
+ * Gets the SFR meter instance.
+ */
+export declare function get_meter(): Meter;
+/**
+ * Initializes all SFR metrics.
+ * Called automatically by init_observability.
+ *
+ * @param service_name - Service name for metric labels
+ */
+export declare function init_metrics(service_name: string): SFRMetrics;
+/**
+ * Gets the SFR metrics instance.
+ * Initializes with default values if not already initialized.
+ */
+export declare function get_sfr_metrics(): SFRMetrics | null;
+/**
+ * Convenience function to record a REST request.
+ */
+export declare function record_rest_request(attributes: {
+    method: string;
+    route: string;
+    status_code: number;
+    duration_ms: number;
+    request_size?: number;
+    response_size?: number;
+}): void;
+/**
+ * Convenience function to record a WebSocket event.
+ */
+export declare function record_ws_event(attributes: {
+    namespace: string;
+    event: string;
+    duration_ms: number;
+    error?: boolean;
+}): void;
+/**
+ * Convenience function to record an MQ message.
+ */
+export declare function record_mq_message(attributes: {
+    queue: string;
+    pattern: string;
+    duration_ms: number;
+    error?: boolean;
+    rejected?: boolean;
+    acked?: boolean;
+}): void;

package/dist/types/observability/middleware/mq.d.mts

@@ -0,0 +1,46 @@
+/**
+ * SFR MQ Telemetry Instrumentation
+ *
+ * Instruments AMQP/RabbitMQ with tracing and metrics.
+ */
+import type { Options } from "amqplib";
+/**
+ * Wraps an MQ message handler with tracing and metrics.
+ * Extracts trace context from message headers for distributed tracing.
+ *
+ * @param queue - The queue name
+ * @param pattern - The communication pattern (e.g., "Point-to-Point", "Fanout")
+ * @param handler - The original handler function
+ * @returns Instrumented handler function
+ */
+export declare function wrap_mq_handler(queue: string, pattern: string, handler: (msg: ParsedMessage) => void | Promise<void>): (msg: ParsedMessage) => Promise<void>;
+/**
+ * Injects trace context into MQ message headers for distributed tracing.
+ * Call this before publishing a message to propagate the trace.
+ *
+ * @param options - The publish options object (will be modified)
+ * @returns The options object with trace context in headers
+ *
+ * @example
+ * ```typescript
+ * const options = inject_mq_trace_context({});
+ * channel.publish(exchange, routingKey, content, options);
+ * ```
+ */
+export declare function inject_mq_trace_context(options?: Options.Publish): Options.Publish;
+/**
+ * Records an MQ publish event for metrics.
+ */
+export declare function record_mq_publish(exchange: string, pattern: string): void;
+/**
+ * Records an MQ message acknowledgment.
+ */
+export declare function record_mq_ack(queue: string, pattern: string): void;
+/**
+ * Records an MQ message rejection.
+ */
+export declare function record_mq_reject(queue: string, pattern: string, requeue: boolean): void;
+/**
+ * Extracts trace context from the current span for manual propagation.
+ */
+export declare function get_mq_trace_headers(): Record<string, string>;

package/dist/types/observability/middleware/rest.d.mts

@@ -0,0 +1,33 @@
+/**
+ * SFR REST Telemetry Middleware
+ *
+ * Express middleware that instruments REST handlers with tracing and metrics.
+ */
+import type { Request, Response, NextFunction } from "express";
+/**
+ * Express middleware that adds OpenTelemetry instrumentation to REST handlers.
+ *
+ * Features:
+ * - Creates spans for each request
+ * - Extracts trace context from incoming headers (distributed tracing)
+ * - Records request/response metrics
+ * - Logs HTTP traffic with trace correlation
+ *
+ * @example
+ * ```typescript
+ * app.use(sfr_rest_telemetry());
+ * ```
+ */
+export declare function sfr_rest_telemetry(): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Extracts the SFR span from a request.
+ * Useful for adding custom attributes or events within handlers.
+ */
+export declare function get_request_span(req: Request): any;
+/**
+ * Extracts the trace context from a request.
+ */
+export declare function get_request_trace(req: Request): {
+    trace_id: string;
+    span_id: string;
+} | null;

package/dist/types/observability/middleware/ws.d.mts

@@ -0,0 +1,35 @@
+/**
+ * SFR WebSocket Telemetry Instrumentation
+ *
+ * Instruments Socket.IO with tracing and metrics.
+ */
+import type { Server, Socket } from "socket.io";
+/**
+ * Instruments a Socket.IO server with OpenTelemetry tracing and metrics.
+ *
+ * Features:
+ * - Tracks active connections
+ * - Creates spans for each event
+ * - Records event metrics
+ * - Logs connection lifecycle with trace correlation
+ *
+ * @param io - The Socket.IO server instance
+ */
+export declare function instrument_socket_io(io: Server): void;
+/**
+ * Wraps a WebSocket event handler with tracing and metrics.
+ * Used internally by SFR to instrument registered handlers.
+ *
+ * @param namespace - The Socket.IO namespace
+ * @param event - The event name
+ * @param handler - The original handler function
+ * @returns Instrumented handler function
+ */
+export declare function wrap_ws_handler(namespace: string, event: string, handler: (...args: any[]) => void | Promise<void>): (...args: any[]) => Promise<void>;
+/**
+ * Gets the trace context attached to a socket.
+ */
+export declare function get_socket_trace(socket: Socket): {
+    trace_id: string;
+    span_id: string;
+} | null;

package/dist/types/observability/tracer.d.mts

@@ -0,0 +1,90 @@
+/**
+ * SFR Tracing Module
+ *
+ * Provides utilities for creating and managing OpenTelemetry spans.
+ */
+import { SpanKind, type Span, type Tracer, type Context } from "@opentelemetry/api";
+/**
+ * Gets the SFR tracer instance.
+ */
+export declare function get_tracer(): Tracer;
+export interface SpanOptions {
+    /** Name of the span */
+    name: string;
+    /** Kind of span (default: INTERNAL) */
+    kind?: SpanKind;
+    /** Initial attributes to set on the span */
+    attributes?: Record<string, string | number | boolean>;
+    /** Parent context (optional, uses active context if not provided) */
+    parent_context?: Context;
+}
+/**
+ * Wraps an async function with a span for automatic tracing.
+ * Handles errors, sets status, and ensures span is ended.
+ *
+ * @example
+ * ```typescript
+ * const result = await with_span({
+ *   name: "db:fetch_user",
+ *   attributes: { "user.id": userId }
+ * }, async (span) => {
+ *   span.setAttribute("custom.attr", "value");
+ *   return await db.users.findById(userId);
+ * });
+ * ```
+ */
+export declare function with_span<T>(options: SpanOptions, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Synchronous version of with_span for non-async operations.
+ */
+export declare function with_span_sync<T>(options: SpanOptions, fn: (span: Span) => T): T;
+/**
+ * Gets the current trace context (trace_id, span_id) if available.
+ * Useful for correlating logs and external systems.
+ */
+export declare function get_trace_context(): {
+    trace_id: string;
+    span_id: string;
+    trace_flags: number;
+} | null;
+/**
+ * Injects the current trace context into a carrier object (e.g., HTTP headers, MQ message properties).
+ * Used for distributed trace propagation.
+ *
+ * @example
+ * ```typescript
+ * const headers = {};
+ * inject_trace_context(headers);
+ * // headers now contains traceparent, tracestate, etc.
+ * ```
+ */
+export declare function inject_trace_context(carrier: Record<string, string>): void;
+/**
+ * Extracts trace context from a carrier object and returns the context.
+ * Used to continue a distributed trace from an incoming request/message.
+ *
+ * @example
+ * ```typescript
+ * const parent_ctx = extract_trace_context(req.headers);
+ * await with_span({ name: "handler", parent_context: parent_ctx }, async (span) => {
+ *   // This span is a child of the extracted context
+ * });
+ * ```
+ */
+export declare function extract_trace_context(carrier: Record<string, string>): Context;
+/**
+ * Adds attributes to the current active span.
+ * No-op if no span is active.
+ */
+export declare function add_span_attributes(attributes: Record<string, string | number | boolean>): void;
+/**
+ * Records an event on the current active span.
+ * No-op if no span is active.
+ */
+export declare function add_span_event(name: string, attributes?: Record<string, string | number | boolean>): void;
+/**
+ * Sets an error status on the current active span.
+ * No-op if no span is active.
+ */
+export declare function set_span_error(error: Error): void;
+export { SpanKind };

package/dist/types/sfr-pipeline.d.mts

@@ -1,3 +1,4 @@
+import { type ObservabilityOptions } from "./observability/index.mjs";
 export declare class SFRPipeline {
     private cfg;
     private oas_cfg;
@@ -14,20 +15,60 @@ export declare class SFRPipeline {
             handlers: {};
             controllers: {};
         };
+        ws: {
+            handlers: {};
+            controllers: {};
+        };
         mq: {
             handlers: {};
             controllers: {};
         };
     };
+    static auth_config: AuthConfig;
+    static rate_limit_config: RateLimitGlobalConfig;
+    static observability_options: ObservabilityOptions;
+    /**
+     * Sets the authentication middleware for protected routes.
+     * @param middleware - The authentication middleware function
+     */
+    static set_auth_middleware(middleware: AuthMiddleware): void;
+    /**
+     * Configures global rate limiting options for all routes.
+     * Can be overridden per-route using cfg.rate_limit in SFR files.
+     * @param config - Rate limit configuration options
+     */
+    static set_rate_limit_config(config: RateLimitGlobalConfig): void;
+    /**
+     * Configures observability options for tracing, metrics, and logging.
+     * Must be called before SFR initialization to take effect.
+     * @param options - Observability configuration options
+     */
+    static set_observability_options(options: ObservabilityOptions): void;
     constructor(cfg: ParserCFG, oas_cfg: OASConfig, comms: SFRProtocols);
     init(base_url?: string): Promise<ServiceDocuments>;
     private file_parsing;
     private fn_binding;
+    /**
+     * Generates OpenAPI multipart/form-data schema for Multer validators.
+     * Since Multer middleware functions can't be easily inspected at runtime,
+     * this generates a generic file upload schema.
+     */
+    private generate_multer_openapi_schema;
+    /**
+     * Gets rate limit configuration for a route, merging global defaults with route-specific config.
+     */
+    private get_rate_limit_config_for_route;
+    /**
+     * Creates a rate limiter middleware based on configuration.
+     * Merges route-specific config with global defaults.
+     */
+    private create_rate_limiter;
     private bind_rest_fns;
     private bind_ws_fns;
     private bind_mq_fns;
     private spec_generation;
     private generate_open_api_document;
-    private generate_async_api_document;
+    private generate_ws_async_api_document;
+    private generate_mq_async_api_document;
     private print_to_console;
 }

package/dist/types/templates.d.mts

@@ -1,8 +1,3 @@
 export declare function REST<V, H, C>(struct: RESTHandlerDescriptor<V, H, C>): H & C;
-export declare function WS<V, H, C>(struct: WSHandlerDescriptor<V, H, C>): {
-    validators: RequestValidators;
-    controllers: RequestControllers;
-    handlers: WSRequestHandlers;
-    cfg: SFRConfig;
-};
+export declare function WS<V, H, C>(struct: WSHandlerDescriptor<V, H, C>): H & C;
 export declare function MQ<V, H, C>(struct: MQHandlerDescriptor<V, H, C>): H & C;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avtechno/sfr",
-  "version": "1.0.18",
+  "version": "2.0.1",
   "description": "An opinionated way of writing services using ExpressJS.",
   "type": "module",
   "files": [
@@ -13,20 +13,35 @@
   "exports": {
     "types": "./dist/types/index.d.mts",
     "default": "./dist/index.mjs",
-    "import": ["./dist/index.mjs", "./dist/mq.mjs"]
+    "import": [
+      "./dist/index.mjs",
+      "./dist/mq.mjs"
+    ]
   },
   "scripts": {
     "clean": "rimraf ./dist",
     "build": "yarn clean && tsc --project tsconfig.json",
     "build:watch": "yarn clean && tsc --project tsconfig.json -w",
-    "postversion": "yarn build"
+    "postversion": "yarn build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "prepublish": "tsc",
   "author": "Emmanuel Abellana",
   "license": "ISC",
   "dependencies": {
+    "@opentelemetry/api": "^1.7.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.40.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.45.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.45.0",
+    "@opentelemetry/resources": "^1.18.0",
+    "@opentelemetry/sdk-metrics": "^1.18.0",
+    "@opentelemetry/sdk-node": "^0.45.0",
+    "@opentelemetry/semantic-conventions": "^1.18.0",
     "amqplib": "^0.10.3",
     "express": "^4.18.2",
+    "express-rate-limit": "^7.1.5",
     "express-session": "^1.17.3",
     "file-type": "^18.5.0",
     "joi": "^17.11.0",
@@ -36,6 +51,14 @@
     "socket.io": "^4.7.2",
     "winston": "^3.17.0"
   },
+  "peerDependencies": {
+    "@opentelemetry/api": ">=1.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/amqplib": "^0.10.3",
     "@types/express": "^4.17.19",
@@ -43,9 +66,11 @@
     "@types/js-yaml": "^4.0.7",
     "@types/multer": "^1.4.11",
     "@types/openapi-v3": "^3.0.0",
+    "@vitest/coverage-v8": "^2.1.9",
     "openapi-types": "^12.1.3",
     "rimraf": "^5.0.1",
     "typedoc": "^0.25.2",
-    "typescript": "^5.2.2"
+    "typescript": "^5.2.2",
+    "vitest": "^2.1.9"
   }
 }

package/src/index.mts

@@ -48,7 +48,8 @@ async function write_service_discovery(cfg: ParserCFG, documents: ServiceDocumen
       } break;
 
       case "WS": {
-
+        documentation = documentation as AsyncAPIDocument;
+        write_to_file(cfg, "ws/index.yaml", documentation);
       } break;
 
       case "MQ": {
@@ -70,7 +71,7 @@ async function write_to_file(cfg: ParserCFG, dir: string, data: object) {
   } 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+" });
   }
 }
 
@@ -85,6 +86,16 @@ function inject(injections : InjectedFacilities){
     ...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
@@ -96,4 +107,56 @@ function inject(injections : InjectedFacilities){
   }
 }
 
-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,
+  type ObservabilityOptions
+} 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,
+  type SFRMetrics
+} from "./observability/metrics.mjs";
+
+export {
+  sfr_logger,
+  create_child_logger,
+  init_logger,
+  type LoggerConfig
+} from "./observability/logger.mjs";
+
+export { 
+  REST, 
+  WS, 
+  MQ, 
+  MQLib, 
+  BroadcastMQ, 
+  TargetedMQ, 
+  inject, 
+  set_auth_middleware,
+  set_rate_limit_config,
+  set_observability_options
+};

package/src/logger.mts

@@ -1,52 +1,17 @@
-import winston from 'winston';
+/**
+ * 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
+ */
 
-// 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 };
+export { 
+  sfr_logger as logger,
+  sfr_logger,
+  create_child_logger,
+  init_logger,
+  get_logger,
+  type LoggerConfig
+} from "./observability/logger.mjs";