@avtechno/sfr 1.0.0

package/dist/types/templates.d.mts

@@ -0,0 +1,8 @@
+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 MQ<V, H, C>(struct: MQHandlerDescriptor<V, H, C>): H & C;

package/dist/types/util.d.mts

@@ -0,0 +1,7 @@
+import { Response } from "express";
+import Joi from "joi";
+export declare function get_stats(dirs: string[], base_dir: string): Promise<string[]>;
+export declare function assess_namespace(stats: string[], dir: string): Promise<any>;
+export declare const template: (rule: object, v: object) => string | false;
+export declare const object_id: Joi.StringSchema<string>;
+export declare const handle_res: (controller: Promise<any>, res: Response) => void;

package/dist/util.mjs

@@ -0,0 +1,25 @@
+import fs from "fs/promises";
+import path from "path";
+import Joi from "joi";
+export async function get_stats(dirs, base_dir) {
+    let temp = await Promise.all(dirs.map((v) => fs.lstat(path.join(base_dir, v)).then((stats) => ({ stats, dir: v }))));
+    const result = temp.filter(({ stats }) => stats.isFile()).map((v) => v.dir);
+    return result;
+}
+export async function assess_namespace(stats, dir) {
+    let dirs = stats.map((v) => `file:///${dir.replaceAll("\\", "/")}/${v}`);
+    const result = await Promise.all(dirs.map((d) => import(d).then((v) => [d.replace(".mjs", "").substring(d.lastIndexOf("/") + 1), v.default]))).then(Object.fromEntries);
+    return result;
+}
+export const template = (rule, v) => _validate(Joi.object(rule).validate(v));
+function _validate(expression) {
+    let result = expression.error;
+    return result ? result.details[0].message : false;
+}
+export const object_id = Joi.string().hex().length(24).required();
+/* QoLs */
+export const handle_res = (controller, res) => {
+    controller
+        .then((data) => res.json({ data }))
+        .catch((error) => res.status(400).json({ error }));
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@avtechno/sfr",
+  "version": "1.0.0",
+  "description": "An opinionated way of writing services using ExpressJS.",
+  "type": "module",
+  "files": [
+    "dist",
+    "lib",
+    "src"
+  ],
+  "main": "./dist/index.mjs",
+  "types": "./dist/types/index.d.mts",
+  "exports": {
+    "types": "./dist/types/index.d.mts",
+    "default": "./dist/index.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"
+  },
+  "prepublish": "tsc",
+  "author": "Emmanuel Abellana",
+  "license": "ISC",
+  "dependencies": {
+    "amqplib": "0.10.7",
+    "express": "^4.18.2",
+    "express-session": "^1.17.3",
+    "file-type": "^18.5.0",
+    "joi": "^17.11.0",
+    "joi-to-swagger": "^6.2.0",
+    "js-yaml": "^4.1.0",
+    "multer": "^1.4.5-lts.1",
+    "socket.io": "^4.7.2",
+    "winston": "^3.17.0"
+  },
+  "devDependencies": {
+    "@types/amqplib": "^0.10.5",
+    "@types/express": "^4.17.19",
+    "@types/express-session": "^1.18.0",
+    "@types/js-yaml": "^4.0.7",
+    "@types/multer": "^1.4.11",
+    "@types/openapi-v3": "^3.0.0",
+    "openapi-types": "^12.1.3",
+    "rimraf": "^5.0.1",
+    "typedoc": "^0.25.2",
+    "typescript": "^5.2.2"
+  }
+}

package/src/example.mts

@@ -0,0 +1,35 @@
+import Joi from "joi";
+import { REST } from "./templates.mjs";
+
+
+export default REST({
+  cfg : {
+    base_dir : "example",
+    public : false,
+  },
+  validators: {
+    "get-something": {
+      "name": Joi.string().required(),
+      "age": Joi.number().required(),
+    }
+  },
+  handlers: {
+    GET : {
+      "get-something": {
+        description : "Get something I guess?",
+        async fn(req, res){
+          const result = await this.db_call()
+          res.status(200).json({
+            data: result
+          });
+        }
+      }
+    }
+  },
+  controllers: {
+    async db_call(){
+      /* Perform database calls here through accessing the "this" context (if injections are set) */
+      return "Something";
+    }
+  }
+})

