@vida-global/core 1.4.5 → 2.0.0

package/lib/server/serverController.js

@@ -1,9 +1,12 @@
-const { logger }                 = require('../logger');
+const   APM                      = require('../apm');
 const { camelize, singularize }  = require('inflection');
 const   Errors                   = require('./errors');
+const { logger }                 = require('../logger');
+const   nodeUtil                 = require('util');
 
 
 const AUTH_CALLBACK_NAME = 'authenticateRequest';
+const actionStore        = new WeakMap();
 
 
 class VidaServerController {
@@ -12,18 +15,22 @@ class VidaServerController {
     #beforeCallbacks       = [];
     #beforeCallbacksToSkip = [];
     #callbacksSetUp        = false;
+    #isStreaming           = false;
+    #logger;
     #params;
     #rendered              = false;
     #request;
     #response;
+    #streamAbortController;
 
 
-    constructor(request, response) {
+    constructor(request, response, serverLogger) {
         if (this.constructor == VidaServerController) {
             throw new Error("ServerControllers must be subclasses of VidaServerController");
         }
         this.#request  = request;
         this.#response = response;
+        this.#logger   = (serverLogger || logger).child(this.requestId);
 
         this.#applyCallbacks();
         this.#setupStatusRenderers();
@@ -41,16 +48,33 @@ class VidaServerController {
         return structuredClone(this.#params);
     }
 
+    get requestId()       { return this._request.id; }
     get requestHeaders()  { return structuredClone(this._request.headers || {}); }
     get responseHeaders() { return this._response.headers; };
     get requestBody()     { return this._request.body; }
+    get requestMethod()   { return this._request.method; }
+    get requestIp()       { return this._request.ip; }
+    get url()             { return this._request.originalUrl; }
     get contentType()     { return this.requestHeaders['content-type']; }
-    get logger()          { return logger; }
-    get rendered()        { return this.#rendered }
-    markRendered()        { this.#rendered = true; }
+    get userAgent()       { return this.requestHeaders['user-agent']; }
+
+    get statusCode()        { return this._response.statusCode; }
+    set statusCode(_status) { this._response.statusCode = _status; }
+
+
+    get logger() {
+        return this.#logger;
+    }
 
-    get statusCode()          { return this._response.statusCode; }
-    set statusCode(_status)   { this._response.statusCode = _status; }
+
+    get bearerToken() {
+      const auth = this.requestHeaders.authorization;
+      if (!auth) return null;
+
+      const match = /^\s*bearer\s+(.+)$/i.exec(auth);
+      if (!match) return null;
+      return match[1].trim();
+    }
 
 
     #processRequestData(key) {
@@ -80,6 +104,7 @@ class VidaServerController {
     ***********************************************************************************************/
     async performRequest(action) {
         try {
+            APM.setControllerName(this.constructor.name, action);
             await this.#performRequest(action)
         } catch(err) {
             await this.#handleError(err);
@@ -88,7 +113,7 @@ class VidaServerController {
 
 
     async #performRequest(action) {
-        await this.setupRequestState();
+        await APM.startSegment('setupRequestState', true, () => this.setupRequestState());
 
         if (this.rendered) {
             this.#response.end();
@@ -98,7 +123,7 @@ class VidaServerController {
         const responseBody = await this.#performAction(action);
 
         if (!this.rendered) {
-            await this.render(responseBody || {});
+            await APM.startSegment('render', true, () => this.render(responseBody || {}));
         }
 
         this.#response.end();
@@ -106,13 +131,14 @@ class VidaServerController {
 
 
     async #performAction(action) {
-        if (await this.runBeforeCallbacks(action) === false) return false;
+        if (await APM.startSegment('beforeCallbacks', true, () => this.runBeforeCallbacks(action)) === false) return false;
 
         const parameters = this.constructor.parametersForAction(action);
-        if (parameters) await this.validateParameters(parameters);
+        if (parameters) await APM.startSegment('validateParameters', true, () => this.validateParameters(parameters));
 
-        const responseBody = await this[action]();
-        if (await this.runAfterCallbacks(action) === false)  return false;
+        const responseBody = await APM.startSegment(`action:${action}`, true, () => this[action]());
+
+        if (await APM.startSegment('afterCallbacks', true, () => this.runAfterCallbacks(action)) === false) return false;
 
         return responseBody;
     }
@@ -140,14 +166,24 @@ class VidaServerController {
                 message = err.message;
             }
             await this.renderServerError(message);
+
+            this.reportError(err);
         }
     }
 
 
+    reportError(err) {
+        APM.reportError(err);
+    }
+
+
     /***********************************************************************************************
     * RESPONSE RENDERING
     ***********************************************************************************************/
     async render(body, options={}) {
+        if (this.rendered) return;
+        if (this.#isStreaming) return;
+
         if (typeof body == 'string') {
             this._response.send(body);
         } else {
@@ -159,7 +195,7 @@ class VidaServerController {
             body = this.formatJSONBody(body, errors, options);
             this._response.json(body);
         }
-        this.#rendered = true;
+        this.markRendered();
     }
 
 
@@ -196,27 +232,29 @@ class VidaServerController {
         if (body === undefined)               return null;
         if (!body || typeof body != 'object') return body;
 
-        body = structuredClone(body);
+        let processedBody;
 
         if (body.toApiResponse) {
             const formattedBody = await body.toApiResponse(options);
             return await this.processJSONBody(formattedBody, options);
 
         } else if (Array.isArray(body)) {
+            const processed = [];
             for (const idx in body) {
-                body[idx] = await this.processJSONBody(body[idx], options);
+                processed.push(await this.processJSONBody(body[idx], options));
             }
+            return processed;
 
         } else if (body.constructor == Date) {
             return body.getTime();
 
         } else {
+            const processed = {};
             for (let [key, val] of Object.entries(body)) {
-                body[key] = await this.processJSONBody(val, options);
+                processed[key] = await this.processJSONBody(val, options);
             }
+            return processed;
         }
-
-        return body;
     }
 
 
@@ -324,10 +362,82 @@ class VidaServerController {
     }
 
 
+    setHeader(header, value) {
+        this.#response.setHeader(header, value);
+    }
+
+
+    flushHeaders() {
+      this.#response.flushHeaders();
+    }
+
+
+    get rendered()      { return this.#rendered; }
+    markRendered()      { this.#rendered = true; }
+    get writableEnded() { return this.#response.writableEnded; }
+
+
+    /***********************************************************************************************
+    * STREAM
+    ***********************************************************************************************/
+    async streamSseResponse(handler, errorHandler, abortController=null) {
+        if (this.#isStreaming) throw new StreamInProgressError();
+        this.#isStreaming = true;
+
+        let closeHandler;
+        if (abortController) {
+            this.#streamAbortController = abortController;
+            closeHandler = () => abortController.abort();
+            this.#request.on('close', closeHandler);
+        }
+
+        this.#setSseHeaders();
+        this.markRendered();
+        try {
+            await handler.bind(this)();
+        } catch(err) {
+          await errorHandler(err);
+          throw err;
+        } finally {
+            this.writeStreamEvent(null, '[DONE]');
+            this.#response.end();
+
+            this.#isStreaming           = false;
+            this.#streamAbortController = null;
+
+            if (closeHandler) this.#request.off('close', closeHandler);
+        }
+    }
+
+
+    #setSseHeaders() {
+        this.statusCode = 200;
+        this.setHeader('Content-Type',      'text/event-stream; charset=utf-8');
+        this.setHeader('Cache-Control',     'no-cache');
+        this.setHeader('Connection',        'keep-alive');
+        this.setHeader('X-Accel-Buffering', 'no');
+        this.flushHeaders();
+    }
+
+
+    writeStreamEvent(evt, data) {
+        if (!this.#isStreaming) throw new NoActiveStreamError();
+        if (this.#streamAbortController?.signal?.aborted || this.writableEnded) return;
+
+        if (evt) {
+            this.#response.write(`event: ${evt}\n`);
+        }
+
+        const msg = `data: ${data}\n\n`;
+        this.#response.write(msg);
+    }
+
+
     /***********************************************************************************************
     * HELPERS
     ***********************************************************************************************/
     static autoLoadHelpers() {
+        this.actions; // make sure that actions are cached before loading helpers
         const { StaticMethods, InstanceMethods, Accessors } = this._autoLoadModule(this.autoLoadHelperPath);
 
         if (StaticMethods)   Object.assign(this, StaticMethods);
@@ -360,12 +470,12 @@ class VidaServerController {
 
 
     static get autoLoadHelperPath() {
-        return `${process.cwd()}/lib/controllers${this.routePrefix}Controller.js`;
+        return `${process.cwd()}/lib/controllers${this.routePrefix}Controller`;
     }
 
 
     static get autoLoadDocumentationPath() {
-        return `${process.cwd()}/lib/controllers/_docs${this.routePrefix}Controller.js`;
+        return `${process.cwd()}/lib/controllers/_docs${this.routePrefix}Controller`;
     }
 
 
@@ -456,6 +566,44 @@ class VidaServerController {
     }
 
 
+    /***********************************************************************************************
+    * REQUEST PARAMETERS
+    ***********************************************************************************************/
+    hasParam(name) {
+        return Object.prototype.hasOwnProperty.call(this.params, name);
+    }
+
+
+    coerceBoolean(value, { fallback } = {}) {
+        if (typeof value === 'boolean') return value;
+        if (typeof value !== 'string')  return fallback;
+        const normalized = value.trim().toLowerCase();
+        if (!normalized) return fallback;
+        if (normalized === 'true'  || normalized === '1' || normalized === 'yes' || normalized === 'on')  return true;
+        if (normalized === 'false' || normalized === '0' || normalized === 'no'  || normalized === 'off') return false;
+        return fallback;
+    }
+
+
+    coerceInteger(value, { min, max, fallback, nonNegative } = {}) {
+        if (value === null || value === undefined) return fallback;
+        if (typeof value === 'string' && value.trim() === '') return fallback;
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed)) return fallback;
+        let next = Math.floor(parsed);
+        if (nonNegative && next < 0) return fallback;
+        if (Number.isFinite(min)) next = Math.max(min, next);
+        if (Number.isFinite(max)) next = Math.min(max, next);
+        return next;
+    }
+
+
+    coerceObject(value, { fallback = {} } = {}) {
+        if (value && typeof value === 'object' && !Array.isArray(value)) return value;
+        return fallback;
+    }
+
+
     /***********************************************************************************************
     * VALIDATIONS
     ***********************************************************************************************/
@@ -531,6 +679,12 @@ class VidaServerController {
     }
 
 
+    validateIsBoolean(value, bool) {
+      if (typeof value == 'boolean' && value === bool) return;
+      return `must be ${bool}`;
+    }
+
+
     async validateFunction(value, fnc) {
         const error = await fnc.call(this, value);
         if (error) return error;
@@ -551,10 +705,14 @@ class VidaServerController {
     * {getFooBar: '/ban/:accountIdd/foo/:userId/bar'}`
     ***********************************************************************************************/
     static get actions() {
+        if (actionStore.has(this)) return actionStore.get(this);
         const actionNames = this.actionNames;
-        return actionNames.map((actionName => {
+        const actions = actionNames.map((actionName => {
             return this._constructAction(actionName);
         }).bind(this));
+
+        actionStore.set(this, actions);
+        return actions;
     }
 
 
@@ -670,15 +828,49 @@ class VidaServerController {
     static authenticationDocumentation(actionName) {
         return {apiKeyAuth: []};
     }
+
+
+    /***********************************************************************************************
+    * SECURITY
+    ***********************************************************************************************/
+    secureCompare(a, b) {
+        const aBuf = Buffer.from(a || '', 'utf8');
+        const bBuf = Buffer.from(b || '', 'utf8');
+        if (aBuf.length !== bBuf.length) return false;
+        return crypto.timingSafeEqual(aBuf, bBuf);
+    }
+
+
+    /***********************************************************************************************
+    * APM
+    ***********************************************************************************************/
+    addApmAttribute(key, value) {
+        APM.addCustomAttribute(key, value)
+    }
+
+
+    setApmUserId(id) {
+        APM.setUserId(id)
+    }
+
+
+    startApmSegment(name, record, handler) {
+        return APM.startSegment(name, record, handler);
+    }
 }
 
 
+class StreamInProgressError extends Error {}
+class NoActiveStreamError   extends Error {}
+
 const errorClasses = Object.values(Errors).filter(cls => cls == Errors.ServerError || cls.prototype instanceof Errors.AbstractServerError);
 VidaServerController.prototype.Errors = Object.fromEntries(errorClasses.map(cls => {
     return [cls.name.replace('Error', ''), cls]
 }));
 
 
-module.exports = { 
+module.exports = {
+    NoActiveStreamError,
+    StreamInProgressError,
     VidaServerController
 };

package/lib/utils/abstractAutoImporter.js

@@ -0,0 +1,64 @@
+const fs = require('fs');
+
+
+class AbstractAutoImporter {
+    #directories;
+    #imports;
+
+
+    constructor(directories) {
+        if (!Array.isArray(directories)) {
+            directories = [directories];
+        }
+        this.#directories = directories;
+    }
+
+
+    get imports() {
+        if (!this.#imports) {
+            this.#runImport();
+        }
+        return this.#imports;
+    }
+
+
+    #runImport() {
+        this.#imports = [];
+        this.#directories.forEach(dir => {
+            this.#importDirectory(dir, dir);
+        });
+    }
+
+
+    #importDirectory(dir, topLevelDirectory) {
+        fs.readdirSync(dir).forEach((f => {
+            const filePath = `${dir}/${f}`;
+            if (fs.lstatSync(filePath).isDirectory()) {
+                this.#importDirectory(filePath, topLevelDirectory);
+            } else if (f.endsWith('.js')) {
+                this.#importFromFile(filePath, dir, topLevelDirectory);
+            }
+        }).bind(this));
+    }
+
+
+    #importFromFile(filePath, dir, topLevelDirectory) {
+        const exports = Object.values(require(filePath));
+        exports.forEach(obj => {
+            if (this.shouldImport(obj)) {
+                const directoryPrefix = dir.replace(topLevelDirectory, '');
+                this.processImport(obj, directoryPrefix);
+                this.#imports.push(obj);
+            }
+        });
+    }
+
+
+    shouldImport(obj)  {}
+    processImport(obj) {}
+}
+
+
+module.exports = {
+    AbstractAutoImporter
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vida-global/core",
-    "version": "1.4.5",
+    "version": "2.0.0",
     "description": "Core libraries for supporting Vida development",
     "author": "",
     "license": "ISC",
@@ -18,19 +18,21 @@
         "setupFilesAfterEnv": ["jest-extended/all"]
     },
     "dependencies": {
+        "bullmq": "^5.0.0",
         "commander": "^13.1.0",
         "express": "^4.21.2",
+        "express-request-id": "1.4.1",
+        "express-winston": "^4.0.0",
         "mustache-express": "^1.2.8",
+        "newrelic": "^13.0.0",
         "pg": "^8.16.3",
-        "pino": "^9.6.0",
-        "pino-http": "^10.4.0",
-        "pino-pretty": "^13.0.0",
-        "redis": "^5.0.0",
+        "redis": "^4.0.0",
         "response-time": "^2.3.3",
         "sequelize": "^6.37.7",
         "sequelize-cli": "^6.6.3",
         "socket.io": "^4.4.0",
-        "@vida-global/release": "^1.0.0"
+        "@vida-global/release": "^1.0.0",
+        "winston": "^3.0.0"
     },
     "devDependencies": {
         "jest": "^29.0.0",

package/test/activeRecord/baseRecord.test.js

@@ -126,6 +126,135 @@ describe('BaseRecord', () => {
     });
 
 
+    describe('BaseRecord.configureVirtualAccessors', () => {
+        it ('adds a VIRTUAL column when a _virtualGet method is defined on the subclass', () => {
+            const getter = jest.fn();
+            class User extends BaseRecord {}
+            User.prototype._virtualGetFullName = getter;
+            User.initialize();
+
+            expect(Model.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    fullName: { type: Sequelize.DataTypes.VIRTUAL, get: getter }
+                }),
+                expect.anything()
+            );
+        });
+
+        it ('adds a VIRTUAL column when a _virtualSet method is defined on the subclass', () => {
+            const setter = jest.fn();
+            class User extends BaseRecord {}
+            User.prototype._virtualSetFullName = setter;
+            User.initialize();
+
+            expect(Model.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    fullName: { type: Sequelize.DataTypes.VIRTUAL, set: setter }
+                }),
+                expect.anything()
+            );
+        });
+
+        it ('merges _virtualGet and _virtualSet into the same VIRTUAL column', () => {
+            const getter = jest.fn();
+            const setter = jest.fn();
+            class User extends BaseRecord {}
+            User.prototype._virtualGetFullName = getter;
+            User.prototype._virtualSetFullName = setter;
+            User.initialize();
+
+            expect(Model.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    fullName: { type: Sequelize.DataTypes.VIRTUAL, get: getter, set: setter }
+                }),
+                expect.anything()
+            );
+        });
+
+        it ('picks up virtual accessors defined on a parent class', () => {
+            const getter = jest.fn();
+            class Person extends BaseRecord {}
+            Person.prototype._virtualGetDisplayName = getter;
+            class Employee extends Person {}
+            Employee.initialize();
+
+            expect(Model.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    displayName: { type: Sequelize.DataTypes.VIRTUAL, get: getter }
+                }),
+                expect.anything()
+            );
+        });
+
+        it ('lets a subclass override a virtual accessor defined on a parent class', () => {
+            const parentGetter = jest.fn();
+            const childGetter  = jest.fn();
+            class Person extends BaseRecord {}
+            Person.prototype._virtualGetDisplayName = parentGetter;
+            class Employee extends Person {}
+            Employee.prototype._virtualGetDisplayName = childGetter;
+            Employee.initialize();
+
+            expect(Model.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    displayName: { type: Sequelize.DataTypes.VIRTUAL, get: childGetter }
+                }),
+                expect.anything()
+            );
+        });
+
+        it ('merges a parent _virtualGet with a child _virtualSet on the same property', () => {
+            const parentGetter = jest.fn();
+            const childSetter  = jest.fn();
+            class Person extends BaseRecord {}
+            Person.prototype._virtualGetDisplayName = parentGetter;
+            class Employee extends Person {}
+            Employee.prototype._virtualSetDisplayName = childSetter;
+            Employee.initialize();
+
+            expect(Model.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    displayName: { type: Sequelize.DataTypes.VIRTUAL, get: parentGetter, set: childSetter }
+                }),
+                expect.anything()
+            );
+        });
+
+        it ('does not pull in non-virtual methods from any ancestor', () => {
+            class Person extends BaseRecord {
+                someOtherMethod() {}
+            }
+            class Employee extends Person {}
+            Employee.initialize();
+
+            const [schemaArg] = Model.init.mock.calls[0];
+            expect(schemaArg).not.toHaveProperty('someOtherMethod');
+        });
+
+        it ('does not walk past Model.prototype when collecting accessors', () => {
+            class User extends BaseRecord {}
+            Model.prototype._virtualGetShouldBeIgnored = jest.fn();
+            User.initialize();
+
+            const [schemaArg] = Model.init.mock.calls[0];
+            expect(schemaArg).not.toHaveProperty('shouldBeIgnored');
+
+            delete Model.prototype._virtualGetShouldBeIgnored;
+        });
+
+        it ('leaves existing schema columns untouched while adding the virtual entry', () => {
+            const getter = jest.fn();
+            class User extends BaseRecord {}
+            User.prototype._virtualGetFullName = getter;
+            User.initialize();
+
+            const [schemaArg] = Model.init.mock.calls[0];
+            expect(schemaArg[Helpers.colName]).toEqual({ type: Sequelize.DataTypes[Helpers.dataTypeKey2] });
+            expect(schemaArg.fullName).toEqual({ type: Sequelize.DataTypes.VIRTUAL, get: getter });
+        });
+    });
+
+
     describe('BaseRecord.tableName', () => {
         it ('defaults to the puralized version of the class name', () => {
             class User extends BaseRecord {}

package/test/activeRecord/db/connection.test.js

@@ -1,9 +1,11 @@
 const { Connection }              = require('../../../lib/activeRecord/db/connection');
 const { ConnectionConfiguration } = require('../../../lib/activeRecord/db/connectionConfiguration');
 const   Helpers                   = require('../helpers/connection');
+const { snapshotEnv }             = require('../../helpers/env');
 
 
 let fetchConfigsSpy;
+let restoreEnv;
 
 jest.mock('sequelize', () => {
     const { MockSequelize } = require('../helpers/fixtures');
@@ -11,6 +13,7 @@ jest.mock('sequelize', () => {
 });
 
 beforeEach(() => {
+    restoreEnv = snapshotEnv(['NODE_ENV']);
     fetchConfigsSpy = jest.spyOn(ConnectionConfiguration, '_fetchAllConfigs');
     fetchConfigsSpy.mockImplementation(Helpers.buildConfigs);
 });
@@ -18,7 +21,7 @@ beforeEach(() => {
 afterEach(() => {
     fetchConfigsSpy.mockRestore();
     Connection.clearConnectionsCache();
-    process.env.NODE_ENV = Helpers.originalNodeEnv;
+    restoreEnv();
 });
 
 

package/test/activeRecord/db/connectionConfiguration.test.js

@@ -1,12 +1,18 @@
 const { ConnectionConfiguration } = require('../../../lib/activeRecord/db/connectionConfiguration');
 const   Helpers                   = require('../helpers/connectionConfiguration');
+const { snapshotEnv }             = require('../../helpers/env');
+
+
+let restoreEnv;
+
+beforeEach(() => {
+    restoreEnv = snapshotEnv(['DB_POOL_MIN', 'DB_POOL_MAX', 'NODE_ENV']);
+});
 
 
 afterEach(() => {
     Helpers.fetchConfigsSpy.mockReset();
-    process.env.DB_POOL_MIN = Helpers.originalEnv.dbPoolMin;
-    process.env.DB_POOL_MAX = Helpers.originalEnv.dbPoolMax;
-    process.env.NODE_ENV    = Helpers.originalEnv.nodeEnv;
+    restoreEnv();
 });