@vida-global/core 2.3.3 → 2.3.4

package/AGENTS.md

@@ -2,12 +2,53 @@
 
 Use this guide to understand and write code for the vida-core repo.
 
+`@vida-global/core` is the shared library behind all Vida apps. It also ships to
+customers inside `vida-apps-tools`, so the exported surface is a public API.
+Treat a changed or removed export as a breaking change, not a refactor.
+
+CommonJS throughout (`require` / `module.exports`). There is no linter in this
+repo — the style guide below is the only enforcement, so follow it closely.
+
+
 # Style and conventions
+
+Always in force:
+
 @agents/style.md
-@agents/server.md
-@agents/db.md
-@agents/apis.md
 @agents/testing.md
 
+Read only when the work touches that area:
+
+- `agents/server.md` — Express endpoints, controllers, validation, status codes
+- `agents/db.md` — ActiveRecord, Sequelize, migrations, caching
+- `agents/apis.md` — outbound HTTP clients to third parties
+- `agents/git.md` — branches, commits, GitHub
+- `agents/frontend.md` — Next.js/React only. Not used by this package.
+
+
+# Commands
+
+    npm test                     # jest, coverage on by default
+    npm test -- test/server      # narrow to a directory
+    npm test -- -t 'name'        # narrow by test name
+    npm run develop              # prerelease via @vida-global/release
+    npm run release              # release via @vida-global/release
+
+`npm test` carries required flags (`LOG_LEVEL=test`, `NODE_NO_WARNINGS=1`,
+`node --experimental-vm-modules`). Always go through the script. Calling `jest`
+directly drops them and the run misbehaves.
+
+Coverage is collected on every run. `/helpers/` is excluded by design.
+
+
+# Repository map
+
+`index.js` is the whole public surface. `lib/` holds the modules; `test/` mirrors
+`lib/` one directory per module. Per-module guides live next to the code and are
+listed in `README.md`: `activeRecord`, `http`, `logger`, `server`, `jobQueue`,
+plus `cache`, `redis`, `apm`, `observability`, `utils`.
 
-# Helpers for common use cases
+One non-obvious mechanic in `index.js`: server error classes are exported by
+filtering `lib/server` exports on `prototype instanceof AbstractServerError`. A
+new error class that extends it is exported automatically — do not add it to
+`module.exports` by hand. One that does not extend it is silently absent.

package/lib/activeRecord/db/migrator.js

