@vida-global/core 1.4.5 → 1.4.6

package/AGENTS.md

@@ -0,0 +1,13 @@
+# vida-core Guide
+
+Use this guide to understand and write code for the vida-core repo.
+
+# Style and conventions
+@agents/style.md
+@agents/server.md
+@agents/db.md
+@agents/apis.md
+@agents/testing.md
+
+
+# Helpers for common use cases

package/lib/logger/README.md

@@ -1,2 +1,33 @@
-## Logger ##
-A standard logger to be used across all Vida applications. Currently, a simple implementation of `pino`, supports the full `pino` API.
+# Logger
+A simple logger that support multiple scopes and log levels. Set the `LOG_LEVEL` environment variable to determine what log levels are output.
+
+## Scopes
+```
+logger.addScope('foo');
+logger.addScope('bar');
+
+logger.foo.debug('my log');
+// [2026-04-30 16:16:12.797 -0700][DEBUG][FOO] my log
+
+logger.bar.verbose('my log');
+// [2026-04-30 16:16:12.797 -0700][VERBOSE][BAR] my log
+
+logger.bar.info('my log');
+// [2026-04-30 16:16:12.797 -0700][INFO][BAR] my log
+
+logger.bar.warn('my log');
+// [2026-04-30 16:16:12.797 -0700][WARN][BAR] my log
+
+logger.bar.error('my log');
+// [2026-04-30 16:16:12.797 -0700][ERROR][BAR] my log
+```
+
+## IDs
+```
+logger.addScope('http');
+const requestId     = 123;
+const requestLogger = logger.http.createChild(requestId);
+
+requestLogger.debug('my log');
+// [2026-04-30 16:16:12.797 -0700][DEBUG][HTTP][123] my log
+``

package/lib/logger/index.js

@@ -1,25 +1,104 @@
-const pino = require('pino');
-
-const config = {
-    level: process.env.LOG_LEVEL || 'info',
-    customLevels: {
-      test: 1000
-    }
-};
-
-if (!process.env.ENV_VERCEL) {
-    config.transport = {
-        target: 'pino-pretty',
-        options: {
-            colorize: true,
-            ignore: 'pid,hostname',
-            translateTime: 'SYS:standard',
-            messageFormat: '{msg}',
+const   winston                           = require('winston');
+const { colorize, combine, printf, timestamp } = winston.format;
+
+
+class Logger {
+    #id;
+    #logger;
+    #scope;
+
+
+    constructor(scope, id) {
+        this.#id     = id;
+        this.#scope  = scope || 'API';
+        this.#logger = winston.createLogger(this.loggerOptions);
+    }
+
+
+    get scope() { return this.#scope; }
+    get id()    { return this.#id; }
+
+
+    get loggerOptions() {
+        const format     = combine(...this.formatters);
+        const level      = this.level;
+        const transports = this.transports;
+
+        return { format, level, transports };
+    }
+
+
+    get formatters() {
+        const colors = {
+            debug:   'magenta',
+            verbose: 'green',
+            info:    'cyan',
+            warn:    'yellow',
+            error:   'red',
+        }
+        const messageFormatter = winston.format(this.messageFormatter.bind(this));
+        return [
+            timestamp({format: 'YYYY-MM-DD HH:mm:ss.SSS ZZ'}),
+            messageFormatter(),
+            colorize({all: true, colors}),
+            printf(({ message }) => message)
+        ];
+    }
+
+
+    messageFormatter(info) {
+        const level  = info.level.toUpperCase()
+
+        let prefix = `[${info.timestamp}][${level}][${this.scope.toUpperCase()}]`;
+        if (this.id) prefix = `${prefix}[${this.id}]`;
+
+        info.message =  `${prefix} ${info.message}`;
+        return info;
+    }
+
+
+    get level() {
+        return process.env.LOG_LEVEL || 'info';
+    }
+
+
+    get transports() {
+        const transports = [ new winston.transports.Console() ];
+        return transports;
+    }
+
+
+    addScope(scope) {
+        const existing = this[scope];
+        if (existing && !existing instanceof Logger) {
+            throw `Property already exists at ${scope}`;
         }
-    };
+
+        const logger = new Logger(scope, this.id);
+        Object.defineProperty(this, scope, { get: () => logger });
+    }
+
+
+    createChild(id) {
+        return new Logger(this.scope, id);
+    }
+
+
+    debug(msg)   { this.#logger.debug(msg) }
+    error(msg)   { this.#logger.error(msg) }
+    info(msg)    { this.#logger.info(msg) }
+    silly(msg)   { this.#logger.silly(msg) }
+    verbose(msg) { this.#logger.verbose(msg) }
+    warn(msg)    { this.#logger.warn(msg) }
+
+    get _winstonLogger() { 
+        this.warn('Directly accessing the underlying winston logger should be avoided unless necessary');
+        return this.#logger
+    }
 }
 
-const logger = pino(config);
+
+const logger = new Logger();
 
 
-module.exports = { logger };
+module.exports = { logger, Logger };

package/lib/logger/serverMiddleware.js

@@ -0,0 +1,39 @@
+const { logger }     = require('./index');
+const expressWinston = require('express-winston');
+
+
+const msgFormatter = (req, res) => {
+    let msg;
+    if (req.controller) {
+        msg = `${req.controller.constructor.name}#${req.action}`;
+    } else {
+        msg = res.statusCode >= 500 ? 'request errored' : 'request completed';
+    }
+
+    const headerPcs       = res._header.split("\n").map(h => h.split(/:(.*)/));
+    const headers         = Object.fromEntries(headerPcs);
+    const responseTime    = headers['X-Response-Time'];
+
+    const requestDetails  = `req: ${req.method} ${req.url.split('?')[0]} for ${req.ip}`;
+    const responseDetails = `res: statusCode=${res.statusCode} responseTime=${responseTime}`;
+
+    msg = `${msg}\n    ${requestDetails}\n    ${responseDetails}`;
+    if (res.error) {
+        msg = `${msg}\n${res.error.stack}`;
+    }
+
+    return msg;
+};
+
+
+logger.addScope('http');
+const middleware = expressWinston.logger({
+    level:           'debug',
+    msg:             msgFormatter,
+    winstonInstance: logger.http._winstonLogger,
+});
+
+
+module.exports = {
+  middleware
+}

