@vida-global/core 1.1.0

package/lib/server/server.js

@@ -0,0 +1,359 @@
+const   express                = require('express');
+const   fs                     = require('fs');
+const   httpLogger             = require('pino-http')
+const { logger }               = require('../logger');
+const   mustacheExpress        = require('mustache-express');
+const { pino }                 = require('pino');
+const   responseTime           = require('response-time');
+const   IoServer               = require("socket.io")
+const { Server }               = require('http');
+const { SystemController }     = require('./systemController');
+const { AuthorizationError,
+        ValidationError,
+        VidaServerController } = require('./serverController');
+
+
+class VidaServer {
+    #controllerClasses;
+    #_expressServer;
+    #host;
+    #_httpServer;
+    #_ioServer;
+    #port;
+
+
+    constructor({ port, host }={}) {
+        this.#port = port || process.env.VIDA_PORT || 3000;
+        this.#host = host || process.env.VIDA_HOST || 'localhost';
+        this.setupMiddleware();
+        this.configureSettings();
+    }
+
+
+    async listen() {
+        await this.registerControllers();
+
+        this.#httpServer.listen(this.#port, this.#host, () => {
+            this.logger.info(`Server is running on port ${this.#port}`);
+        });
+    }
+
+
+    get host()   { return this.#host; }
+    get port()   { return this.#port; }
+    get logger() { return logger; }
+
+
+    /***********************************************************************************************
+    * WEB SOCKETS
+    ***********************************************************************************************/
+    get #ioServer() {
+        if (!this.#_ioServer) {
+            this.#_ioServer = IoServer(this.#httpServer, {
+                cors: { origin: this.corsOrigins, credentials: true }
+            });
+        }
+
+        return this.#_ioServer;
+    }
+
+
+    emitWebSocketEvent(channel, eventName, eventData) {
+        this.#ioServer.to(channel).emit(eventName, eventData);
+    }
+
+
+    addWebSocketEventHandler(eventName, eventHandler) {
+        this.#ioServer.on(eventName, eventHandler);
+    }
+
+
+    /***********************************************************************************************
+    * MIDDLEWARE
+    ***********************************************************************************************/
+    setupMiddleware() {
+        this.use(this.jsonParsingMiddleware);
+        this.use(responseTime())
+        this.use(express.static('public'))
+        this.use(this.loggingMiddleware);
+        this.use('/static', express.static(this.staticFilesDirectory));
+        this.use(this.connectionAbortedMiddleware);
+
+        this.#expressServer.engine('html', mustacheExpress());
+    }
+
+
+    get jsonParsingMiddleware() {
+        return express.json({
+            limit:          '50Mb', // Increase JSON limit
+            parameterLimit: 50000,  // Increase parameter limit
+            type:           [
+              'application/json',
+              'text/plain',         // AWS sends this content-type for its messages/notifications
+            ]
+        })
+    }
+
+
+    get loggingMiddleware() {
+        return httpLogger({
+            logger: this.middleWareLogger,
+            customLogLevel: (res, err) => {
+                if (res.statusCode >= 500) return 'error';
+                if (res.statusCode >= 400) return 'warn';
+                return 'info';
+            },
+            serializers: {
+                // Format the request log as a string
+                req: (req) => `Request: ${req.method} ${req.url}`,
+                // Format the response log as a string
+                res: (res) => `statusCode=${res.statusCode}, responseTime=${res.get('X-Response-Time')}`,
+            },
+            wrapSerializers: false,
+        })
+    }
+
+
+    get middlewareLogger() {
+      return pino({
+            transport: {
+                level: process.env.LOG_LEVEL ? 'debug' : 'info',
+                target: 'pino-pretty',
+                options: {
+                    colorize: true,
+                    ignore: 'pid,hostname',
+                    translateTime: 'SYS:standard',
+                    messageFormat: '{msg}',
+                }
+            },
+        });
+    }
+
+
+    get staticFilesDirectory() {
+        return `${process.cwd()}/static`;
+    }
+
+
+    get connectionAbortedMiddleware() {
+        return async function (err, req, res, next) {
+            if (err && err.code === 'ECONNABORTED') {
+                return res.status(400).end(); // Don't process this error any further to avoid its logging
+            }
+            next();
+        };
+    }
+
+
+    use() { this.#expressServer.use(...arguments); }
+
+
+    /***********************************************************************************************
+    * SETTINGS
+    ***********************************************************************************************/
+    configureSettings() {
+        this.set('view engine', 'mustache');
+        this.set('views', this.viewsDirectory);
+        this.set('json spaces', 2);
+    }
+
+
+    viewsDirectory() {
+        return `${process.cwd()}/views`;
+    }
+
+
+    get corsOrigins() {
+        return [];
+    }
+    
+
+    set() { this.#expressServer.set(...arguments); }
+
+
+    /***********************************************************************************************
+    * ACTION SETUP
+    * The server searches through all paths defined in `controllerDirectories` for any subclasses
+    * of VidaServerController and registers their actions
+    ***********************************************************************************************/
+    registerControllers() {
+        this.#registerDefaultControllers();
+        this.controllerClasses.forEach((controllerCls => {
+            this.#registerController(controllerCls);
+        }).bind(this));
+    }
+
+
+    #registerDefaultControllers() {
+        this.#registerController(SystemController);
+    }
+
+
+    #registerController(controllerCls) {
+        controllerCls.actions.forEach((action => {
+            this.#registerAction(action, controllerCls)
+        }).bind(this));
+    }
+
+
+    #registerAction(action, controllerCls) {
+        const method         = action.method.toLowerCase();
+        const requestHandler = this.requestHandler(action.action, controllerCls)
+        this['_'+method](action.path, requestHandler);
+    }
+
+
+    _get()    { this.#expressServer.get(...arguments); }
+    _post()   { this.#expressServer.post(...arguments); }
+    _put()    { this.#expressServer.put(...arguments); }
+    _delete() { this.#expressServer.delete(...arguments); }
+    _patch()  { this.#expressServer.patch(...arguments); }
+
+
+    requestHandler(action, controllerCls) {
+        return async function(request, response) {
+            if (process.env.NODE_ENV != 'test') this.logger.info(`${controllerCls.name}#${action}`);
+            const controllerInstance = this.buildController(controllerCls, request, response);
+            await controllerInstance.setupRequestState();
+
+            if (controllerInstance.rendered) {
+                response.end();
+                return;
+            }
+
+            controllerInstance.setupCallbacks();
+
+            const responseBody = await this.performRequest(controllerInstance, action);
+
+            if (!controllerInstance.rendered) {
+                await controllerInstance.render(responseBody || {});
+            }
+
+            response.end();
+        }.bind(this);
+    }
+
+
+    async performRequest(controllerInstance, action) {
+        try {
+            return await this._performRequest(controllerInstance, action);
+        } catch(err) {
+            await this.handleError(err, controllerInstance);
+        }
+    }
+
+
+    async handleError(err, controllerInstance) {
+        if (err.constructor == AuthorizationError) {
+            await controllerInstance.renderUnauthorizedResponse();
+            return;
+
+        } else if (err.constructor == ValidationError) {
+            await controllerInstance.renderErrors(err.errors);
+            return;
+
+        } else {
+            controllerInstance.statusCode = 500;
+            await controllerInstance.render({error: err.message});
+        }
+
+        if (process.env.NODE_ENV == 'development') console.log(err);
+    }
+
+
+    async _performRequest(controllerInstance, action) {
+        if (await controllerInstance.runBeforeCallbacks(action) === false) return false;
+        const responseBody = await controllerInstance[action]();
+        if (await controllerInstance.runAfterCallbacks(action) === false)  return false;
+
+        return responseBody;
+    }
+
+
+    buildController(controllerCls, request, response) {
+        return new controllerCls(request, response);
+    }
+
+
+    get controllerClasses() {
+        if (this.#controllerClasses) return this.#controllerClasses;
+        this.#controllerClasses = [];
+
+        this.controllerDirectories.forEach(dir => {
+          this.#importControllers(dir, dir);
+        });
+
+        return this.#controllerClasses;
+    }
+
+
+    #importControllers(dir, topLevelDirectory) {
+        fs.readdirSync(dir).forEach((f => {
+            const filePath = `${dir}/${f}`;
+            if (fs.lstatSync(filePath).isDirectory()) {
+                this.#importControllers(filePath, topLevelDirectory);
+            } else if (f.endsWith('.js')) {
+                this.#importControllersFromFile(filePath, dir, topLevelDirectory);
+            }
+        }).bind(this));
+    }
+
+    
+    #importControllersFromFile(filePath, dir, topLevelDirectory) {
+        const exports     = Object.values(require(filePath));
+        exports.forEach(_export => {
+            if (_export.prototype instanceof VidaServerController) {
+                const directoryPrefix   = dir.replace(topLevelDirectory, '');
+                _export.directoryPrefix = directoryPrefix;
+                this.#controllerClasses.push(_export);
+            }
+        });
+    }
+
+
+    get controllerDirectories() {
+        return [`${process.cwd()}/controllers`];
+    }
+
+
+    get #expressServer() {
+        if (!this.#_expressServer) this.#_expressServer = express();
+        return this.#_expressServer;
+    }
+
+
+    get #httpServer() { // Needed for io socket to work
+        if (!this.#_httpServer) this.#_httpServer = Server(this.#expressServer);
+        return this.#_httpServer;
+    }
+
+
+    /***********************************************************************************************
+    * DEPRECATED PASS THROUGH METHODS
+    ***********************************************************************************************/
+    get()    { this.handleDeprecatedRoutingCall('get',    arguments); }
+    post()   { this.handleDeprecatedRoutingCall('post',   arguments); }
+    put()    { this.handleDeprecatedRoutingCall('put',    arguments); }
+    patch()  { this.handleDeprecatedRoutingCall('patch',  arguments); }
+    delete() { this.handleDeprecatedRoutingCall('delete', arguments); }
+
+
+    handleDeprecatedRoutingCall(methodName, args) {
+        this.emitRoutingDeprecationWarning(methodName);
+        this.#expressServer[methodName](...args);
+    }
+
+
+    emitRoutingDeprecationWarning(methodName) {
+        if (!this.routingDeprecationWarnings)            this.routingDeprecationWarnings = {}; 
+        if (this.routingDeprecationWarnings[methodName]) return;
+        this.routingDeprecationWarnings[methodName] = true;
+
+        process.emitWarning(`\`${methodName}\` is deprecated for creating routes. Use \`VidaServerController\` instead.`, 'DeprecationWarning');
+    }
+}
+
+
+module.exports = {
+    VidaServer
+}

package/lib/server/serverController.js

@@ -0,0 +1,344 @@
+const { logger }    = require('../logger');
+const { camelize }  = require('inflection');
+
+
+class VidaServerController {
+    #afterCallbacks  = [];
+    #beforeCallbacks = [];
+    #params;
+    #rendered        = false;
+    #request;
+    #requestBody;
+    #requestQuery;
+    #response;
+
+
+    constructor(request, response) {
+        if (this.constructor == VidaServerController) {
+            throw new Error("ServerControllers must be subclasses of VidaServerController");
+        }
+        this.#request  = request;
+        this.#response = response;
+    }
+
+
+    get _request()        { return this.#request  };
+    get _response()       { return this.#response };
+
+    get params()          { 
+        if (!this.#params) {
+            const body   = this.#processRequestData('body');
+            const query  = this.#processRequestData('query');
+            this.#params = {...this._request.params, ...body, ...query};
+        }
+        return structuredClone(this.#params);
+    }
+
+    get requestHeaders()  { return structuredClone(this._request.headers || {}); }
+    get responseHeaders() { return this._response.headers; };
+    get contentType()     { return this.requestHeaders['content-type']; }
+    get logger()          { return logger; }
+    get rendered()        { return this.#rendered }
+
+    get statusCode()          { return this._response.statusCode; }
+    set statusCode(_status)   { this._response.statusCode = _status; }
+
+
+    #processRequestData(key) {
+        const instanceVarKey  = key.charAt(0).toUpperCase() + key.slice(1);
+        const instanceVarName = `#request${instanceVarKey}`;
+        const data            = this._request[key] || {};
+        if (this[instanceVarName] === undefined) {
+            const processedData = {};
+            this[instanceVarName] = processedData;
+            for (let [paramName, paramValue] of Object.entries(data)) {
+                processedData[paramName] = this.#processedRequestDataValue(paramValue)
+            }
+        }
+
+        return structuredClone(this[instanceVarName]);
+    }
+
+
+    #processedRequestDataValue(value) {
+        try {
+            return JSON.parse(value);
+        } catch(err) {
+            return value;
+        }
+    }
+
+
+    async render(body, options={}) {
+        if (typeof body == 'string') {
+            this._response.send(body);
+        } else {
+            body = await this.formatJSONBody(body, options);
+            this._response.json(body);
+        }
+        this.#rendered = true;
+    }
+
+
+    async formatJSONBody(body, options) {
+        body = await this._formatJSONBody(body, options);
+        return {data: body, status: this.statusText};
+    }
+
+
+    async _formatJSONBody(body, options) {
+        if (body === undefined)               return null;
+        if (!body || typeof body != 'object') return body;
+
+        if (body.toApiResponse) {
+            const formattedBody = await body.toApiResponse(options);
+            return await this._formatJSONBody(formattedBody, options);
+
+        } else if (Array.isArray(body)) {
+            for (const idx in body) {
+                body[idx] = await this._formatJSONBody(body[idx], options);
+            }
+
+        } else if (body.constructor == Date) {
+            return body.getTime();
+
+        } else {
+            for (let [key, val] of Object.entries(body)) {
+                body[key] = await this._formatJSONBody(val, options);
+            }
+        }
+
+        return body;
+    }
+
+
+    get statusText() {
+        switch(this.statusCode) {
+            case 200:
+                return 'ok';
+            case 400:
+                return 'bad request'
+            case 401:
+                return 'unauthorized';
+            case 404:
+                return 'not found';
+            case 500:
+                return 'server error';
+        }
+    }
+
+
+    async renderErrors(errors) {
+        this.statusCode = 400;
+        await this.render({ errors });
+    }
+
+
+    async renderNotFoundResponse() {
+        this.statusCode = 404;
+        await this.render();
+    }
+
+
+    async renderUnauthorizedResponse() {
+        this.statusCode = 401;
+        await this.render();
+    }
+
+
+    /***********************************************************************************************
+    * CALLBACKS
+    ***********************************************************************************************/
+    async setupRequestState() {}
+    setupCallbacks() {}
+
+
+    beforeCallback(callback, options={}) {
+        this.#addCallback(callback, options, this.#beforeCallbacks);
+    }
+
+
+    afterCallback(callback, options={}) {
+        this.#addCallback(callback, options, this.#afterCallbacks);
+    }
+
+
+    #addCallback(callback, options, callbacksList) {
+        callbacksList.push({ callback, options });
+    }
+
+
+    async runBeforeCallbacks(actionName) {
+        return await this.#runCallbacks(this.#beforeCallbacks, actionName);
+    }
+
+
+    async runAfterCallbacks(actionName) {
+        return await this.#runCallbacks(this.#afterCallbacks, actionName);
+    }
+
+
+    async #runCallbacks(callbacksList, actionName) {
+        for (const  { callback, options } of callbacksList) {
+            if (!this.#shouldRunCallback(actionName, options)) continue;
+            if (await this[callback]() === false) return false;
+        }
+
+        return true;
+    }
+
+
+    #shouldRunCallback(actionName, options) {
+        if (options.only) {
+            if (Array.isArray(options.only)) return options.only.includes(actionName);
+            return options.only == actionName;
+        }
+
+        if (options.except) {
+            if (Array.isArray(options.except)) return !options.except.includes(actionName);
+            return options.except != actionName;
+        }
+
+        return true;
+    }
+
+
+    /***********************************************************************************************
+    * VALIDATIONS
+    ***********************************************************************************************/
+    async validateParameters(validations) {
+        const errors = {};
+        for (const [parameterName, parameterValidations] of Object.entries(validations)) {
+            const parameterErrors = this.validateParameter(this.params[parameterName], parameterValidations);
+            if (parameterErrors.length) errors[parameterName] = parameterErrors;
+        }
+
+        if (Object.keys(errors).length) throw new ValidationError(errors);
+    }
+
+
+    validateParameter(value, parameterValidations) {
+        const errors = [];
+        for (const [validationType, validationOptions] of Object.entries(parameterValidations)) {
+            const validationMethod = `validate${camelize(validationType)}`;
+            const error = this[validationMethod](value, validationOptions);
+            if (error) errors.push(error);
+        }
+
+        return errors;
+    }
+
+
+    validatePresence(value) {
+        if (!value) return 'required';
+    }
+
+
+    validateIsInteger(value, options) {
+        const num = parseFloat(value);
+        if (/\D/.test(value) || isNaN(num) || !Number.isInteger(num)) return 'must be an integer';
+        if (options && options.gte !== undefined) {
+            if (num < options.gte) return `must be greater than or equal to ${options.gte}`;
+        }
+    }
+
+
+    validateIsDateTime(value) {
+        if (new Date(value) == 'Invalid Date') return 'invalid date';
+    }
+
+
+    validateIsEnum(value, options) {
+        if (!options.enums.includes(value)) return options.error;
+    }
+
+
+    validateFunction(value, fnc) {
+        const error = fnc(value);
+        if (error) return error;
+    }
+
+
+    /***********************************************************************************************
+    * ACTION SETUP
+    * The controller looks for any methods that fit the pattern of `{httpMethod}ActionName`
+    * (e.g. getFooBar) and prepares server routes for them. By default, a method `getFooBar` on a
+    * `BazController` would have an endpoint of  `GET /baz/fooBar`. The server will also prepend
+    * directory names, so if `bazController.js` is nested within the `ban` directory
+    * (e.g. `ban/bazController.js`), the endpoint will be `GET /ban/baz/fooBar`.
+    *
+    * Default routing logic can be overriden by defining custom routes in the `routes` getter. To
+    * provider a custom route for `getFooBar`, `routes` should return an object like:
+    * {getFooBar: '/ban/:accountIdd/foo/:userId/bar'}`
+    ***********************************************************************************************/
+    static get actions() {
+        const actionNames = this.actionNames;
+        return actionNames.map((actionName => {
+            return this._constructAction(actionName);
+        }).bind(this));
+    }
+
+
+    static _constructAction(actionName) {
+        const routePrefix = this.routePrefix
+        const action      = {};
+        const match       = actionName.match(this.actionRegExp);
+
+        action.method = match.groups.method.toUpperCase();
+        action.action = actionName;
+        action.path   = this._routeForAction(action.method, match.groups.path, routePrefix, actionName);
+        return action;
+    }
+
+
+    static _routeForAction(method, path, routePrefix, actionName) {
+        if (this.routes[actionName]) return this.routes[actionName];
+        if (path == 'Index')         return routePrefix;
+
+        path = path.charAt(0).toLowerCase() + path.slice(1);
+        return `${routePrefix}/${path}`;
+    }
+
+
+    static get routePrefix() {
+        const controllerName   = this.name.replace(/Controller$/, '');
+        const controllerPrefix = controllerName.charAt(0).toLowerCase() + controllerName.slice(1);
+        
+        return `${this.directoryPrefix || ''}/${controllerPrefix}`;
+    }
+
+
+    static get routes() {
+        return {};
+    }
+
+
+    static get actionNames() {
+        const methodNames = Object.getOwnPropertyNames(this.prototype);
+        const nameRegExp  = this.actionRegExp;
+        return methodNames.filter(name => nameRegExp.test(name));
+    }
+
+
+    static get actionRegExp() {
+        return new RegExp(/^(?<method>get|post|put|delete|patch)(?<path>[A-Z][a-zA-Z]+)$/);
+    }
+}
+
+
+class AuthorizationError extends Error {}
+class ValidationError    extends Error {
+    #errors;
+    constructor(errors) {
+        super();
+        this.#errors = errors;
+    }
+    get errors() { return structuredClone(this.#errors) }; 
+}
+
+
+module.exports = { 
+    AuthorizationError,
+    ValidationError,
+    VidaServerController
+};