@avtechno/sfr 1.0.0

package/src/sfr-pipeline.mts

@@ -0,0 +1,508 @@
+import path from "path";
+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";
+
+const CWD = process.cwd();
+
+const PATTERNS: CommunicationPattern[] = ["Point-to-Point", "Request-Reply", "Publish-Subscribe", "Routing", "Topic"];
+const TARGETED_PATTERN = ["Point-to-Point", "Request-Reply"];
+
+export class SFRPipeline {
+  base_url: string;
+  pattern_channels: PatternMQSet;
+  mount_data = {
+    rest : 0,
+    ws   : 0,
+    mq   : 0
+  }
+
+  /* Contains values that are injected into each protocol's handlers. */
+  static injections = {
+    rest: {
+      handlers: {},
+      controllers: {}
+    },
+    mq: {
+      handlers: {},
+      controllers: {}
+    },
+  }
+
+  constructor(private cfg: ParserCFG, private oas_cfg: OASConfig, private comms: SFRProtocols) { }
+
+  async init(base_url?: string): Promise<ServiceDocuments> {
+    this.base_url = base_url;
+    if(this.comms["MQ"]){
+      //Create channels for each type of Communication Pattern
+      const channels = await Promise.all(PATTERNS.map(async (v) => {
+        const channel = await this.comms["MQ"].createChannel();
+        const mq = TARGETED_PATTERN.includes(v) ? new TargetedMQ(channel, v) : new BroadcastMQ(channel, v);
+  
+        return [v, mq];
+      }));
+  
+      this.pattern_channels = Object.fromEntries(channels);
+  
+
+      SFRPipeline.injections.rest.handlers = {
+        ...SFRPipeline.injections.rest.handlers,
+        mq: this.pattern_channels
+      }
+      
+      SFRPipeline.injections.mq.handlers = {
+        ...SFRPipeline.injections.mq.handlers,
+        mq: this.pattern_channels
+      }
+    }
+
+    //Declarations for each protocol in key/value pairs.
+    let protocols = await this.file_parsing();
+    
+    //Filter protocols that have been parsed if its' associated SFRProtocol has been defined
+    /* @ts-ignore */
+    protocols = Object.fromEntries(Object.entries(protocols).filter(([k])=> this.comms[k]).map(([k, v])=> [k, v]));
+    await this.fn_binding(protocols);
+
+    this.print_to_console();
+
+    return this.spec_generation(protocols);
+  }
+
+  // Handles the parsing of SFR files from the directory specified under cfg.out config.
+  // It returns a standard NamespaceDeclaration containing each declaration of each supported protocol.
+  private async file_parsing() {
+    //These are the officially supported protocols of the SFR library
+    const SUPPORTED_PROTOCOLS = ["rest", "ws", "mq"];
+
+    /*
+      Look for folders that match the supported protocols listed above in the designated directory
+  
+      cfg.root = "Specifies the working directory"
+      cfg.path = "Specifies the API directory i.e: where SFR files reside"
+      cfg.out  = "Specifies the directory where the resulting OAS documents are outputted"
+    */
+    const directory = path.join(CWD, this.cfg.root);
+    let paths = SUPPORTED_PROTOCOLS.map((v) => path.join(directory, `${this.cfg.path}/${v}`));
+    //Create the directories if it doesn't exist.
+    await Promise.all(paths.map((v) => fs.mkdir(v, { recursive: true })));
+    //Recursively retrieve all SFRs of each protocol
+    let sfr_paths = await Promise.all(paths.map((path) => resolve_sfrs(path)));
+    //Import SFRs
+    const protocols = await Promise.all(sfr_paths.map((protocol) => import_sfrs(protocol)));
+    const REST: RESTNamespaceDeclaration = protocols[0];
+    logger.info(`${Object.keys(protocols[0]).length} REST SFR`)
+    const WS: WSNamespaceDeclaration = protocols[1];
+    logger.info(`${Object.keys(protocols[1]).length} WS SFR`)
+    const MQ: MQNamespaceDeclaration = protocols[2];
+    logger.info(`${Object.keys(protocols[2]).length} MQ SFR`)
+
+    return { REST, WS, MQ } as NamespaceDeclaration;
+  }
+
+  // Handles the binding of the components of each SFR (e.g: executing validators of matching endpoints, injecting controllers to each handler, etc.)
+  //Owing to their differing nature, spec generation and fn_binding is handled this way so as to split up the individual logics involved in parsing them. 
+  private async fn_binding(protocols: NamespaceDeclaration) {
+    Object.entries(protocols).forEach(([protocol, declaration]) => {
+      switch (protocol) {
+        case "REST": this.bind_rest_fns(declaration as RESTNamespaceDeclaration); break;
+        case "WS": this.bind_ws_fns(declaration as WSNamespaceDeclaration); break;
+        case "MQ": this.bind_mq_fns(declaration as MQNamespaceDeclaration); break;
+      }
+    });
+  }
+  /* Fn Binding */
+  private async bind_rest_fns(declaration: RESTNamespaceDeclaration) {
+    const comms = this.comms["REST"];
+    if (!comms) throw new Error(`FN Binding failed: \nREST protocol lacks it's associated SFRProtocols`);
+
+    Object.entries(declaration).forEach(([namespace, module]) => {
+      let { cfg, validators, handlers } = module.content;
+      //Set base_directory
+      /* 
+        Directory Order:
+        this.base_url -> Folder Structure -> cfg.base_dir
+      */
+      let base_dir = "";
+      
+      if(this.base_url)base_dir = `/${this.base_url}`;
+      if(module.dir)base_dir += `/${module.dir.toString().replaceAll(",", "/")}`;
+      if(cfg.base_dir)base_dir += `/${cfg.base_dir}`;
+      logger.info(`[SFR ${module.name}] resolved path: ${base_dir}/${namespace}`);
+
+      const is_public = Boolean(cfg.public);
+      //Loop over all methods and their respective handlers
+      Object.entries(handlers).forEach(([method, handler_map]) => {
+        for (const [name, handler] of Object.entries(handler_map).filter(([k]) => validators[k])) {
+          const dir = `${base_dir}/${namespace}/${name}`;
+          console.log(dir)
+          const validator = validators[name];
+          const validator_type = typeof validator !== "function" ? "joi" : "multer";
+
+          /* bind validators */
+          switch (validator_type) {
+            case "joi": {
+              comms[method.toLowerCase() as RESTRequestType](dir, (req, res, next) => {
+                let error: string | boolean = true;
+
+                if (is_public) {
+                  //if(!req.session.user)return res.status(401).json({error : "Session not found."});
+                }
+
+                error = template(validator, method === "GET" ? req.query : req.body);
+                if (error) return res.status(400).json({ error });
+                next();
+              });
+            } break;
+
+            case "multer": {
+              comms[method.toLowerCase() as RESTRequestType](dir, validator as RequestHandler);
+
+              /* @ts-ignore */
+              comms.use((err, req, res, next) => {
+                let temp = { error: err.message, details: err.cause };
+                if (err) return res.status(400).json(temp);
+                next();
+              });
+            } break;
+          }
+
+          /* Bind to express app */
+          comms[method.toLowerCase()](dir, handler.fn);
+          this.mount_data.rest++;
+        }
+
+      });
+    });
+  }
+  private async bind_ws_fns(declaration: WSNamespaceDeclaration) {
+
+  }
+  private async bind_mq_fns(declaration: MQNamespaceDeclaration) {
+    const comms = this.comms["MQ"];
+    if (!comms) throw new Error(`FN Binding failed: \nMQ protocol lacks it's associated SFRProtocols`);
+    
+    Object.entries(declaration).forEach(([namespace, module]) => {
+      let { cfg, validators, handlers } = module.content;
+      //Set base_directory
+      let base_dir = cfg.base_dir ? `/${cfg.base_dir}` : "";
+      if (this.base_url) base_dir = `/${this.base_url}/${base_dir}`;
+      if (module.dir) base_dir = `${module.dir.toString().replaceAll(",", "/")}/${base_dir}`
+      const is_public = Boolean(cfg.public);
+
+      //Loop over all methods and their respective handlers
+      Object.entries(handlers).forEach(([pattern, handler_map]: [CommunicationPattern, MQRequestHandlerMap]) => {
+        //Get associated MQ for pattern
+        let mq = this.pattern_channels[pattern];
+
+        //Get all valid handlers (i.e: those with matching validators)
+        const valid_handlers = Object.entries(handler_map).filter(([k]) => validators[k]);
+
+        //Loop over each handler
+        for (let [name, handler] of valid_handlers) {
+          const dir = `${base_dir}${namespace}/${name}`;
+          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) {
+            const error = template(validator, msg.content);
+
+            if (error) {
+              if (mq instanceof TargetedMQ) {
+                if (error) {
+                  switch (pattern) {
+                    case "Request-Reply": mq.reply(msg, { error }); break;
+                    default: mq.channel.reject(msg, false);
+                  }
+                }
+              }
+
+              if (mq instanceof BroadcastMQ) {
+                mq.channel.reject(msg, false);
+              }
+            }
+
+            handler.fn(msg);
+          }
+
+          /* bind validators */
+          if (mq instanceof TargetedMQ) {
+            mq.consume(dir, {
+              options: handler.options,
+              fn: validator_fn
+            })
+          }
+
+          if (mq instanceof BroadcastMQ) {
+            switch (pattern) {
+              case "Publish-Subscribe": {
+                mq.subscribe(dir, "", {
+                  options: handler.options,
+                  fn: validator_fn
+                })
+              } break;
+
+              case "Routing": {
+                /* @ts-ignore */
+                mq.subscribe(dir, handler.routing_key, {
+                  options: handler.options,
+                  fn: validator_fn
+                });
+              }
+
+              case "Topic": {
+                /* @ts-ignore */
+                mq.subscribe(dir, handler.binding_key, {
+                  options: handler.options
+                });
+              }
+            }
+          }
+
+          this.mount_data.mq++;
+        }
+      });
+    });
+  }
+
+  // Generate OpenAPI and AsyncAPI specification.
+  private spec_generation(protocols: NamespaceDeclaration): ServiceDocuments {
+    // Holds the key/value pair of protocols and their respective API Documentation
+    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)];
+        default: throw new Error(`Failed to generate SFR Spec: ${protocol} protocol is unknown.`);
+      }
+    });
+
+    return Object.fromEntries(documents);
+  }
+
+  private generate_open_api_document(declaration: RESTNamespaceDeclaration) {
+    // This will hold the final OpenAPI Document.
+    const spec: OAPI_Document = {
+      openapi: "3.0.0",
+      info : Object.assign({}, this.oas_cfg),
+      paths: {}
+    };
+
+    // Iterate through each protocol (e.g., REST, WS, MQ)
+    Object.entries(declaration).forEach(([namespace, module]) => {
+      const { cfg, handlers, validators } = module.content;
+
+      //Set base_directory
+      let base_dir = cfg.base_dir ? `/${cfg.base_dir}/` : "/";
+      if (this.base_url) base_dir = `/${this.base_url}${base_dir}`;
+      if (module.dir) base_dir = `${module.dir.toString().replaceAll(",", "/")}/${base_dir}`
+      // Collect the OpenAPI path object for each handler (method)
+      for (let [method, handler_map] of Object.entries(handlers)) {
+        //Transform method to lowercase
+        method = method.toLowerCase();
+
+        // Define the operation (method) for this endpoint
+        for (const [endpoint, body] of Object.entries(handler_map)) {
+          const validator: any = validators[endpoint];
+          // Skip if no matching validator
+          if (!validator) continue;
+          const validator_type = typeof validator !== "function" ? "joi" : "multer";
+          
+          //Default tags are used for service and router level classification (developer platform)
+          let default_tags = [
+            `sfr-router:${namespace}`,
+            `sfr-service:${this.oas_cfg.title || "unspecified"}`
+          ];
+
+          if (body.tags && Array.isArray(body.tags)) default_tags.push(...body.tags);
+
+          const operation_id = `${base_dir}${namespace}/${endpoint}`;
+          const document: any = {
+            operationId : `${method.toUpperCase()}:${operation_id}`,
+            summary     : body.summary || "",
+            description : body.description || "",
+            tags        : default_tags,
+            public      : Boolean(cfg.public),
+
+            responses: {
+              "200": {
+                description: "Successful operation",
+                content: { "application/json": { schema: { type: "object" } } }
+              },
+              "400": {
+                description: "An error has occured",
+                content: { "application/json": { schema: { type: "object" } } }
+              }
+            }
+          };
+
+          //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
+          if(validator_type === "multer"){
+          }
+
+          //Create path if it does not exist.
+          if (!spec.paths[operation_id]) spec.paths[operation_id] = {};
+          if (!spec.paths[operation_id][method.toLowerCase()]) spec.paths[operation_id][method.toLowerCase()] = document;
+        }
+      }
+    });
+
+    //Conform to OAPI standards by appending "x-property" on each field under "meta"
+    /* @ts-ignore */
+    spec.info.meta = Object.fromEntries(Object.entries(spec.info.meta).map(([k, v])=> [`x-${k}`, v]));
+
+    return spec;
+  }
+
+  // Method to generate an AsyncAPI document from an MQNamespaceDeclaration
+  private generate_async_api_document(declaration: MQNamespaceDeclaration): AsyncAPIDocument {
+    // This will hold the final AsyncAPI Document.
+    const spec = {
+      asyncapi: '3.0.0',
+      info : Object.assign({}, this.oas_cfg),
+
+      channels: {},
+      operations: {},
+      components: {
+        messages: {},
+      },
+    };
+
+    //Conform to OAPI standards by appending "x-property" on each field under "meta"
+    /* @ts-ignore */
+    spec.info.meta = Object.fromEntries(Object.entries(spec.info.meta).map(([k, v])=> [`x-${k}`, v]));
+
+
+    Object.entries(declaration).forEach(([namespace, module]) => {
+      let { cfg, validators, handlers } = module.content;
+      //Set base_directory
+      let base_dir = cfg.base_dir ? `/${cfg.base_dir}/` : "";
+      if (this.base_url) base_dir = `/${this.base_url}/${base_dir}`;
+      if (module.dir) base_dir = `${module.dir.toString().replaceAll(",", "/")}/${base_dir}`
+      const is_public = Boolean(cfg.public);
+
+      //Loop over all methods and their respective handlers
+      Object.entries(handlers).forEach(([pattern, handler_map]: [CommunicationPattern, MQRequestHandlerMap]) => {
+        //Get associated MQ for pattern
+        let mq = this.pattern_channels[pattern];
+
+        //Get all valid handlers (i.e: those with matching validators)
+        const valid_handlers = Object.entries(handler_map).filter(([k]) => validators[k]);
+
+        //Loop over each handler
+        for (let [name, handler] of valid_handlers) {
+          const dir = `${base_dir}${namespace}/${name}`;
+          const validator:any = validators[name];
+          const validator_type = typeof validator !== "function" ? "joi" : "multer"; // TODO: Dynamically update parameter content based on validator type.
+
+          const channel_document: any = {
+            address : dir,
+            messages : {}
+          }
+
+          const operation_document: any = {
+            action      : "receive",
+            summary     : handler.summary || "",
+            description : handler.description || "",
+            channel     : `#/channels/${name}` 
+          }
+
+          //Insert either a parameter or a requestBody according to the method type
+          if(validator_type === "joi"){
+            channel_document.messages[`${name}-message`] = {
+              name : `${name}-message`,
+              payload : j2s(validator).swagger
+            };
+          }
+          
+          //Haven't found a library for converting multer validators to swagger doc
+          if(validator_type === "multer"){
+          
+          }
+
+          spec.channels[name] = channel_document;
+          spec.operations[name] = operation_document;
+        }
+      });
+    });
+
+    return spec;
+  }
+
+
+  // Method to print SFR info to console
+  private print_to_console(){
+    console.log(`____________________________
+|                          | Mounted  
+| ░██████╗███████╗██████╗░ | REST : ${this.mount_data.rest}  
+| ██╔════╝██╔════╝██╔══██╗ | WS   : ${this.mount_data.ws}  
+| ╚█████╗░█████╗░░██████╔╝ | MQ   : ${this.mount_data.mq}  
+| ░╚═══██╗██╔══╝░░██╔══██╗ |-----------
+| ██████╔╝██║░░░░░██║░░██║ | Protocols 
+| ╚═════╝░╚═╝░░░░░╚═╝░░╚═╝ | REST : ${this.comms["REST"] ? "✅" : "❌"} 
+| Single File Router       | MQ   : ${this.comms["MQ"] ? "✅" : "❌"} 
+|                          | WS   : ${this.comms["WS"] ? "✅" : "❌"} 
+¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯`)
+  }
+}
+
+/* Utility fns */
+/* File Parsing */
+async function resolve_sfrs(dir: string, prefix?: string) {
+  //Get Directory Contents
+  const contents = await fs.readdir(dir);
+
+  const results = [];
+  //Loop over contents
+  await Promise.all(contents.map(async (v) => {
+    const content_path = path.join(dir, v);
+    const is_dir = (await fs.lstat(content_path)).isDirectory();
+
+    //If Directory, perform a recursion and return output of contents.map fn.
+    if (is_dir) {
+      const dir_output = await resolve_sfrs(content_path, prefix ? `${prefix}/${v}` : v);
+      results.push(dir_output);
+      return;
+    };
+
+    let output: any = { name: v, path: content_path };
+    if (prefix) output.dir = prefix.split("/");
+    results.push(output);
+  }));
+
+  return results.flat();
+}
+async function import_sfrs(protocol_files: any[]) {
+  const protocols = await Promise.all(protocol_files.map(async (v) => {
+    const import_task = await import(`file:///${v.path}`);
+    return [v.name.replace(".mjs", ""), {
+      ...v,
+      content: import_task.default
+    }];
+  }));
+
+  //Removes SFRs without body.
+  return Object.fromEntries(protocols.filter((v) => v[1].content));
+}
+
+// Method to generate JSON schema for the payload based on handler metadata
+function generate_json_schema(metadata: SFRMetadata): any {
+  return {
+    type: 'object',
+    properties: {
+      example_field: {
+        type: 'string',
+        ...metadata
+      },
+    },
+    required: ['example_field'],
+  };
+}

