@vida-global/core 2.5.0 → 3.0.1

package/lib/search/openSearchClient.js

@@ -0,0 +1,319 @@
+const { AbstractSearchClient } = require('./abstractSearchClient');
+const { AwsSigv4Signer }       = require('@opensearch-project/opensearch/aws');
+const { BulkWriteError, UnsupportedOperationError } = require('./errors');
+const { Client }               = require('@opensearch-project/opensearch');
+
+
+class OpenSearchClient extends AbstractSearchClient {
+    #_client;
+
+
+    static get SERVICE() { return 'aoss'; }
+
+
+    get wildcardIndex() { return `${this.index}-*`; }
+    get endpoint()      { throw new Error('Not Implemented') }
+
+
+    get writeIndex() {
+        if (!this.indexSuffix) return this.index;
+        return `${this.index}-${this.indexSuffix}`;
+    }
+
+
+    /***********************************************************************************************
+    * READ
+    ***********************************************************************************************/
+    async _execute(serializedConditions, options) {
+        return await this.#client.search({
+            index: this.#readIndexForFetch(options),
+            body:  serializedConditions
+        });
+    }
+
+
+    _hitsFromResponse(response)  { return response.body.hits                   }
+    _totalFromResponse(response) { return response.body.hits.total?.value || 0 }
+    _idFromHit(hit)              { return hit._id                              }
+    _scoreFromHit(hit)           { return hit._score                           }
+    _documentFromHit(hit)        { return hit._source                          }
+
+
+    #readIndexForFetch({indexWildcard}) {
+        return indexWildcard ? this.wildcardIndex : this.writeIndex;
+    }
+
+
+    /***********************************************************************************************
+    * SERIALIZATION
+    ***********************************************************************************************/
+    _serializeConditions(conditions) {
+        return {
+            query:            this.#serializeTree(conditions),
+            track_total_hits: true,
+            ...this.#serializeOptions(conditions.options)
+        };
+    }
+
+
+    #serializeTree(conditions) {
+        const must    = this.#serializeAll(conditions.and);
+        const mustNot = this.#serializeAll(conditions.not);
+        if (conditions.or.length) must.push(this.#serializeShouldGroup(conditions.or));
+
+        if (must.length === 1 && !mustNot.length) return must[0];
+        return {bool: {must, must_not: mustNot}};
+    }
+
+
+    #serializeAll(conditions) {
+        return conditions.map(condition => this.#serializeCondition(condition));
+    }
+
+
+    // `minimum_should_match` is not optional here: alongside a populated `must`, OpenSearch treats
+    // `should` clauses as score boosters rather than filters, so the group would stop filtering.
+    #serializeShouldGroup(conditions) {
+        return {bool: {should: this.#serializeAll(conditions), minimum_should_match: 1}};
+    }
+
+
+    #serializeCondition(condition) {
+        if (condition.operator) return this.#serializeLeaf(condition);
+        return this.#serializeTree(condition);
+    }
+
+
+    #serializeLeaf(leaf) {
+        const operator = `${leaf.operator[0].toUpperCase()}${leaf.operator.slice(1)}`;
+        return this[`_serialize${operator}`](leaf);
+    }
+
+
+    #serializeOptions({limit, minScore, offset, sort}) {
+        const body = {};
+
+        if (limit    !== undefined) body.size      = limit;
+        if (offset   !== undefined) body.from      = offset;
+        if (minScore !== undefined) body.min_score = minScore;
+        if (sort)                   body.sort      = this.#serializeSort(sort);
+        return body;
+    }
+
+
+    #serializeSort(sortKeys) {
+        return sortKeys.map(({field, direction}) => ({[field]: {order: direction}}));
+    }
+
+
+    /***********************************************************************************************
+    * CONDITION SERIALIZERS
+    ***********************************************************************************************/
+    _serializeEquals({field, value}) {
+        return {term: {[field]: {value}}};
+    }
+
+
+    _serializeIn({field, value}) {
+        return {terms: {[field]: value}};
+    }
+
+
+    _serializeRange({field, value}) {
+        return {range: {[field]: value}};
+    }
+
+
+    _serializeExists({field}) {
+        return {exists: {field}};
+    }
+
+
+    _serializeMissing({field}) {
+        return {bool: {must_not: {exists: {field}}}};
+    }
+
+
+    _serializeMatches({field, value, options}) {
+        return {match: {[field]: {query: value, fuzziness: options.fuzziness}}};
+    }
+
+
+    _serializePhrase({field, value}) {
+        return {match_phrase: {[field]: {query: value}}};
+    }
+
+
+    _serializeFullText({field, value, options}) {
+        const query  = options.wildcard ? `*${value}*` : value;
+        const fields = Object.entries(field).map(([name, boost]) => `${name}^${boost}`);
+
+        return {query_string: {query, fields}};
+    }
+
+
+    _serializeNested({field, value}) {
+        return {nested: {path: field, query: this.#serializeTree(value)}};
+    }
+
+
+    /***********************************************************************************************
+    * WRITE
+    ***********************************************************************************************/
+    async _upsert(id, document) {
+        return await this.#rethrowUnsupported('upsert', () => this.#client.update({
+            id,
+            index: this.writeIndex,
+            body:  {doc: document, doc_as_upsert: true}
+        }));
+    }
+
+
+    async _append(document) {
+        return await this.#client.index({index: this.writeIndex, body: document});
+    }
+
+
+    async _delete(id) {
+        return await this.#client.delete({id, index: this.writeIndex});
+    }
+
+
+    async _bulkUpsert(documents) {
+        const body     = this.#buildBulkBody(documents);
+        const response = await this.#rethrowUnsupported('bulkUpsert', () => this.#client.bulk({body}));
+        this.#assertBulkSucceeded(response);
+        return response;
+    }
+
+
+    #buildBulkBody(documents) {
+        const operations = [];
+
+        for (const { id, document } of documents) {
+            operations.push({update: {_id: id, _index: this.writeIndex}});
+            operations.push({doc: document, doc_as_upsert: true});
+        }
+        return operations;
+    }
+
+
+    #assertBulkSucceeded(response) {
+        if (!response.body.errors) return;
+
+        const failures = this.#collectBulkFailures(response.body.items);
+        throw new BulkWriteError(`${failures.length} documents could not be written`, failures);
+    }
+
+
+    #collectBulkFailures(items) {
+        const failures = [];
+
+        for (const item of items) {
+            const outcome = item.update;
+            if (outcome.error) failures.push({id: outcome._id, reason: outcome.error.reason});
+        }
+        return failures;
+    }
+
+
+    async #rethrowUnsupported(operationName, operation) {
+        try {
+            return await operation();
+        } catch (error) {
+            if (!this._isUnsupportedOperation(error)) throw error;
+            throw new UnsupportedOperationError(
+                `${operationName} is not supported by the collection behind ${this.constructor.name}`,
+                {cause: error}
+            );
+        }
+    }
+
+
+    // Serverless rejects every write addressed to a document id unless the collection is of type
+    // SEARCH. Nothing in the response names the collection type, so the refusal is read off the
+    // message. The regex here is a guess and should be fixed if it doesn't properly catch the error
+    _isUnsupportedOperation(error) {
+        const statusCode = error.statusCode || error.meta?.statusCode;
+        if (statusCode !== 400) return false;
+        return /not supported/i.test(error.message || '');
+    }
+
+
+    /***********************************************************************************************
+    * ADMIN
+    ***********************************************************************************************/
+    async _indexExists() {
+        const response = await this.#client.indices.exists({index: this.writeIndex});
+        return Boolean(response.body);
+    }
+
+
+    async _createIndex() {
+        return await this.#client.indices.create({index: this.writeIndex});
+    }
+
+
+    async _putMapping() {
+        return await this.#client.indices.putMapping({index: this.writeIndex, body: this.mapping});
+    }
+
+
+    /***********************************************************************************************
+    * RETRIES
+    ***********************************************************************************************/
+    shouldRetry(attemptCount, error) {
+        if (!super.shouldRetry(attemptCount, error)) return false;
+        return this.#isServerError(error);
+    }
+
+
+    #isServerError(error) {
+        const statusCode = error.statusCode || error.meta?.statusCode;
+        return statusCode >= 500 && statusCode < 600;
+    }
+
+
+    /***********************************************************************************************
+    * CLIENT CONFIG
+    ***********************************************************************************************/
+    get openSearchClientClass() { return Client; }
+    get awsSignerFactory()      { return AwsSigv4Signer; }
+
+
+    get #client() {
+        return this.#_client ||= new this.openSearchClientClass(this.#config);
+    }
+
+
+    get #config() {
+        return {...this.awsSigner, node: this.endpoint};
+    }
+
+
+    get awsSigner() {
+        return this.awsSignerFactory({
+            region:         this.region,
+            service:        this.constructor.SERVICE,
+            getCredentials: this.getCredentials.bind(this)
+        });
+    }
+
+
+    get region() {
+        return process.env.OPENSEARCH_REGION || process.env.DEFAULT_AWS_REGION;
+    }
+
+
+    async getCredentials() {
+        return {
+            accessKeyId:     process.env.OPENSEARCH_AWS_KEY,
+            secretAccessKey: process.env.OPENSEARCH_AWS_SECRET
+        };
+    }
+}
+
+
+module.exports = {
+    OpenSearchClient
+};

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/index.js

@@ -1,11 +1,13 @@
+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 = {
     ApiDocsGenerator,
+    Authorizer,
     ...Errors,
     VidaServer,
     VidaServerController,

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.5.0",
+    "version": "3.0.1",
     "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/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);
+            });
         });