package/src/index.mts

@@ -0,0 +1,99 @@
+/// <reference path="types/index.d.ts" />
+import yaml from "js-yaml";
+import path from "path";
+import fs from "fs/promises";
+
+import { REST, WS, MQ } from "./templates.mjs";
+import { SFRPipeline } from "./sfr-pipeline.mjs";
+import { MQLib } from "./mq.mjs";
+
+const cwd = process.cwd();
+
+export default async (cfg: ParserCFG, oas_cfg: OASConfig, connectors: SFRProtocols, base_url?: string):Promise<ServiceManifest> => {
+  //TODO: Verify connectors
+  const sfr = new SFRPipeline(cfg, oas_cfg, connectors);
+
+  // Returned service artifacts for both OpenAPI and AsyncAPI are written into the server directory
+  // An express static endpoint is pointed to this directory for service directory.
+  const documents = await sfr.init(base_url);
+
+  write_service_discovery(cfg, documents);//Writes services to output dir (cfg.out)
+  
+  return {
+    ...oas_cfg,
+    documents
+  };
+};
+
+async function write_service_discovery(cfg: ParserCFG, documents: ServiceDocuments) {
+  //Setup files in case they do not exist.
+
+  //Setup output folder
+  await fs.mkdir(path.join(cwd, cfg.out), { recursive: true });
+
+  // Loop over each protocol
+  for (let [protocol, documentation] of Object.entries(documents)) {
+    //Strictly await for setup to create dirs for each protocol.
+    await fs.mkdir(path.join(cwd, cfg.out, protocol.toLowerCase()), { recursive: true });
+    //Convert documentation into service manifest.
+
+    //OpenAPI Documents  : paths
+    //AsyncAPI Documents : channels
+    switch (protocol) {
+      case "REST": {
+        documentation = documentation as OAPI_Document;
+        for (const [path, methods] of Object.entries(documentation.paths)) {
+          write_to_file(cfg, `rest/${path}`, methods);
+        }
+      } break;
+
+      case "WS": {
+
+      } break;
+
+      case "MQ": {
+        documentation = documentation as AsyncAPIDocument;
+        write_to_file(cfg, "mq/index.yaml", documentation);
+      }
+    }
+  }
+}
+
+//Tasked with recursively creating directories and spec files.
+async function write_to_file(cfg: ParserCFG, dir: string, data: object) {
+  //Path is a slash(/) delimited string, with the end delimiter indicating the filename to be used.
+  const paths = dir.split("/");
+
+  //Indicates a root file
+  if (paths.length === 1) {
+    await fs.writeFile(path.join(cwd, cfg.out, paths[0]), yaml.dump(data), { flag: "w+" });
+  } 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+" });
+  }
+}
+
+function inject(injections : InjectedFacilities){
+  SFRPipeline.injections.rest.handlers = {
+    ...SFRPipeline.injections.rest.handlers,
+    ...injections.handlers
+  }
+
+  SFRPipeline.injections.rest.controllers = {
+    ...SFRPipeline.injections.rest.controllers,
+    ...injections.controllers
+  }
+
+  SFRPipeline.injections.mq.handlers = {
+    ...SFRPipeline.injections.mq.handlers,
+    ...injections.handlers
+  }
+
+  SFRPipeline.injections.mq.controllers = {
+    ...SFRPipeline.injections.mq.controllers,
+    ...injections.controllers
+  }
+}
+
+export { REST, WS, MQ, MQLib, inject };

package/src/logger.mts

@@ -0,0 +1,52 @@
+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 };

package/src/mq.mts