package/src/templates.mts

@@ -0,0 +1,55 @@
+//Previous Name: RequestHandlerFactory
+//Dependencies are imported and used by the functions below
+import { SFRPipeline } from "./sfr-pipeline.mjs";
+
+export function REST<V, H, C>(struct : RESTHandlerDescriptor<V, H, C>) : H & C {
+  const validators  : RequestValidators   = struct.validators  || {};
+  const controllers : RequestControllers  = struct.controllers || {};
+  const handlers    : RESTRequestHandlers = struct.handlers    || {};
+  const cfg         : SFRConfig           = struct.cfg         || {};
+
+  //Bind controller injections to each controllers
+  Object.entries(controllers).map(([k, v])=>controllers[k] = v.bind({...SFRPipeline.injections.rest.controllers}) as RequestController);
+
+  //Bind handler injections and SFR controllers into each handlers.
+  Object.entries(handlers).forEach(([method, handlermap])=>{
+    Object.entries(handlermap).forEach(([k, v])=> {
+      /* @ts-ignore */      
+      handlers[method][k] = {...v, fn : v.fn.bind({ ...controllers, ...SFRPipeline.injections.rest.handlers })};
+    });
+  });
+  /* @ts-ignore */
+  return { validators, controllers, handlers, cfg } as H & C
+}
+
+export function WS<V, H, C>(struct : WSHandlerDescriptor<V, 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 }
+}
+
+export function MQ<V, H, C>(struct : MQHandlerDescriptor<V, H, C>): H & C{
+  const validators  : RequestValidators     = struct.validators  || {};
+  const controllers : RequestControllers    = struct.controllers || {};
+  const handlers    : MQRequestHandlers<C>  = struct.handlers    || {};
+  const cfg         : SFRConfig             = struct.cfg         || {};
+
+  //Bind controller injections to each controllers
+  Object.entries(controllers).map(([k, v])=>controllers[k] = v.bind({...SFRPipeline.injections.mq.controllers}) as RequestController);
+
+  //Bind handler injections and SFR controllers into each handlers.
+  Object.entries(handlers).forEach(([pattern, handlermap])=>{
+    Object.entries(handlermap).forEach(([k, v])=> {
+      /* @ts-ignore */
+      const {mq} = (SFRPipeline.injections.mq.handlers || {});
+      /* @ts-ignore */
+      handlers[pattern][k] = {...v, fn : v.fn.bind({ ...controllers, mq : mq ? mq[pattern] : null })};
+    });
+  });
+  /* @ts-ignore */
+  return { validators, controllers, handlers, cfg } as H & C;
+}