@vida-global/core 2.4.5 → 3.0.0

package/lib/search/query.js

@@ -0,0 +1,163 @@
+class Query {
+    #client;
+    #conditions;
+
+
+    constructor(client, conditions) {
+        this.#client     = client;
+        this.#conditions = conditions || this.constructor.EMPTY_CONDITIONS;
+    }
+
+
+    static get EMPTY_CONDITIONS() {
+        return {and: [], or: [], not: [], options: {}};
+    }
+
+
+    static get DEFAULTS() {
+        return {BOOST: 1, FUZZINESS: 'AUTO', SORT_DIRECTION: 'desc'};
+    }
+
+
+    async fetch(options) {
+        return await this.#client.fetch(this.conditions, options);
+    }
+
+
+    get conditions() {
+        return structuredClone(this.#conditions);
+    }
+
+
+    /***********************************************************************************************
+    * OPERATORS
+    ***********************************************************************************************/
+    and(...newConditions) {
+        return this.#applyConditions('and', newConditions);
+    }
+
+
+    or(...newConditions) {
+        return this.#applyConditions('or', newConditions);
+    }
+
+
+    not(...newConditions) {
+        return this.#applyConditions('not', newConditions);
+    }
+
+
+    /***********************************************************************************************
+    * CONDITIONS
+    ***********************************************************************************************/
+    equals(field, value) {
+        return this.and({operator: 'equals', field, value});
+    }
+
+
+    in(field, values) {
+        return this.and({operator: 'in', field, value: values});
+    }
+
+
+    range(field, bounds) {
+        return this.and({operator: 'range', field, value: bounds});
+    }
+
+
+    exists(field) {
+        return this.and({operator: 'exists', field});
+    }
+
+
+    missing(field) {
+        return this.and({operator: 'missing', field});
+    }
+
+
+    matches(field, text, options = {}) {
+        const fuzziness = options.fuzziness || this.constructor.DEFAULTS.FUZZINESS;
+        return this.and({operator: 'matches', field, value: text, options: {fuzziness}});
+    }
+
+
+    phrase(field, text) {
+        return this.and({operator: 'phrase', field, value: text});
+    }
+
+
+    fullText(text, options = {}) {
+        const field    = this.#buildBoostMap(options);
+        const wildcard = Boolean(options.wildcard);
+        return this.and({operator: 'fullText', field, value: text, options: {wildcard}});
+    }
+
+
+    nested(path, query) {
+        return this.and({operator: 'nested', field: path, value: query.conditions});
+    }
+
+
+    /***********************************************************************************************
+    * OPTIONS
+    ***********************************************************************************************/
+    limit(value) {
+        return this.#applyOption('limit', value);
+    }
+
+
+    offset(value) {
+        return this.#applyOption('offset', value);
+    }
+
+
+    minScore(value) {
+        return this.#applyOption('minScore', value);
+    }
+
+
+    sort(field, direction) {
+        const sortKey  = {field, direction: direction || this.constructor.DEFAULTS.SORT_DIRECTION};
+        const sortKeys = [...(this.#conditions.options.sort || []), sortKey];
+        return this.#applyOption('sort', sortKeys);
+    }
+
+
+    /***********************************************************************************************
+    * CONDITION ASSEMBLY
+    ***********************************************************************************************/
+    #applyConditions(key, newConditions) {
+        const conditions = this.conditions;
+        for (const newCondition of newConditions) {
+            conditions[key].push(this.#normalizeCondition(newCondition));
+        }
+        return new this.constructor(this.#client, conditions);
+    }
+
+
+    #normalizeCondition(newCondition) {
+        if (newCondition instanceof Query) return newCondition.conditions;
+        return newCondition;
+    }
+
+
+    #applyOption(key, value) {
+        const conditions = this.conditions;
+        conditions.options[key] = value;
+        return new this.constructor(this.#client, conditions);
+    }
+
+
+    #buildBoostMap({fields, boost = {}}) {
+        const boostMap = {};
+        for (const field of fields) {
+            boostMap[field] = boost[field] || this.constructor.DEFAULTS.BOOST;
+        }
+        return boostMap;
+    }
+}
+
+
+module.exports = {
+    Query
+};

package/lib/server/authorizer.js

@@ -0,0 +1,42 @@
+const { camelize } = require('inflection');
+
+
+class Authorizer {
+    #currentUser;
+    #adminUser;
+
+    constructor(currentUser, adminUser) {
+        this.#currentUser = currentUser;
+        this.#adminUser   = adminUser;
+    }
+
+
+    async can(action, scope) {
+        if (!scope) return false;
+
+        const cls = this.classForScope(scope);
+        let permissionMethod = camelize(`${cls.name}Permission`, true);
+        if (!this[permissionMethod]) permissionMethod = 'defaultPermission';
+
+        return await this[permissionMethod](action, scope);
+    }
+
+
+    defaultPermission(action, scope) {
+        return false;
+    }
+
+
+    classForScope(scope) {
+        return !scope || scope.constructor == Function ? scope : scope.constructor;
+    }
+
+
+    get currentUser() { return this.#currentUser; }
+    get adminUser()   { return this.#adminUser;   }
+}
+
+
+module.exports = {
+    Authorizer
+}

package/lib/server/controllerMixins/validations.js

@@ -38,6 +38,7 @@ const InstanceMethods = {
         const errors = [];
 
         if (parameterValidations?.optional && value === undefined) return errors;
+        if (parameterValidations?.nullable === true && value === null) return errors;
 
         for (const [validationType, validationOptions] of Object.entries(parameterValidations)) {
             const validationMethod = `validate${camelize(validationType)}`;

package/lib/server/index.js

@@ -1,7 +1,8 @@
+const   Errors                 = require('./errors');
+const { ApiDocsGenerator }     = require('./openApi/apiDocsGenerator');
+const { Authorizer }           = require('./authorizer');
 const { VidaServer }           = require('./server');
 const { VidaServerController } = require('./serverController');
-const   Errors                 = require('./errors');
-const { ApiDocsGenerator }    = require('./openApi/apiDocsGenerator');
 
 
 module.exports = {

package/lib/server/serverController.js

@@ -1,11 +1,13 @@
-const   APM        = require('../apm');
-const { camelize } = require('inflection');
-const   crypto     = require('node:crypto');
+const   APM          = require('../apm');
+const { Authorizer } = require('./authorizer');
+const { camelize }   = require('inflection');
+const   crypto       = require('node:crypto');
 const   Errors       = require('./errors');
 const { logger }     = require('../logger');
 
 
 class VidaServerController {
+    #authorizer;
     #logger;
     #params;
     #rendered = false;
@@ -207,6 +209,38 @@ class VidaServerController {
     }
 
 
+    /***********************************************************************************************
+    * AUTH
+    ***********************************************************************************************/
+    async authorize(action, scope) {
+        const authorized = await this.can(action, scope);
+        if (!authorized) throw new this.Errors.Forbidden();
+    }
+
+
+    async can(action, scope) {
+        return await this.authorizer.can(action, scope);
+    }
+
+
+    get authorizer()  {
+        if (!this.#authorizer) {
+            this.#authorizer = new this.authorizerClass(...this.authorizerParameters);
+        }
+        return this.#authorizer;
+    }
+
+
+    get authorizerParameters() {
+        return [this.currentUser, this.adminUser];
+    }
+
+
+    get authorizerClass() {
+        return Authorizer;
+    }
+
+
     /***********************************************************************************************
     * SECURITY
     ***********************************************************************************************/

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vida-global/core",
-    "version": "2.4.5",
+    "version": "3.0.0",
     "description": "Core libraries for supporting Vida development",
     "author": "",
     "license": "ISC",
@@ -31,6 +31,7 @@
         "js-yaml": "^3.14.2",
         "mustache-express": "^1.2.8",
         "newrelic": "^13.0.0",
+        "@opensearch-project/opensearch": "^3.0.0",
         "pg": "^8.16.3",
         "redis": "^4.0.0",
         "response-time": "^2.3.3",

package/test/activeRecord/baseRecord.test.js

@@ -655,6 +655,28 @@ describe('BaseRecord', () => {
                 expect(Person.findAll).toHaveBeenCalledWith({where: {[pk]: [id1, id2]}});
             });
 
+            it ('sets each record with an expiry when expireSeconds is passed', async () => {
+                const key1 = `Person#find:${id1}`;
+                Person.findAll.mockImplementation(() => [new Person({[pk]:id1})]);
+                redisClient.mGet.mockImplementation(keys => [null]);
+
+                await Person._cachedFind([id1], {expireSeconds: 300});
+
+                expect(redisClient.mSet).not.toHaveBeenCalled();
+                expect(redisClient.set).toHaveBeenCalledTimes(1);
+                expect(redisClient.set).toHaveBeenCalledWith(key1, `AR:Person:{"${pk}":${id1}}`, {EX: 300});
+            });
+
+            it ('passes expireSeconds through from find', async () => {
+                const cacheSpy = jest.spyOn(Person, 'cachedFetch');
+
+                await Person.find([id1], {expireSeconds: 300});
+
+                expect(cacheSpy).toHaveBeenCalledWith(expect.any(Array), {clear: false, expireSeconds: 300},
+                                                      expect.any(Function));
+                cacheSpy.mockRestore();
+            });
+
             it ('returns an array of active record objects if an array was passed', async () => {
                 const p1 = new Person({[pk]: id1});
                 const p2 = new Person({[pk]: id2});

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

@@ -1,4 +1,5 @@
-const Helpers = require('../helpers/migrator');
+const   Helpers          = require('../helpers/migrator');
+const { MigrationError } = require('../../../lib/activeRecord/db/migrationErrors');
 
 
 afterEach(() => {
@@ -422,13 +423,13 @@ describe('Migrator', () => {
 
     describe('Migrator#removeIndex', () => {
         it.each([
-            ['default options', false, { transaction: null }],
-            ['concurrently', true, { concurrently: true, transaction: null }],
-        ])('passes removeIndex options for %s', async (_label, concurrently, expectedOptions) => {
+            ['default options', {}, { transaction: null }],
+            ['concurrently', { concurrently: true }, { concurrently: true, transaction: null }],
+        ])('passes removeIndex options for %s', async (_label, indexOptions, expectedOptions) => {
             const tableName = Helpers.randomString();
             const fields = [Helpers.randomString(), Helpers.randomString()];
 
-            await Helpers.migrator.removeIndex(tableName, fields, concurrently);
+            await Helpers.migrator.removeIndex(tableName, fields, indexOptions);
 
             expect(Helpers.mockQueryInterface.removeIndex).toHaveBeenCalledTimes(1);
             expect(Helpers.mockQueryInterface.removeIndex).toHaveBeenCalledWith(
@@ -453,6 +454,17 @@ describe('Migrator', () => {
     });
 
 
+    describe('Migrator concurrent indexes inside a transaction', () => {
+        it.each([
+            ['addIndex',    async function() { await this.addIndex('users', ['team_id'], { concurrently: true }); }],
+            ['removeIndex', async function() { await this.removeIndex('users', ['team_id'], { concurrently: true }); }],
+        ])('throws when %s asks for concurrently', async (methodName, operation) => {
+            await expect(Helpers.runInMigration(operation)).rejects.toThrow(MigrationError);
+            expect(Helpers.mockQueryInterface[methodName]).not.toHaveBeenCalled();
+        });
+    });
+
+
     describe('Migrator#defaultIndexName', () => {
         it ('builds idx_<table>_<columns> from a single column', () => {
             expect(Helpers.migrator.defaultIndexName('users', ['team_id'])).toBe('idx_users_team_id');

package/test/activeRecord/db/schema.test.js

@@ -122,6 +122,21 @@ describe('activeRecord/db/schema', () => {
                 const schema = getActiveRecordSchema('t', 'main', 'postgres');
                 expect(schema.name.autoIncrement).toBeUndefined();
             });
+
+
+            // A schema file is written from describeTable, and sequelize's postgres driver returns
+            // a BOOLEAN column's default as a javascript boolean rather than as text. Matching the
+            // sequence pattern against that boolean threw until e3dae1b replaced String#match with
+            // RegExp#test.
+            it.each([true, false, 5])('leaves a non-string defaultValue of %p alone', (defaultValue) => {
+                importSchema.mockImplementation(() => ({
+                    flag: { type: 'BOOLEAN', defaultValue, allowNull: false }
+                }));
+                const schema = getActiveRecordSchema('t', 'main', 'postgres');
+                expect(schema.flag.autoIncrement).toBeUndefined();
+                expect(schema.flag.defaultValue).toBe(defaultValue);
+                expect(schema.flag.allowNull).toBe(false);
+            });
         });
 
 

package/test/http/client.test.js

@@ -181,6 +181,48 @@ describe('HttpClient', () => {
     });
 
 
+    describe('binary responses', () => {
+        const client = new HttpClient();
+
+
+        beforeEach(() => Helpers.mockFetchBinary());
+
+
+        it ('returns the exact bytes as a Buffer', async () => {
+            const result = await client.get(Helpers.apiUrl, { binaryResponse: true });
+
+            expect(result.status).toBe(200);
+            expect(Buffer.isBuffer(result.data)).toBe(true);
+            expect(result.data).toEqual(Helpers.binaryPayload);
+        });
+
+
+        // The point of the option: a text read replaces every byte that is not valid UTF-8.
+        it ('never reads the body as text', async () => {
+            await client.get(Helpers.apiUrl, { binaryResponse: true });
+
+            const response = await fetch.mock.results[0].value;
+            expect(response.text).not.toHaveBeenCalled();
+        });
+
+
+        it ('reads the body as text without the option, losing the bytes', async () => {
+            const result = await client.get(Helpers.apiUrl);
+
+            expect(typeof result.data).toBe('string');
+            expect(Buffer.from(result.data)).not.toEqual(Helpers.binaryPayload);
+        });
+
+
+        const verbs = [['post'], ['put'], ['delete']];
+        it.each(verbs)('applies to %s as well', async (methodName) => {
+            const result = await client[methodName](Helpers.apiUrl, { binaryResponse: true });
+
+            expect(result.data).toEqual(Helpers.binaryPayload);
+        });
+    });
+
+
     describe('abort/timeout support', () => {
         const client = new HttpClient();
 

package/test/http/helpers/client.js

@@ -18,6 +18,10 @@ const apiUrl           = `${baseUrl}${endpoint}`;
 const responsePayload  = randomPayload();
 const responseBody     = JSON.stringify(responsePayload);
 
+// A RIFF header followed by byte sequences that are not valid UTF-8, so a text read cannot
+// reproduce them.
+const binaryPayload    = Buffer.from([0x52, 0x49, 0x46, 0x46, 0xff, 0xfe, 0x00, 0x80]);
+
 
 class ClientWithUrlRoot extends HttpClient {
     get urlRoot() {
@@ -67,11 +71,19 @@ const mockFetchResponse = ({ body, contentType, status = 200 }) => {
             get: jest.fn((headerName) => headerName == 'content-type' ? contentType : undefined),
         },
         status,
-        text: jest.fn().mockResolvedValue(body),
+        // Interpolated rather than passed through, so a Buffer body decodes the way a real text
+        // read would.
+        text:        jest.fn().mockResolvedValue(`${body ?? ''}`),
+        arrayBuffer: jest.fn().mockResolvedValue(Buffer.from(body ?? '')),
     });
 }
 
 
+const mockFetchBinary = () => {
+    mockFetchResponse({ body: binaryPayload, contentType: 'audio/wav' });
+}
+
+
 /***************************************************************************************************
 * ASSERTIONS
 ***************************************************************************************************/
@@ -109,11 +121,13 @@ module.exports = {
     apiUrl,
     basicAuthCredentials,
     bearerToken,
+    binaryPayload,
     ClientWithBasicAuth,
     ClientWithBearerToken,
     ClientWithUrlRoot,
     endpoint,
     expectRequest,
+    mockFetchBinary,
     mockFetchResponse,
     mockFetchSuccess,
     randomPayload,

package/test/jobQueue/helpers/bullmqMock.js

@@ -16,6 +16,7 @@ class MockBullQueue {
         this.close                   = jest.fn();
         this.pause                   = jest.fn();
         this.resume                  = jest.fn();
+        this.obliterate              = jest.fn();
         this.getJobCounts            = jest.fn();
         this.getJobs                 = jest.fn();
         this.getActive               = jest.fn();

package/test/jobQueue/queue.test.js

@@ -218,6 +218,17 @@ describe('Queue', () => {
     });
 
 
+    describe('#obliterate', () => {
+        it ('calls bullmq obliterate() with force so active jobs do not block it', async () => {
+            await queue.obliterate();
+
+            const instance = bullmqMock.instances.queues[0];
+            expect(instance.obliterate).toHaveBeenCalledTimes(1);
+            expect(instance.obliterate).toHaveBeenCalledWith({ force: true });
+        });
+    });
+
+
     describe('maximum concurrency', () => {
         it ('sets the queue maximum', async () => {
             const maximum = TestHelpers.Faker.Math.randomNumber(20);