@@ -0,0 +1,236 @@
+import { Connection, Options, connect, Channel, ConsumeMessage } from "amqplib";
+
+/**
+ * MQLib class for establishing a connection to the message queue and creating channels.
+ */
+export class MQLib {
+  private connection?: Connection;
+  private channel?: Channel;
+
+  /**
+   * Initializes the connection and channel to the message queue.
+   * 
+   * @param MQ_URL - The URL of the message queue.
+   * @example
+   * const mqLib = new MQLib();
+   * await mqLib.init("amqp://localhost");
+   */
+  async init(MQ_URL: string) {
+    await connect(MQ_URL)
+      .then(async (v) => {
+        //@ts-ignore
+        this.connection = v;
+        this.channel = await v.createChannel();
+      });
+  }
+
+  /**
+   * Returns the connection object.
+   * 
+   * @returns The connection object to the message queue.
+   */
+  get_connection() {
+    return this.connection;
+  }
+
+  /**
+   * Returns the channel object.
+   * 
+   * @returns The channel object to the message queue.
+   */
+  get_channel() {
+    return this.channel;
+  }
+}
+
+/**
+ * BroadcastMQ class to handle different types of broadcast communication patterns: Publish-Subscribe, Routing, and Topic.
+ */
+export class BroadcastMQ {
+  constructor(public channel: Channel, protected type: CommunicationPattern) {}
+
+  /**
+   * Publishes a message to the specified exchange based on the communication pattern.
+   * 
+   * @param exchange - The name of the exchange to send the message to.
+   * @param key - The routing key or pattern to use, depending on the communication pattern.
+   * @param payload - The message to be sent.
+   * @param options - Additional publishing options.
+   * @example
+   * // Publish a message to a 'logsExchange' with a routing key 'error' for a routing pattern.
+   * const mq = new BroadcastMQ(channel, "Routing");
+   * mq.publish("logsExchange", "error", { level: "error", message: "Something went wrong" });
+   */
+  async publish(exchange: string, key: string, payload: any, options?: Options.Publish) {
+    switch (this.type) {
+    case "Publish-Subscribe": {
+      await this.channel.assertExchange(exchange, "fanout", { durable: false });
+      this.channel.publish(exchange, "", encode_payload(payload), options);
+      break;
+    }
+
+    case "Routing": {
+      await this.channel.assertExchange(exchange, "direct", { durable: false });
+      this.channel.publish(exchange, key, encode_payload(payload), options);
+      break;
+    }
+
+    case "Topic": {
+      await this.channel.assertExchange(exchange, "topic", { durable: false });
+      this.channel.publish(exchange, key, encode_payload(payload), options);
+      break;
+    }
+    }
+  }
+
+  /**
+   * Subscribes to an exchange to receive messages based on the communication pattern.
+   * 
+   * @param exchange - The name of the exchange to subscribe to.
+   * @param key - The routing key or pattern to listen for.
+   * @param cfg - Configuration options for the consumer, including the callback function.
+   * @param options - Additional consumption options.
+   * @example
+   * // Subscribe to the 'logsExchange' for all 'error' messages in the Routing pattern.
+   * const mq = new BroadcastMQ(channel, "Routing");
+   * mq.subscribe("logsExchange", "error", { fn: handleErrorLogs, options: { noAck: true } });
+   */
+  async subscribe(
+    exchange: string,
+    key: string,
+    cfg: ConsumerConfig,
+    options?: Options.Publish
+  ) {
+    let fn = cfg.fn.bind({ channel: this.channel, type: this.type });
+
+    switch (this.type) {
+    case "Publish-Subscribe": {
+      await this.channel.assertExchange(exchange, "fanout", { durable: false });
+      const { queue } = await this.channel.assertQueue("", { exclusive: true });
+
+      this.channel.bindQueue(queue, exchange, "");
+      this.channel.consume(queue, (v) => fn(parse_payload(v)), cfg.options);
+      break;
+    }
+
+    case "Routing": {
+      await this.channel.assertExchange(exchange, "direct", { durable: false });
+      const { queue } = await this.channel.assertQueue("", { exclusive: true });
+      await this.channel.bindQueue(queue, exchange, key);
+
+      this.channel.consume(queue, (v) => fn(parse_payload(v)), options);
+      break;
+    }
+
+    case "Topic": {
+      await this.channel.assertExchange(exchange, "topic", { durable: false });
+      const { queue } = await this.channel.assertQueue("", { exclusive: true });
+
+      this.channel.bindQueue(queue, exchange, key);
+      this.channel.consume(queue, (v) => fn(parse_payload(v)), options);
+      break;
+    }
+    }
+  }
+}
+
+/**
+ * TargetedMQ class to handle Point-to-Point and Request-Reply communication patterns.
+ */
+export class TargetedMQ {
+  constructor(public channel: Channel, protected type: CommunicationPattern) {}
+
+  /**
+   * Sends a message to the specified queue depending on the communication pattern.
+   * 
+   * @param binding - The name of the queue or binding to send the message to.
+   * @param payload - The message to be sent.
+   * @param options - Additional publishing options.
+   * @example
+   * // Send a message to a queue for point-to-point communication
+   * const mq = new TargetedMQ(channel, "Point-to-Point");
+   * mq.produce("taskQueue", { taskId: 1, action: "process" });
+   */
+  async produce(binding: string, payload: any, options?: Options.Publish) {
+    /* Alter produce strategy depending on the instance's configured comm pattern */
+    switch (this.type) {
+    case "Point-to-Point": {
+      await this.channel.assertQueue(binding);
+      return this.channel.sendToQueue(binding, encode_payload(payload), options);
+    }
+
+    case "Request-Reply": {
+      await this.channel.assertQueue(binding);
+      return this.channel.sendToQueue(binding, encode_payload(payload), options);
+    }
+    }
+  }
+
+  /**
+   * Sends a reply to the message sender in a Request-Reply pattern.
+   * 
+   * @param msg - The original message to reply to.
+   * @param payload - The reply message to send back to the requester.
+   * @example
+   * // Send a response back to the client in a Request-Reply pattern
+   * const mq = new TargetedMQ(channel, "Request-Reply");
+   * mq.reply(msg, { result: "Processed successfully" });
+   */
+  async reply(msg: ConsumeMessage, payload: any) {
+    if (this.type !== "Request-Reply") return;
+
+    this.channel.sendToQueue(msg.properties.replyTo, encode_payload(payload));
+    this.channel.ack(msg);
+  }
+
+  /**
+   * Consumes messages from the specified queue based on the communication pattern.
+   * 
+   * @param queue - The name of the queue to consume messages from.
+   * @param cfg - Configuration options for the consumer, including the callback function.
+   * @example
+   * // Consume a message from the 'taskQueue' in a Point-to-Point communication pattern
+   * const mq = new TargetedMQ(channel, "Point-to-Point");
+   * mq.consume("taskQueue", { fn: processTask, options: { noAck: true } });
+   */
+  async consume(queue: string, cfg: ConsumerConfig) {
+    let fn = cfg.fn.bind({ channel: this.channel, type: this.type });
+
+    switch (this.type) {
+    case "Point-to-Point": {
+      await this.channel.assertQueue(queue);
+      this.channel.consume(queue, (v) => fn(parse_payload(v)), cfg.options);
+      break;
+    }
+
+    case "Request-Reply": {
+      await this.channel.assertQueue(queue);
+      this.channel.consume(queue, (v) => fn(parse_payload(v)), cfg.options);
+      break;
+    }
+    }
+  }
+}
+
+/* Helper Functions */
+
+/**
+ * Parses the payload of a message.
+ * 
+ * @param msg - The consumed message.
+ * @returns The parsed message content.
+ */
+function parse_payload(msg: any) {
+  if(!msg)return {};
+  return { ...msg, content: JSON.parse(msg.content.toString()) };
+}
+
+/**
+ * Encodes a message as a Buffer to be sent over the message queue.
+ * 
+ * @param msg - The message to be encoded.
+ * @returns The encoded message as a Buffer.
+ */
+function encode_payload(msg: any) {
+  return Buffer.from(JSON.stringify(msg));
+}