@@ -119,8 +119,11 @@ class Migrator {
 
 
     idColumn(idType=DEFAULT_ID_TYPE) {
+        if (idType === false) return {};
+
         if (!ID_TYPES.includes(idType)) {
-            throw new Error(`Unknown id type "${idType}". Use one of: ${ID_TYPES.join(', ')}`);
+            throw new Error(`Unknown id type "${idType}". Use one of: ${ID_TYPES.join(', ')}, or `
+                          + `false for a table that declares its own primary key.`);
         }
 
         return this[`${idType}IdColumn`];

package/lib/server/controllerMixins/renderer.js

@@ -9,6 +9,13 @@ class StreamInProgressError extends Error {}
 class NoActiveStreamError   extends Error {}
 
 
+// xmlbuilder2's default object-notation control prefixes: @attribute, #text, $cdata,
+// !comment, ?processing-instruction. A key using one of these must survive sanitization
+// unmangled, or an intended attribute (e.g. {'@track': 'both'}) silently turns into a
+// child element (`<_track>both</_track>`) instead of `track="both"`.
+const XML_CONVERT_PREFIXES = ['@', '#', '$', '!', '?'];
+
+
 const CONTENT_TYPE_BY_EXTENSION = {
     css:   'text/css; charset=utf-8',
     gif:   'image/gif',
@@ -88,12 +95,17 @@ const InstanceMethods = {
         if (!this.responseContentType) this.responseContentType = CONTENT_TYPE_BY_EXTENSION.xml;
         const doc = create({ [this.xmlRootElement]: body });
         const xml = doc.end();
-        this._response.send(xml);
+        this._send(xml);
     },
 
 
     renderTextResponse(body) {
         if (!this.responseContentType) this.responseContentType = CONTENT_TYPE_BY_EXTENSION.txt;
+        this._send(body);
+    },
+
+
+    _send(body) {
         this._response.send(body);
     },
 
@@ -182,8 +194,23 @@ const InstanceMethods = {
 
     // XML element names can't start with a digit or contain spaces/other invalid characters,
     // so sanitize keys that would otherwise make xmlbuilder2 throw on dynamic response data.
+    // A leading xmlbuilder2 control prefix (see XML_CONVERT_PREFIXES) is preserved as-is;
+    // only the remainder (the attribute/PI name, if any) is sanitized.
     _toXMLElementName(key) {
-        let name = `${key}`.replace(/[^a-zA-Z0-9_.-]/g, '_');
+        key = `${key}`;
+
+        const prefix = XML_CONVERT_PREFIXES.find(p => key.startsWith(p));
+        if (prefix) {
+            const rest = key.slice(prefix.length);
+            return rest ? prefix + this._sanitizeXMLNamePart(rest) : prefix;
+        }
+
+        return this._sanitizeXMLNamePart(key);
+    },
+
+
+    _sanitizeXMLNamePart(name) {
+        name = name.replace(/[^a-zA-Z0-9_.-]/g, '_');
         if (!/^[a-zA-Z_]/.test(name)) name = `_${name}`;
         return name;
     },

package/lib/server/controllerMixins/requestDetails.js

@@ -47,8 +47,10 @@ const Accessors = {
 
     contentType:     { get() { return this.requestHeaders['content-type']          }},
     cookies:         { get() { return this._request.cookies || {}                  }},
+    isProxiedRequest:{ get() { return Boolean(this.requestHeaders['x-forwarded-for']) }},
     requestBody:     { get() { return this._request.body                           }},
     requestHeaders:  { get() { return structuredClone(this._request.headers || {}) }},
+    requestHost:     { get() { return this.requestHeaders.host                     }},
     requestId:       { get() { return this._request.id                             }},
     requestIp:       { get() { return this._request.ip                             }},
     requestMethod:   { get() { return this._request.method                         }},
@@ -73,6 +75,36 @@ const Accessors = {
             return match[1].trim();
         }
     },
+
+
+    // The absolute URL the caller addressed, rebuilt from the request. Webhook signature schemes
+    // sign this string, so it has to match what the sender used character for character.
+    requestUrl: {
+        get() { return `${this.requestProtocol}://${this.requestHost}${this.url}` }
+    },
+
+
+    // TLS usually terminates at a load balancer, and not every balancer forwards
+    // X-Forwarded-Proto, so `_request.protocol` can report http on a request the caller made over
+    // https. Prefer the forwarded protocol, assume https for anything else that arrived through a
+    // proxy, and fall back to the connection's own protocol for direct requests.
+    requestProtocol: {
+        get() {
+            if (this.forwardedProtocol) return this.forwardedProtocol;
+            if (this.isProxiedRequest)  return 'https';
+            return this._request.protocol;
+        }
+    },
+
+
+    // A comma-joined chain lists the original client's protocol first.
+    forwardedProtocol: {
+        get() {
+            const header = this.requestHeaders['x-forwarded-proto'];
+            if (!header) return null;
+            return header.split(',')[0].trim();
+        }
+    },
 }
 
 

package/lib/server/doc/requestDetails.md

@@ -19,6 +19,11 @@ Within an action, the controller exposes:
 | `this.requestMethod` | HTTP method. |
 | `this.requestIp` | Client IP address. |
 | `this.url` | Original URL. |
+| `this.requestHost` | Shortcut for `requestHeaders['host']`. |
+| `this.requestUrl` | Absolute URL the caller addressed: `requestProtocol://requestHost + url`. Use this when verifying a webhook signature that covers the URL. |
+| `this.requestProtocol` | `forwardedProtocol`, else `https` when `isProxiedRequest`, else the connection's own protocol. |
+| `this.forwardedProtocol` | First entry of `X-Forwarded-Proto`, or `null`. |
+| `this.isProxiedRequest` | `true` when `X-Forwarded-For` is present. |
 | `this.bearerToken` | Parsed `Authorization: Bearer <token>` value, or `null`. |
 | `this.statusCode` | Current outgoing status (settable, but prefer the render helpers below). |
 | `this.logger` | Per-request child logger. |

package/lib/server/server.js

@@ -192,7 +192,7 @@ class VidaServer {
         const method         = action.method.toLowerCase();
         const requestHandler = this.requestHandler(action.action, controllerCls)
         if (process.env.NODE_ENV != 'test') {
-            this.logger.verbose(`ROUTE: ${method.toUpperCase().padEnd(6)} ${action.path}`);
+            this.logger.debug(`ROUTE: ${method.toUpperCase().padEnd(6)} ${action.path}`);
         }
         this['_'+method](action.path, requestHandler);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vida-global/core",
-    "version": "2.3.3",
+    "version": "2.3.4",
     "description": "Core libraries for supporting Vida development",
     "author": "",
     "license": "ISC",

package/test/activeRecord/db/migrator.test.js

@@ -177,6 +177,48 @@ describe('Migrator', () => {
                 .rejects.toThrow(`Unknown id type "${idType}". Use one of: bigint, int, uuid`);
         });
 
+        it ('tells the caller false is an option when refusing an id type', async () => {
+            await expect(Helpers.migrator.createTable(Helpers.randomString(), {}, { id: Helpers.randomString() }))
+                .rejects.toThrow('or false for a table that declares its own primary key');
+        });
+
+        // For a table whose primary key is a natural column, e.g. a baseline migration recreating
+        // a table that predates the migrations directory.
+        it ('adds no id column when id is false', async () => {
+            const tableName = Helpers.randomString();
+
+            await Helpers.migrator.createTable(tableName, {}, { id: false });
+
+            const [, columns] = Helpers.mockQueryInterface.createTable.mock.calls[0];
+            expect(columns).not.toHaveProperty('id');
+        });
+
+        it ('keeps the table details when id is false', async () => {
+            const tableName = Helpers.randomString();
+            const uuid      = { allowNull: false, primaryKey: true, type: 'UUID' };
+
+            await Helpers.migrator.createTable(tableName, { uuid }, { id: false, timestamps: false });
+
+            expect(Helpers.mockQueryInterface.createTable).toHaveBeenCalledWith(
+                tableName, { uuid }, Helpers.noTransaction,
+            );
+        });
+
+        const notFalseCases = [['null', null], ['zero', 0], ['an empty string', '']];
+        it.each(notFalseCases)('does not treat %s as false', async (_label, idType) => {
+            await expect(Helpers.migrator.createTable(Helpers.randomString(), {}, { id: idType }))
+                .rejects.toThrow('Unknown id type');
+        });
+
+        it ('still defaults to a bigint id when no id option is given', async () => {
+            const tableName = Helpers.randomString();
+
+            await Helpers.migrator.createTable(tableName, {}, {});
+
+            const [, columns] = Helpers.mockQueryInterface.createTable.mock.calls[0];
+            expect(columns.id).toEqual({ allowNull: false, autoIncrement: true, primaryKey: true, type: 'BIGINT' });
+        });
+
         it ('lets the details override the id column', async () => {
             const tableName = Helpers.randomString();
             const id        = { allowNull: false, primaryKey: true, type: 'UUID' };

package/test/server/controllerMixins/renderer.test.js

@@ -494,6 +494,68 @@ describe('VidaServerController', () => {
             expect(controller._toXMLElementName('first name')).toBe('first_name');
             expect(controller._toXMLElementName('a:b')).toBe('a_b');
         });
+
+
+        // xmlbuilder2 reads these prefixes as instructions rather than as part of the name.
+        // Sanitizing one away silently turns an intended attribute into a child element.
+        const prefixCases = [
+            ['attribute',              '@', '@track',   'both'],
+            ['text',                   '#', '#text',    'value'],
+            ['cdata',                  '$', '$cdata',   'value'],
+            ['comment',                '!', '!comment', 'value'],
+            ['processing instruction', '?', '?target',  'value'],
+        ];
+        it.each(prefixCases)('preserves the %s prefix', (_label, _prefix, key) => {
+            expect(controller._toXMLElementName(key)).toBe(key);
+        });
+
+        it ('sanitizes the name after the prefix but keeps the prefix', () => {
+            expect(controller._toXMLElementName('@my attr')).toBe('@my_attr');
+            expect(controller._toXMLElementName('@a:b')).toBe('@a_b');
+        });
+
+        it ('underscores a prefixed name that starts with a digit', () => {
+            expect(controller._toXMLElementName('@123')).toBe('@_123');
+        });
+
+        it ('returns a bare prefix untouched', () => {
+            expect(controller._toXMLElementName('@')).toBe('@');
+            expect(controller._toXMLElementName('#')).toBe('#');
+        });
+
+        it ('only treats a prefix as a prefix in the leading position', () => {
+            expect(controller._toXMLElementName('track@')).toBe('track_');
+            expect(controller._toXMLElementName('a#b')).toBe('a_b');
+        });
+    });
+
+
+    // The end-to-end reason the prefixes are preserved: without it these render as child
+    // elements (<_track>both</_track>) rather than attributes.
+    describe('#renderXMLResponse attribute rendering', () => {
+        it ('renders @-prefixed keys as XML attributes', async () => {
+            const response   = buildResponseMock();
+            const controller = new FooController({query: {_format: 'xml'}}, response);
+            controller.formatResponseBody = body => body;
+
+            await controller.render({Record: {'@track': 'both', '@trim': 'do-not-trim'}});
+
+            expect(response.send).toHaveBeenCalledWith(
+                expect.stringContaining('<Record track="both" trim="do-not-trim"/>')
+            );
+        });
+
+        it ('still renders an ordinary key as a child element', async () => {
+            const response   = buildResponseMock();
+            const controller = new FooController({query: {_format: 'xml'}}, response);
+            controller.formatResponseBody = body => body;
+
+            await controller.render({Record: {'weird key!': 'x'}});
+
+            expect(response.send).toHaveBeenCalledWith(
+                expect.stringContaining('<weird_key_>x</weird_key_>')
+            );
+        });
     });
 
 

package/test/server/controllerMixins/requestDetails.test.js

@@ -88,6 +88,72 @@ describe('VidaServerController', () => {
         });
 
 
+        describe('#requestHost', () => {
+            it ('returns the host request header', () => {
+                request.headers.host = `${TestHelpers.Faker.Text.randomString()}.vida.dev`;
+                expect(controller.requestHost).toEqual(request.headers.host);
+            });
+        });
+
+
+        describe('#forwardedProtocol', () => {
+            it ('returns null when the proxy sends no forwarded protocol', () => {
+                delete request.headers['x-forwarded-proto'];
+                expect(controller.forwardedProtocol).toBe(null);
+            });
+
+            it ('returns the forwarded protocol', () => {
+                request.headers['x-forwarded-proto'] = 'https';
+                expect(controller.forwardedProtocol).toEqual('https');
+            });
+
+            it ('returns only the first entry of a forwarded protocol chain', () => {
+                request.headers['x-forwarded-proto'] = 'https, http';
+                expect(controller.forwardedProtocol).toEqual('https');
+            });
+        });
+
+
+        describe('#isProxiedRequest', () => {
+            it.each([
+                ['x-forwarded-for is present', '203.0.113.7', true],
+                ['x-forwarded-for is absent',  undefined,     false],
+            ])('returns %s -> %s', (_label, forwardedFor, expected) => {
+                delete request.headers['x-forwarded-for'];
+                if (forwardedFor) request.headers['x-forwarded-for'] = forwardedFor;
+                expect(controller.isProxiedRequest).toBe(expected);
+            });
+        });
+
+
+        describe('#requestUrl', () => {
+            beforeEach(() => {
+                request.headers.host = 'api.vida.dev';
+                request.originalUrl  = '/things?page=2';
+                request.protocol     = 'http';
+                delete request.headers['x-forwarded-proto'];
+                delete request.headers['x-forwarded-for'];
+            });
+
+            it ('uses the forwarded protocol when the proxy sends one', () => {
+                request.headers['x-forwarded-proto'] = 'https';
+                request.headers['x-forwarded-for']   = '203.0.113.7';
+                expect(controller.requestUrl).toEqual('https://api.vida.dev/things?page=2');
+            });
+
+            // Not every balancer forwards X-Forwarded-Proto, so a proxied request can look like
+            // plain http even though the caller addressed an https URL.
+            it ('assumes https for a proxied request that carries no forwarded protocol', () => {
+                request.headers['x-forwarded-for'] = '203.0.113.7';
+                expect(controller.requestUrl).toEqual('https://api.vida.dev/things?page=2');
+            });
+
+            it ('keeps the connection protocol for a direct request with no proxy headers', () => {
+                expect(controller.requestUrl).toEqual('http://api.vida.dev/things?page=2');
+            });
+        });
+
+
         describe('#statusCode', () => {
             it ('returns the response status code', () => {
                 expect(controller.statusCode).toEqual(response.statusCode);