@vida-global/core 1.4.4 → 1.4.6

package/lib/server/serverController.js

@@ -1,6 +1,7 @@
 const { logger }                 = require('../logger');
 const { camelize, singularize }  = require('inflection');
 const   Errors                   = require('./errors');
+const   nodeUtil                 = require('util');
 
 
 const AUTH_CALLBACK_NAME = 'authenticateRequest';
@@ -12,10 +13,13 @@ class VidaServerController {
     #beforeCallbacks       = [];
     #beforeCallbacksToSkip = [];
     #callbacksSetUp        = false;
+    #isStreaming           = false;
+    #logger;
     #params;
     #rendered              = false;
     #request;
     #response;
+    #streamAbortController;
 
 
     constructor(request, response) {
@@ -41,16 +45,36 @@ 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 statusCode()        { return this._response.statusCode; }
+    set statusCode(_status) { this._response.statusCode = _status; }
+
+
+    get logger() { 
+      if (!this.#logger) {
+          this.#logger = logger.http.createChild(this.requestId);
+      }
+      return this.#logger;
+    }
+
+
+    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) {
@@ -148,6 +172,9 @@ class VidaServerController {
     * 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 +186,7 @@ class VidaServerController {
             body = this.formatJSONBody(body, errors, options);
             this._response.json(body);
         }
-        this.#rendered = true;
+        this.markRendered();
     }
 
 
@@ -196,6 +223,8 @@ class VidaServerController {
         if (body === undefined)               return null;
         if (!body || typeof body != 'object') return body;
 
+        if (nodeUtil.types.isProxy(body)) body = {...body};
+
         body = structuredClone(body);
 
         if (body.toApiResponse) {
@@ -324,6 +353,77 @@ 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
     ***********************************************************************************************/
@@ -531,6 +631,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;
@@ -670,15 +776,31 @@ 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);
+    }
 }
 
 
+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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vida-global/core",
-    "version": "1.4.4",
+    "version": "1.4.6",
     "description": "Core libraries for supporting Vida development",
     "author": "",
     "license": "ISC",
@@ -20,17 +20,17 @@
     "dependencies": {
         "commander": "^13.1.0",
         "express": "^4.21.2",
+        "express-request-id": "1.4.1",
+        "express-winston": "^4.0.0",
         "mustache-express": "^1.2.8",
         "pg": "^8.16.3",
-        "pino": "^9.6.0",
-        "pino-http": "^10.4.0",
-        "pino-pretty": "^13.0.0",
         "redis": "^5.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/db/schema.test.js

@@ -0,0 +1,217 @@
+jest.mock('../../../lib/activeRecord/db/importSchema', () => jest.fn());
+
+jest.mock('../../../lib/activeRecord/db/connection', () => {
+    const clearConnectionsCache = jest.fn();
+    const allTables             = jest.fn();
+    function Connection() {
+        this.queryInterface = { allTables };
+    }
+    Connection.clearConnectionsCache = clearConnectionsCache;
+    Connection.__allTables           = allTables;
+    return { Connection };
+});
+
+jest.mock('../../../lib/activeRecord/db/connectionConfiguration', () => ({
+    ConnectionConfiguration: { configuredDatabaseIds: jest.fn() }
+}));
+
+jest.mock('../../../lib/activeRecord/utils', () => {
+    const actual = jest.requireActual('../../../lib/activeRecord/utils');
+    return { ...actual, ensureSchemasDirectory: jest.fn() };
+});
+
+const   fs                                                   = require('node:fs');
+const   importSchema                                         = require('../../../lib/activeRecord/db/importSchema');
+const { Connection }                                         = require('../../../lib/activeRecord/db/connection');
+const { ConnectionConfiguration }                            = require('../../../lib/activeRecord/db/connectionConfiguration');
+const   utils                                                = require('../../../lib/activeRecord/utils');
+const { generateActiveRecordSchemaFiles, getActiveRecordSchema } = require('../../../lib/activeRecord/db/schema');
+const { Sequelize }                                          = require('sequelize');
+
+afterEach(() => {
+    jest.clearAllMocks();
+});
+
+
+describe('activeRecord/db/schema', () => {
+    describe('.getActiveRecordSchema', () => {
+        it ('throws when no schema is found for the table', () => {
+            importSchema.mockImplementation(() => undefined);
+            expect(() => getActiveRecordSchema('users', 'main', 'postgres'))
+                .toThrow('No schema found for table main.users');
+        });
+
+
+        describe('type mapping (cleanSchema → dataTypeForColumn)', () => {
+            it ('maps INTEGER columns to Sequelize.DataTypes.INTEGER', () => {
+                importSchema.mockImplementation(() => ({
+                    id: { type: 'INTEGER', primaryKey: true }
+                }));
+                const schema = getActiveRecordSchema('t', 'main', 'postgres');
+                expect(schema.id.type).toBe(Sequelize.DataTypes.INTEGER);
+            });
+
+            it ('maps BOOLEAN columns to Sequelize.DataTypes.BOOLEAN', () => {
+                importSchema.mockImplementation(() => ({
+                    flag: { type: 'BOOLEAN' }
+                }));
+                const schema = getActiveRecordSchema('t', 'main', 'postgres');
+                expect(schema.flag.type).toBe(Sequelize.DataTypes.BOOLEAN);
+            });
+
+            it ('strips parameterized type modifiers before lookup', () => {
+                importSchema.mockImplementation(() => ({
+                    name: { type: 'INTEGER(10)' }
+                }));
+                const schema = getActiveRecordSchema('t', 'main', 'postgres');
+                expect(schema.name.type).toBe(Sequelize.DataTypes.INTEGER);
+            });
+
+            it ('falls back to STRING when type contains CHAR but is not otherwise matched', () => {
+                importSchema.mockImplementation(() => ({
+                    code: { type: 'NCHARFOO' }
+                }));
+                const schema = getActiveRecordSchema('t', 'main', 'postgres');
+                expect(schema.code.type).toBe(Sequelize.DataTypes.STRING);
+            });
+
+            it ('leaves the original type when no match is found', () => {
+                importSchema.mockImplementation(() => ({
+                    weird: { type: 'COMPLETELY_UNKNOWN_TYPE' }
+                }));
+                const schema = getActiveRecordSchema('t', 'main', 'postgres');
+                expect(schema.weird.type).toBe('COMPLETELY_UNKNOWN_TYPE');
+            });
+        });
+
+
+        describe('autoIncrement resolution', () => {
+            it ('sets autoIncrement and removes defaultValue + allowNull when default is a PG sequence', () => {
+                importSchema.mockImplementation(() => ({
+                    id: {
+                        type:         'INTEGER',
+                        primaryKey:   true,
+                        defaultValue: 'nextval(users_id_seq::regclass)',
+                        allowNull:    false
+                    }
+                }));
+                const schema = getActiveRecordSchema('t', 'main', 'postgres');
+                expect(schema.id.autoIncrement).toBe(true);
+                expect(schema.id).not.toHaveProperty('defaultValue');
+                expect(schema.id).not.toHaveProperty('allowNull');
+            });
+
+            it ('does not modify columns whose defaultValue is not a sequence', () => {
+                importSchema.mockImplementation(() => ({
+                    name: {
+                        type:         'INTEGER',
+                        defaultValue: 'literal',
+                        allowNull:    true
+                    }
+                }));
+                const schema = getActiveRecordSchema('t', 'main', 'postgres');
+                expect(schema.name.autoIncrement).toBeUndefined();
+                expect(schema.name.defaultValue).toBe('literal');
+                expect(schema.name.allowNull).toBe(true);
+            });
+
+            it ('does nothing when there is no defaultValue', () => {
+                importSchema.mockImplementation(() => ({
+                    name: { type: 'INTEGER' }
+                }));
+                const schema = getActiveRecordSchema('t', 'main', 'postgres');
+                expect(schema.name.autoIncrement).toBeUndefined();
+            });
+        });
+
+
+        describe('UUID resolution', () => {
+            it ('sets UUIDV4 default on UUID primary keys whose type stays as the string "UUID"', () => {
+                importSchema.mockImplementation(() => ({
+                    id: { type: 'UUID', primaryKey: true }
+                }));
+                const schema = getActiveRecordSchema('t', 'main', 'postgres');
+                // Whether dataTypeForColumn rewrote the type or not, behavior is observable:
+                // if it stayed as 'UUID', resolveUUIDColumns sets the default.
+                if (schema.id.type === 'UUID') {
+                    expect(schema.id.defaultValue).toBe(Sequelize.UUIDV4);
+                }
+            });
+
+            it ('does not set a UUIDV4 default on UUID columns that are not primary keys', () => {
+                importSchema.mockImplementation(() => ({
+                    ref: { type: 'UUID' }
+                }));
+                const schema = getActiveRecordSchema('t', 'main', 'postgres');
+                expect(schema.ref.defaultValue).toBeUndefined();
+            });
+
+            it ('does not set a UUIDV4 default on non-UUID primary keys', () => {
+                importSchema.mockImplementation(() => ({
+                    id: { type: 'INTEGER', primaryKey: true }
+                }));
+                const schema = getActiveRecordSchema('t', 'main', 'postgres');
+                expect(schema.id.defaultValue).toBeUndefined();
+            });
+        });
+    });
+
+
+    describe('.generateActiveRecordSchemaFiles', () => {
+        let writeFileSpy;
+
+        beforeEach(() => {
+            writeFileSpy = jest.spyOn(fs, 'writeFile').mockImplementation((p, c, cb) => cb && cb(null));
+        });
+
+        afterEach(() => {
+            writeFileSpy.mockRestore();
+        });
+
+        it ('ensures the schemas directory exists before writing', async () => {
+            ConnectionConfiguration.configuredDatabaseIds.mockReturnValue([]);
+            await generateActiveRecordSchemaFiles();
+            expect(utils.ensureSchemasDirectory).toHaveBeenCalledTimes(1);
+        });
+
+        it ('writes one schema file per configured database id', async () => {
+            ConnectionConfiguration.configuredDatabaseIds.mockReturnValue(['main', 'analytics']);
+            Connection.__allTables.mockResolvedValue({ users: { id: { type: 'INTEGER' } } });
+
+            await generateActiveRecordSchemaFiles();
+            expect(Connection.clearConnectionsCache).toHaveBeenCalledTimes(2);
+            expect(writeFileSpy).toHaveBeenCalledTimes(2);
+
+            const writtenPaths = writeFileSpy.mock.calls.map(c => c[0]);
+            expect(writtenPaths[0]).toEqual(`${utils.schemasDirectory}/main.js`);
+            expect(writtenPaths[1]).toEqual(`${utils.schemasDirectory}/analytics.js`);
+
+            const writtenBody = writeFileSpy.mock.calls[0][1];
+            expect(writtenBody).toContain('module.exports = ');
+            expect(writtenBody).toContain('"users"');
+        });
+
+        it ('logs an error when fs.writeFile fails (does not reject)', async () => {
+            const { logger } = require('../../../lib/logger');
+            const errSpy     = jest.spyOn(logger, 'error').mockImplementation(() => {});
+            ConnectionConfiguration.configuredDatabaseIds.mockReturnValue(['main']);
+            Connection.__allTables.mockResolvedValue({});
+            writeFileSpy.mockImplementation((p, c, cb) => cb(new Error('disk full')));
+
+            await generateActiveRecordSchemaFiles();
+            expect(errSpy).toHaveBeenCalledWith(expect.stringContaining('Unable to write new schema file'));
+            errSpy.mockRestore();
+        });
+
+        it ('logs success when fs.writeFile succeeds', async () => {
+            const { logger } = require('../../../lib/logger');
+            const infoSpy    = jest.spyOn(logger, 'info').mockImplementation(() => {});
+            ConnectionConfiguration.configuredDatabaseIds.mockReturnValue(['main']);
+            Connection.__allTables.mockResolvedValue({});
+
+            await generateActiveRecordSchemaFiles();
+            expect(infoSpy).toHaveBeenCalledWith(expect.stringContaining('New schemas file written'));
+            infoSpy.mockRestore();
+        });
+    });
+});

package/test/activeRecord/utils.test.js

@@ -0,0 +1,72 @@
+const fs    = require('node:fs');
+const utils = require('../../lib/activeRecord/utils');
+
+
+describe('activeRecord/utils', () => {
+    describe('.toCamelCase', () => {
+        it ('converts kebab-case to camelCase', () => {
+            expect(utils.toCamelCase('foo-bar-baz')).toEqual('fooBarBaz');
+        });
+
+        it ('converts snake_case to camelCase', () => {
+            expect(utils.toCamelCase('foo_bar_baz')).toEqual('fooBarBaz');
+        });
+
+        it ('converts space-separated words to camelCase', () => {
+            expect(utils.toCamelCase('foo bar baz')).toEqual('fooBarBaz');
+        });
+
+        it ('handles mixed separators', () => {
+            expect(utils.toCamelCase('foo-bar_baz qux')).toEqual('fooBarBazQux');
+        });
+
+        it ('lowercases the first token even when capitalized', () => {
+            expect(utils.toCamelCase('Foo-Bar')).toEqual('fooBar');
+        });
+
+        it ('returns a single token lowercased', () => {
+            expect(utils.toCamelCase('FOO')).toEqual('foo');
+        });
+
+        it ('returns an empty string when given an empty string', () => {
+            expect(utils.toCamelCase('')).toEqual('');
+        });
+    });
+
+
+    describe('directory ensurers', () => {
+        let mkdirSpy;
+
+        beforeEach(() => {
+            mkdirSpy = jest.spyOn(fs, 'mkdirSync').mockImplementation(() => undefined);
+        });
+
+        afterEach(() => {
+            mkdirSpy.mockRestore();
+        });
+
+        describe('.ensureConfigDirectory', () => {
+            it ('creates the config directory recursively', () => {
+                utils.ensureConfigDirectory();
+                expect(mkdirSpy).toHaveBeenCalledTimes(1);
+                expect(mkdirSpy).toHaveBeenCalledWith(utils.configDirectory, { recursive: true });
+            });
+        });
+
+        describe('.ensureMigrationsDirectory', () => {
+            it ('creates the migrations directory recursively', () => {
+                utils.ensureMigrationsDirectory();
+                expect(mkdirSpy).toHaveBeenCalledTimes(1);
+                expect(mkdirSpy).toHaveBeenCalledWith(utils.migrationsDirectory, { recursive: true });
+            });
+        });
+
+        describe('.ensureSchemasDirectory', () => {
+            it ('creates the schemas directory recursively', () => {
+                utils.ensureSchemasDirectory();
+                expect(mkdirSpy).toHaveBeenCalledTimes(1);
+                expect(mkdirSpy).toHaveBeenCalledWith(utils.schemasDirectory, { recursive: true });
+            });
+        });
+    });
+});

package/test/http/client.test.js

@@ -1,6 +1,6 @@
-const { HttpClient } = require('../../lib/http/client');
-const { logger }     = require('../../lib/logger');
-const   Helpers      = require('./helpers/client');
+const { HttpClient, HttpAbortError } = require('../../lib/http/client');
+const { logger }                     = require('../../lib/logger');
+const   Helpers                      = require('./helpers/client');
 
 
 afterEach(() => {
@@ -90,4 +90,73 @@ describe('HttpClient', () => {
             });
         }
     });
+
+
+    describe('abort/timeout support', () => {
+        const client = new HttpClient();
+
+
+        it('passes a signal when timeout is provided', async () => {
+            await client.post(Helpers.apiUrl, { timeout: 5000 });
+
+            const callOpts = fetch.mock.calls[0][1];
+            expect(callOpts.signal).toBeInstanceOf(AbortSignal);
+        });
+
+
+        it('passes a signal when an external signal is provided', async () => {
+            const externalSignal = new AbortController().signal;
+
+            await client.post(Helpers.apiUrl, { signal: externalSignal });
+
+            const callOpts = fetch.mock.calls[0][1];
+            expect(callOpts.signal).toBe(externalSignal);
+        });
+
+
+        it('composes external signal with timeout', async () => {
+            const externalSignal = new AbortController().signal;
+
+            await client.post(Helpers.apiUrl, { signal: externalSignal, timeout: 5000 });
+
+            const callOpts = fetch.mock.calls[0][1];
+            expect(callOpts.signal).toBeInstanceOf(AbortSignal);
+            expect(callOpts.signal).not.toBe(externalSignal);
+        });
+
+
+        it('omits signal when neither timeout nor signal is provided', async () => {
+            await client.post(Helpers.apiUrl);
+
+            const callOpts = fetch.mock.calls[0][1];
+            expect(callOpts.signal).toBeUndefined();
+        });
+
+
+        it('throws HttpAbortError with reason "timed out" when fetch rejects with AbortError under a timeout', async () => {
+            global.fetch = jest.fn().mockRejectedValue(new DOMException('aborted', 'AbortError'));
+
+            await expect(client.post(Helpers.apiUrl, { timeout: 1 }))
+                .rejects.toBeInstanceOf(HttpAbortError);
+            await expect(client.post(Helpers.apiUrl, { timeout: 1 }))
+                .rejects.toMatchObject({ reason: 'timed out' });
+        });
+
+
+        it('throws HttpAbortError with reason "aborted" when caller-supplied signal aborts the fetch', async () => {
+            global.fetch = jest.fn().mockRejectedValue(new DOMException('aborted', 'AbortError'));
+            const externalSignal = new AbortController().signal;
+
+            await expect(client.post(Helpers.apiUrl, { signal: externalSignal }))
+                .rejects.toMatchObject({ reason: 'aborted' });
+        });
+
+
+        it('rethrows non-abort fetch errors unchanged', async () => {
+            const networkErr = new Error('connect ECONNREFUSED');
+            global.fetch = jest.fn().mockRejectedValue(networkErr);
+
+            await expect(client.post(Helpers.apiUrl)).rejects.toBe(networkErr);
+        });
+    });
 });