@avtechno/sfr 1.0.18 → 2.0.0

package/src/sfr-pipeline.mts

@@ -3,8 +3,19 @@ import fs from "fs/promises";
 import { template } from "./util.mjs";
 import { BroadcastMQ, TargetedMQ } from "./mq.mjs"; 
 import j2s from "joi-to-swagger";
-
-import {logger} from "./logger.mjs";
+import rateLimit from "express-rate-limit";
+
+// Observability imports
+import { 
+  init_observability, 
+  is_observability_enabled,
+  type ObservabilityOptions 
+} from "./observability/index.mjs";
+import { sfr_logger as logger, create_child_logger } from "./observability/logger.mjs";
+import { sfr_rest_telemetry } from "./observability/middleware/rest.mjs";
+import { instrument_socket_io, wrap_ws_handler } from "./observability/middleware/ws.mjs";
+import { wrap_mq_handler, record_mq_reject } from "./observability/middleware/mq.mjs";
+import { with_span, SpanKind, add_span_attributes } from "./observability/tracer.mjs";
 
 const CWD = process.cwd();
 
@@ -28,16 +39,71 @@ export class SFRPipeline {
       handlers: {},
       controllers: {}
     },
+    ws: {
+      handlers: {},
+      controllers: {}
+    },
     mq: {
       handlers: {},
       controllers: {}
     },
   }
 
