@avtechno/sfr 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+# Single File Router (SFR)
+
+### Overview
+SFR allows the declaration of services including its controllers, handlers and validators in one single file.
+
+Featuring a configurable Inversion of Control pattern for dependency libraries, It allows developers to easily inject dependencies on either handlers or controllers for convenient and easy access.
+
+Due to it's self-contained and structured format, The SFR has allowed for the development of several extensions such as:
+
+* OpenAPI Service Translator
+
+	`A plugin which also uses API-Bundler's ability to extract metadata from individual SFRs
+  It's main purpose is to translate and create service-level documentation which follows the OpenAPI Standard, this essentially opens up doors to extensive tooling support, instrumentation, automated endpoint testing, automated documentation generation, just to name a few.`
+
+* UAC - ACM Self-Registration Scheme
+
+	`The in-house API-Bundler was designed to extract useful information from individual SFRs, termed service-artifacts, they are reported to a centralized authority through the well-documented UAC - ACM Self-Registration Scheme, this is prerogative to the grand scheme of Resource Administration.`
+
+### Structure 
+
+A regular SFR is composed of the following objects
+
+|Object Name|Description|
+|-|-|
+|CFG| configuration information relayed to the API-bundler (service-parser).|
+|Validators|POJO representation of what values are allowed for each endpoint.|
+|Handlers| Express middlewares which acts as the main logic block for each endpoint.|
+|Controllers|Functions that execute calls to the database.|
+
+### Usage
+
+``` javascript
+
+import sfr from "@hawkstow/sfr";
+import express from "express";
+
+const api_path = "api";
+const doc_path = "docs";
+
+const app = express();
+
+/*
+	Note: 
+	SFR Bundler will look for two folders, named "rest" and "ws" inside the "path". 
+	The placement of SFRs define the protocol that they'll use. 
+	`
+	i.e:rest SFRs reside within "rest", websocket SFRs reside in "ws".
+*/
+
+sfr({
+  root : "dist",   //Specifies the working directory
+  path : api_path, //Specifies the API directory i.e: where SFR files reside
+  out  : doc_path  //Specifies the directory for the resulting OAS documents
+}, app);
+
+```
+
+### Error-Handling
+The library automatically handles errors on both handlers and controllers, however, care must be taken on how error-handling is done by the developer, the following table illustrates what error-handling styles are allowed for both cases.
+
+|Handlers|Controllers|
+|-|-|
+|Exception Throws|Promise.resolve/reject returns|
+|Passing Exceptions to Next fn||
+
+
+### Bug Reporting
+If you've found a bug, please file it in our Github Issues Page so we can have a look at it, perhaps fix it XD
+
+TODO:
+* Multer Upload Validation
+* Built-in Logging

package/dist/example.mjs

@@ -0,0 +1,33 @@
+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/dist/index.mjs

@@ -0,0 +1,84 @@
+/// <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, oas_cfg, connectors, base_url) => {
+    //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, documents) {
+    //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;
+                    for (const [path, methods] of Object.entries(documentation.paths)) {
+                        write_to_file(cfg, `rest/${path}`, methods);
+                    }
+                }
+                break;
+            case "WS":
+                {
+                }
+                break;
+            case "MQ": {
+                documentation = documentation;
+                write_to_file(cfg, "mq/index.yaml", documentation);
+            }
+        }
+    }
+}
+//Tasked with recursively creating directories and spec files.
+async function write_to_file(cfg, dir, data) {
+    //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) {
+    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/dist/logger.mjs

@@ -0,0 +1,37 @@
+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/dist/mq.mjs

@@ -0,0 +1,217 @@
+import { connect } from "amqplib";
+/**
+ * MQLib class for establishing a connection to the message queue and creating channels.
+ */
+export class MQLib {
+    connection;
+    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) {
+        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 {
+    channel;
+    type;
+    constructor(channel, type) {
+        this.channel = channel;
+        this.type = type;
+    }
+    /**
+     * 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, key, payload, options) {
+        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, key, cfg, options) {
+        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 {
+    channel;
+    type;
+    constructor(channel, type) {
+        this.channel = channel;
+        this.type = type;
+    }
+    /**
+     * 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, payload, options) {
+        /* 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, payload) {
+        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, cfg) {
+        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) {
+    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) {
+    return Buffer.from(JSON.stringify(msg));
+}