package/lib/server/server.js

@@ -1,13 +1,13 @@
 const { ControllerImporter }   = require('./controllerImporter');
 const   express                = require('express');
-const   httpLogger             = require('pino-http')
 const { logger }               = require('../logger');
+const   loggingMiddleware      = require('../logger/serverMiddleware');
 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   requestID              = require( 'express-request-id');
 
 
 class VidaServer {
@@ -31,7 +31,7 @@ class VidaServer {
         await this.registerControllers();
 
         this.#httpServer.listen(this.#port, this.#host, () => {
-            this.logger.info(`Server is running on port ${this.#port}`);
+            logger.info(`Server is running on port ${this.#port}`);
             if (callback) callback();
         });
     }
@@ -39,7 +39,7 @@ class VidaServer {
 
     get host()   { return this.#host; }
     get port()   { return this.#port; }
-    get logger() { return logger; }
+    get logger() { return logger.http; }
 
 
     /***********************************************************************************************
@@ -72,11 +72,12 @@ class VidaServer {
     setupMiddleware() {
         this.use(this.jsonParsingMiddleware);
         this.use(this.octetStreamParsingMiddleware);
-        this.use(responseTime())
+        this.use(responseTime({suffix: true}))
         this.use(express.static('public'))
         this.use(this.loggingMiddleware);
         this.use('/static', express.static(this.staticFilesDirectory));
         this.use(this.connectionAbortedMiddleware);
+        this.use(requestID());
 
         this.#expressServer.engine('html', mustacheExpress());
     }
@@ -105,15 +106,7 @@ class VidaServer {
 
 
     get loggingMiddleware() {
-        return httpLogger({
-            logger:               this.middlewareLogger,
-            customLogLevel:       this.requestLogLevel.bind(this),
-            customSuccessMessage: this.requestLogMessage.bind(this),
-            customErrorMessage:   this.requestLogMessage.bind(this),
-            customErrorObject:    this.requestLogDetails.bind(this),
-            customSuccessObject:  this.requestLogDetails.bind(this),
-            wrapSerializers:      false,
-        })
+      return loggingMiddleware.middleware
     }
 
 
@@ -135,53 +128,6 @@ class VidaServer {
     use() { this.#expressServer.use(...arguments); }
 
 
-    /***********************************************************************************************
-    * LOGGING
-    ***********************************************************************************************/
-    requestLogDetails(req, res, err) {
-        const details = {
-            req: `${req.method} ${req.url}`,
-            res: `statusCode=${res.statusCode}, responseTime=${res.get('X-Response-Time')}`,
-        };
-
-        if (res.statusCode >= 500 && res.error) {
-            details.error = this.requestLogErrorDetails(req, res, res.error);
-        }
-
-        return details;
-    }
-
-
-    requestLogErrorDetails(req, res, err) {
-        if (typeof err == 'string') return {message: err};
-        return {
-            type: err.constructor.name,
-            message: err.message,
-            stack: err.stack
-        }
-    }
-
-    
-    requestLogMessage(req, res) {
-        const prefix = '[VidaServer]';
-        if (req.controller) {
-            return `${prefix} ${req.controller.constructor.name}#${req.action}`;
-        }
-
-        return `${prefix} ${res.status >= 500 ? 'request errored' : 'request completed'}`;
-    }
-
-
-    requestLogLevel(req, res) {
-        return 'debug';
-    }
-
-
-    get middlewareLogger() {
-        return logger;
-    }
-
-
     /***********************************************************************************************
     * SETTINGS
     ***********************************************************************************************/
@@ -234,7 +180,7 @@ class VidaServer {
         const method         = action.method.toLowerCase();
         const requestHandler = this.requestHandler(action.action, controllerCls)
         if (process.env.NODE_ENV != 'test') {
-            logger.info(`ROUTE: ${method.toUpperCase().padEnd(6)} ${action.path}`);
+            logger.verbose(`ROUTE: ${method.toUpperCase().padEnd(6)} ${action.path}`);
         }
         this['_'+method](action.path, requestHandler);
     }

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.5",
+    "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",