+  /* Authentication middleware configuration */
+  static auth_config: AuthConfig = {};
+
+  /* Rate limit configuration */
+  static rate_limit_config: RateLimitGlobalConfig = {};
+
+  /* Observability configuration */
+  static observability_options: ObservabilityOptions = {};
+
+  /**
+   * Sets the authentication middleware for protected routes.
+   * @param middleware - The authentication middleware function
+   */
+  static set_auth_middleware(middleware: AuthMiddleware) {
+    SFRPipeline.auth_config.middleware = middleware;
+  }
+
+  /**
+   * 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) {
+    SFRPipeline.rate_limit_config = config;
+  }
+
+  /**
+   * 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) {
+    SFRPipeline.observability_options = options;
+  }
+
   constructor(private cfg: ParserCFG, private oas_cfg: OASConfig, private comms: SFRProtocols) { }
 
   async init(base_url?: string): Promise<ServiceDocuments> {
     this.base_url = base_url;
+
+    // Initialize observability with service config from oas_cfg
+    if (SFRPipeline.observability_options.enabled !== false) {
+      init_observability(this.oas_cfg, SFRPipeline.observability_options);
+    }
+
+    // Add REST telemetry middleware if enabled
+    if (this.comms["REST"] && is_observability_enabled()) {
+      this.comms["REST"].use(sfr_rest_telemetry());
+    }
+
+    // Instrument Socket.IO if enabled
+    if (this.comms["WS"] && is_observability_enabled()) {
+      instrument_socket_io(this.comms["WS"]);
+    }
+
     if(this.comms["MQ"]){
       //Create channels for each type of Communication Pattern
       const channels = await Promise.all(PATTERNS.map(async (v) => {
@@ -58,6 +124,19 @@ export class SFRPipeline {
         ...SFRPipeline.injections.mq.handlers,
         mq: this.pattern_channels
       }
+
+      SFRPipeline.injections.ws.handlers = {
+        ...SFRPipeline.injections.ws.handlers,
+        mq: this.pattern_channels
+      }
+    }
+
+    // Inject Socket.IO server into WS handlers
+    if (this.comms["WS"]) {
+      SFRPipeline.injections.ws.handlers = {
+        ...SFRPipeline.injections.ws.handlers,
+        io: this.comms["WS"]
+      }
     }
 
     //Declarations for each protocol in key/value pairs.
@@ -118,6 +197,91 @@ export class SFRPipeline {
       }
     });
   }
+  /**
+   * 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(validator: RequestHandler): any {
+    // Multer middleware is a function, so we generate a generic multipart schema
+    // In the future, this could be enhanced to parse Multer configuration
+    return {
+      content: {
+        "multipart/form-data": {
+          schema: {
+            type: "object",
+            properties: {
+              file: {
+                type: "string",
+                format: "binary",
+                description: "File to upload"
+              }
+            }
+          },
+          encoding: {
+            file: {
+              contentType: "*/*"
+            }
+          }
+        }
+      }
+    };
+  }
+
+  /**
+   * Gets rate limit configuration for a route, merging global defaults with route-specific config.
+   */
+  private get_rate_limit_config_for_route(cfg?: SFRConfig): RateLimitConfig | null {
+    if (cfg?.rate_limit === false) {
+      return null; // Explicitly disabled
+    }
+    
+    const global_default = SFRPipeline.rate_limit_config.default;
+    const route_config = cfg?.rate_limit;
+    
+    if (!global_default && !route_config) {
+      return null; // No rate limiting configured
+    }
+    
+    return {
+      max: 100,
+      windowMs: 60000,
+      ...global_default,
+      ...route_config
+    };
+  }
+
+  /**
+   * Creates a rate limiter middleware based on configuration.
+   * Merges route-specific config with global defaults.
+   */
+  private create_rate_limiter(route_config?: RateLimitConfig | false): RequestHandler | null {
+    // If explicitly disabled, return null
+    if (route_config === false) {
+      return null;
+    }
+
+    // Merge route config with global default
+    const global_default = SFRPipeline.rate_limit_config.default;
+    const config: RateLimitConfig = {
+      max: 100,
+      windowMs: 60000,
+      message: "Too many requests, please try again later.",
+      statusCode: 429,
+      standardHeaders: true,
+      legacyHeaders: false,
+      ...global_default,
+      ...route_config
+    };
+
+    // Only create rate limiter if max is greater than 0
+    if (config.max && config.max > 0) {
+      return rateLimit(config);
+    }
+
+    return null;
+  }
+
   /* Fn Binding */
   private async bind_rest_fns(declaration: RESTNamespaceDeclaration) {
     const comms = this.comms["REST"];
@@ -146,14 +310,27 @@ export class SFRPipeline {
           const validator = validators[name];
           const validator_type = typeof validator !== "function" ? "joi" : "multer";
 
+          // Apply rate limiting middleware if configured
+          const rate_limiter = this.create_rate_limiter(cfg.rate_limit);
+          if (rate_limiter) {
+            comms[method.toLowerCase() as RESTRequestType](dir, rate_limiter);
+          }
+
           /* bind validators */
           switch (validator_type) {
             case "joi": {
-              comms[method.toLowerCase() as RESTRequestType](dir, (req, res, next) => {
+              comms[method.toLowerCase() as RESTRequestType](dir, async (req, res, next) => {
                 let error: string | boolean = true;
                 
-                if (is_public) {
-                  //if(!req.session.user)return res.status(401).json({error : "Session not found."});
+                // Authentication check for protected routes
+                if (!is_public && SFRPipeline.auth_config.middleware) {
+                  const auth_result = await SFRPipeline.auth_config.middleware(req, res);
+                  if (auth_result === false) {
+                    return res.status(401).json({ error: "Unauthorized" });
+                  }
+                  if (typeof auth_result === "object" && auth_result.error) {
+                    return res.status(auth_result.status || 401).json({ error: auth_result.error });
+                  }
                 }
                 
                 const validator_keys = Object.keys(validator);
@@ -186,7 +363,101 @@ export class SFRPipeline {
     });
   }
   private async bind_ws_fns(declaration: WSNamespaceDeclaration) {
+    const io = this.comms["WS"];
+    if (!io) throw new Error(`FN Binding failed: \nWS protocol lacks its associated SFRProtocols`);
+
+    Object.entries(declaration).forEach(([namespace, module]) => {
+      const { cfg, validators, handlers } = module.content;
+      
+      // Determine the Socket.IO namespace to use
+      // Priority: cfg.namespace -> cfg.base_dir -> "/"
+      let ws_namespace = "/";
+      if (cfg.namespace) ws_namespace = cfg.namespace.startsWith("/") ? cfg.namespace : `/${cfg.namespace}`;
+      else if (cfg.base_dir) ws_namespace = cfg.base_dir.startsWith("/") ? cfg.base_dir : `/${cfg.base_dir}`;
+      
+      logger.info(`[SFR WS ${module.name}] namespace: ${ws_namespace}`);
+
+      // Get or create the namespace
+      const nsp = io.of(ws_namespace);
+
+      // Handle connections to this namespace
+      nsp.on("connection", (socket) => {
+        logger.info(`[SFR WS] Client connected to ${ws_namespace}: ${socket.id}`);
+
+        // Register event handlers for this connection
+        Object.entries(handlers).forEach(([event, handler]) => {
+          // Skip if no matching validator
+          const validator = validators[event];
+          if (!validator) return;
+
+          socket.on(event, async (data: any, ack?: (...args: any[]) => void) => {
+            // Validate incoming data if validator is a Joi schema (not Multer)
+            const validator_type = typeof validator !== "function" ? "joi" : "custom";
+
+            if (validator_type === "joi") {
+              const validator_keys = Object.keys(validator);
+              if (validator_keys.length) {
+                const error = template(validator, data || {});
+                if (error) {
+                  // Send validation error back via acknowledgement or emit
+                  if (ack) {
+                    ack({ error });
+                  } else {
+                    socket.emit(`${event}:error`, { error });
+                  }
+                  return;
+                }
+              }
+            }
 
+            // Build context for handler
+            const ctx: WSRequestCtx = {
+              io,
+              socket,
+              data: data || {},
+              ack
+            };
+
+            // Create the handler execution function
+            const execute_handler = async () => {
+              await handler.fn.call({ 
+                ...module.content.controllers,
+                ...SFRPipeline.injections.ws.handlers,
+                io,
+                socket
+              }, ctx);
+            };
+
+            try {
+              // Wrap with telemetry if observability is enabled
+              if (is_observability_enabled()) {
+                const instrumented = wrap_ws_handler(ws_namespace, event, execute_handler);
+                await instrumented();
+              } else {
+                await execute_handler();
+              }
+            } catch (err) {
+              logger.error(`[SFR WS] Error in handler ${event}`, {
+                error: err instanceof Error ? err.message : String(err),
+                event,
+                namespace: ws_namespace
+              });
+              if (ack) {
+                ack({ error: err instanceof Error ? err.message : "Unknown error" });
+              } else {
+                socket.emit(`${event}:error`, { error: err instanceof Error ? err.message : "Unknown error" });
+              }
+            }
+          });
+
+          this.mount_data.ws++;
+        });
+
+        socket.on("disconnect", (reason) => {
+          logger.info(`[SFR WS] Client disconnected from ${ws_namespace}: ${socket.id} (${reason})`);
+        });
+      });
+    });
   }
   private async bind_mq_fns(declaration: MQNamespaceDeclaration) {
     const comms = this.comms["MQ"];
@@ -214,31 +485,41 @@ export class SFRPipeline {
           const validator = validators[name];
           //const validator_type = typeof validator !== "function" ? "joi" : "multer"; // TODO: Dynamically update parameter content based on validator type.
 
-          let validator_fn = function (msg: ConsumeMessage) {
+          // Create the base handler with validation
+          const base_handler = function (msg: ParsedMessage) {
             const validator_keys = Object.keys(validator);
 
             if(validator_keys.length){
               const error = template(validator, msg.content);
               
               if (error) {
+                // Record rejection metrics
+                if (is_observability_enabled()) {
+                  record_mq_reject(dir, pattern, false);
+                }
+
                 if (mq instanceof TargetedMQ) {
                   if (error) {
                     switch (pattern) {
-                      case "Request-Reply": mq.reply(msg, { error }); break;
-                      default: mq.channel.reject(msg, false);
+                      case "Request-Reply": mq.reply(msg as any, { error }); break;
+                      default: mq.channel.reject(msg as any, false);
                     }
                   }
                 }
 
-                if (mq instanceof BroadcastMQ)mq.channel.reject(msg, false);
+                if (mq instanceof BroadcastMQ) mq.channel.reject(msg as any, false);
 
                 return; //Return immediately to avoid executing handler fn (which may contain reply or ack calls.)
               }
             }
 
-
             handler.fn(msg);
-          }
+          };
+
+          // Wrap with telemetry if observability is enabled
+          const validator_fn = is_observability_enabled() 
+            ? wrap_mq_handler(dir, pattern, base_handler)
+            : base_handler;
 
           /* bind validators */
           if (mq instanceof TargetedMQ) {
@@ -267,8 +548,8 @@ export class SFRPipeline {
     const documents = Object.entries(protocols).map(([protocol, declaration]) => {
       switch (protocol) {
         case "REST": return [protocol, this.generate_open_api_document(declaration as RESTNamespaceDeclaration)];
-        case "WS": return [protocol, this.generate_async_api_document(declaration as WSNamespaceDeclaration)];
-        case "MQ": return [protocol, this.generate_async_api_document(declaration as MQNamespaceDeclaration)];
+        case "WS": return [protocol, this.generate_ws_async_api_document(declaration as WSNamespaceDeclaration)];
+        case "MQ": return [protocol, this.generate_mq_async_api_document(declaration as MQNamespaceDeclaration)];
         default: throw new Error(`Failed to generate SFR Spec: ${protocol} protocol is unknown.`);
       }
     });
@@ -313,12 +594,15 @@ export class SFRPipeline {
           if (body.tags && Array.isArray(body.tags)) default_tags.push(...body.tags);
 
           const operation_id = `${base_dir}${namespace}/${endpoint}`;
+          const is_public = Boolean(cfg.public);
+          const rate_limit_config = this.get_rate_limit_config_for_route(cfg);
+          
           const document: any = {
             operationId : `${method.toUpperCase()}:${operation_id}`,
             summary     : body.summary || "",
             description : body.description || "",
             tags        : default_tags,
-            public      : Boolean(cfg.public),
+            public      : is_public,
 
             responses: {
               "200": {
@@ -326,19 +610,90 @@ export class SFRPipeline {
                 content: { "application/json": { schema: { type: "object" } } }
               },
               "400": {
-                description: "An error has occured",
-                content: { "application/json": { schema: { type: "object" } } }
+                description: "Bad request - validation error",
+                content: { "application/json": { schema: { type: "object", properties: { error: { type: "string" } } } } }
               }
             }
           };
 
+          // Add authentication-related responses for protected routes
+          if (!is_public) {
+            document.responses["401"] = {
+              description: "Unauthorized - authentication required",
+              content: { "application/json": { schema: { type: "object", properties: { error: { type: "string" } } } } }
+            };
+            document.responses["403"] = {
+              description: "Forbidden - insufficient permissions",
+              content: { "application/json": { schema: { type: "object", properties: { error: { type: "string" } } } } }
+            };
+          }
+
+          // Add rate limiting response and headers if rate limiting is configured
+          if (rate_limit_config && rate_limit_config.max && rate_limit_config.max > 0) {
+            document.responses["429"] = {
+              description: "Too many requests - rate limit exceeded",
+              content: { 
+                "application/json": { 
+                  schema: { 
+                    type: "object", 
+                    properties: { 
+                      error: { type: "string" },
+                      message: { type: "string" }
+                    } 
+                  } 
+                } 
+              },
+              headers: {}
+            };
+
+            // Add rate limit headers if standardHeaders is enabled
+            if (rate_limit_config.standardHeaders !== false) {
+              document.responses["429"].headers["RateLimit-Limit"] = {
+                description: "The maximum number of requests allowed in the current window",
+                schema: { type: "integer", example: rate_limit_config.max }
+              };
+              document.responses["429"].headers["RateLimit-Remaining"] = {
+                description: "The number of requests remaining in the current window",
+                schema: { type: "integer" }
+              };
+              document.responses["429"].headers["RateLimit-Reset"] = {
+                description: "The time at which the current rate limit window resets (Unix timestamp)",
+                schema: { type: "integer" }
+              };
+            }
+
+            // Add legacy headers if enabled
+            if (rate_limit_config.legacyHeaders) {
+              document.responses["429"].headers["X-RateLimit-Limit"] = {
+                description: "The maximum number of requests allowed in the current window (legacy)",
+                schema: { type: "integer", example: rate_limit_config.max }
+              };
+              document.responses["429"].headers["X-RateLimit-Remaining"] = {
+                description: "The number of requests remaining in the current window (legacy)",
+                schema: { type: "integer" }
+              };
+              document.responses["429"].headers["X-RateLimit-Reset"] = {
+                description: "The time at which the current rate limit window resets (legacy)",
+                schema: { type: "integer" }
+              };
+            }
+
+            // Add rate limit metadata to operation description
+            if (rate_limit_config.windowMs) {
+              const window_seconds = Math.floor(rate_limit_config.windowMs / 1000);
+              const rate_limit_note = `\n\n**Rate Limit:** ${rate_limit_config.max} requests per ${window_seconds} second${window_seconds !== 1 ? 's' : ''}`;
+              document.description = (document.description || "") + rate_limit_note;
+            }
+          }
+
           //Insert either a parameter or a requestBody according to the method type
           if(validator_type === "joi"){
             document[method === "GET" ? "parameters" : "requestBody"] = j2s(validator).swagger;
           }
 
-          //Haven't found a library for converting multer validators to swagger doc
+          // Convert Multer validators to multipart/form-data OpenAPI schema
           if(validator_type === "multer"){
+            document.requestBody = this.generate_multer_openapi_schema(validator as RequestHandler);
           }
 
           //Create path if it does not exist.
@@ -355,8 +710,103 @@ export class SFRPipeline {
     return spec;
   }
 
+  // Method to generate an AsyncAPI document from a WSNamespaceDeclaration
+  private generate_ws_async_api_document(declaration: WSNamespaceDeclaration): AsyncAPIDocument {
+    const spec: any = {
+      asyncapi: '3.0.0',
+      info: Object.assign({}, this.oas_cfg),
+      servers: {
+        websocket: {
+          host: `localhost:${this.oas_cfg.meta?.port || 3000}`,
+          protocol: 'ws',
+          description: 'WebSocket server'
+        }
+      },
+      channels: {},
+      operations: {},
+      components: {
+        messages: {},
+      },
+    };
+
+    // Conform to AsyncAPI standards by appending "x-property" on each field under "meta"
+    if (spec.info.meta) {
+      spec.info.meta = Object.fromEntries(Object.entries(spec.info.meta).map(([k, v]) => [`x-${k}`, v]));
+    }
+
+    Object.entries(declaration).forEach(([namespace, module]) => {
+      const { cfg, validators, handlers } = module.content;
+
+      // Determine namespace path
+      let ws_namespace = "/";
+      if (cfg.namespace) ws_namespace = cfg.namespace.startsWith("/") ? cfg.namespace : `/${cfg.namespace}`;
+      else if (cfg.base_dir) ws_namespace = cfg.base_dir.startsWith("/") ? cfg.base_dir : `/${cfg.base_dir}`;
+
+      // Loop over all event handlers
+      Object.entries(handlers).forEach(([event, handler]) => {
+        const validator: any = validators[event];
+        if (!validator) return;
+
+        const validator_type = typeof validator !== "function" ? "joi" : "custom";
+        const channel_id = `${ws_namespace === "/" ? "" : ws_namespace}/${event}`.replace(/^\/+/, "").replace(/\//g, "-") || event;
+
+        // Default tags for service classification
+        const default_tags = [
+          { name: `sfr-namespace:${namespace}` },
+          { name: `sfr-service:${this.oas_cfg.title || "unspecified"}` }
+        ];
+
+        if (handler.tags && Array.isArray(handler.tags)) {
+          default_tags.push(...handler.tags.map(t => ({ name: t })));
+        }
+
+        const channel_document: any = {
+          address: ws_namespace === "/" ? `/${event}` : `${ws_namespace}/${event}`,
+          messages: {}
+        };
+
+        const operation_document: any = {
+          action: "receive",
+          summary: handler.summary || `Handle ${event} event`,
+          description: handler.description || "",
+          channel: { $ref: `#/channels/${channel_id}` },
+          tags: default_tags
+        };
+
+        // Generate message schema from Joi validator
+        if (validator_type === "joi") {
+          const message_id = `${channel_id}-message`;
+          channel_document.messages[message_id] = {
+            $ref: `#/components/messages/${message_id}`
+          };
+
+          spec.components.messages[message_id] = {
+            name: message_id,
+            contentType: "application/json",
+            payload: j2s(validator).swagger
+          };
+        }
+
+        spec.channels[channel_id] = channel_document;
+        spec.operations[`${channel_id}-receive`] = operation_document;
+
+        // Add send operation for events that can emit responses
+        const send_operation: any = {
+          action: "send",
+          summary: `Send ${event} response`,
+          description: `Response for ${event} event`,
+          channel: { $ref: `#/channels/${channel_id}` },
+          tags: default_tags
+        };
+        spec.operations[`${channel_id}-send`] = send_operation;
+      });
+    });
+
+    return spec;
+  }
+
   // Method to generate an AsyncAPI document from an MQNamespaceDeclaration
-  private generate_async_api_document(declaration: MQNamespaceDeclaration): AsyncAPIDocument {
+  private generate_mq_async_api_document(declaration: MQNamespaceDeclaration): AsyncAPIDocument {
     // This will hold the final AsyncAPI Document.
     const spec = {
       asyncapi: '3.0.0',

package/src/templates.mts

@@ -22,14 +22,23 @@ export function REST<V, H, C>(struct : RESTHandlerDescriptor<V, H, C>) : H & C {
   return { validators, controllers, handlers, cfg } as H & C
 }
 
-export function WS<V, H, C>(struct : WSHandlerDescriptor<V, H, C>){
+export function WS<V, H, C>(struct : WSHandlerDescriptor<V, H, C>): H & C {
   const validators  : RequestValidators  = struct.validators  || {};
   const controllers : RequestControllers = struct.controllers || {};
   const handlers    : WSRequestHandlers  = struct.handlers    || {};
-  const cfg         : SFRConfig          = struct.cfg         || {};
-  
-  //Dependency injection happens here...npm
-  return { validators, controllers, handlers, cfg }
+  const cfg         : WSConfig           = struct.cfg         || {};
+
+  // Bind controller injections to each controller
+  Object.entries(controllers).map(([k, v]) => controllers[k] = v.bind({...SFRPipeline.injections.ws.controllers}) as RequestController);
+
+  // Bind handler injections and SFR controllers into each handler
+  Object.entries(handlers).forEach(([event, handler]) => {
+    /* @ts-ignore */
+    handlers[event] = { ...handler, fn: handler.fn.bind({ ...controllers, ...SFRPipeline.injections.ws.handlers }) };
+  });
+
+  /* @ts-ignore */
+  return { validators, controllers, handlers, cfg } as H & C;
 }
 
 export function MQ<V, H, C>(struct : MQHandlerDescriptor<V, H, C>): H & C{