@vida-global/core 1.4.5 → 2.0.0

package/test/jobQueue/abstractJob.test.js

@@ -0,0 +1,307 @@
+const TestHelpers              = require('@vida-global/test-helpers');
+const { defineJobSubclass }    = require('./helpers/abstractJob');
+
+
+jest.mock('../../lib/jobQueue/queue', () => ({
+    getQueue: jest.fn(),
+}));
+
+jest.mock('../../lib/logger', () => {
+    const { buildLoggerMock } = require('./helpers/loggerMock');
+    return { logger: buildLoggerMock() };
+});
+
+jest.mock('../../lib/apm', () => {
+    const { buildApmMock } = require('./helpers/apmMock');
+    return buildApmMock();
+});
+
+
+let AbstractJob;
+let getQueue;
+let logger;
+let APM;
+
+beforeEach(() => {
+    jest.resetModules();
+    ({ AbstractJob } = require('../../lib/jobQueue/abstractJob'));
+    ({ getQueue }    = require('../../lib/jobQueue/queue'));
+    ({ logger }      = require('../../lib/logger'));
+    APM              = require('../../lib/apm');
+});
+
+
+afterEach(() => {
+    jest.clearAllMocks();
+});
+
+
+describe('AbstractJob', () => {
+    describe('constructor', () => {
+        it ('throws when AbstractJob is instantiated directly', () => {
+            expect(() => new AbstractJob()).toThrow('Cannot create an instance of AbstractJob');
+        });
+
+        it ('throws when the subclass does not define a queueName', () => {
+            class NoQueueJob extends AbstractJob {
+                async run() {}
+            }
+
+            expect(() => new NoQueueJob()).toThrow('No queue defined');
+        });
+
+        it ('throws when the subclass does not define a run method', () => {
+            class NoRunJob extends AbstractJob {
+                static queueName() { return 'q'; }
+            }
+
+            expect(() => new NoRunJob()).toThrow('No run method defined');
+        });
+
+        it ('succeeds when the subclass defines both queueName and run', () => {
+            const Subclass = defineJobSubclass(AbstractJob);
+
+            expect(() => new Subclass()).not.toThrow();
+        });
+    });
+
+
+    describe('.queue', () => {
+        it ('returns the queue from getQueue invoked with the resolved queue name', () => {
+            const name        = TestHelpers.Faker.Text.randomString();
+            const Subclass    = defineJobSubclass(AbstractJob, { queueName: name });
+            const stubQueue   = { queueJob: jest.fn() };
+            getQueue.mockReturnValue(stubQueue);
+
+            const result = Subclass.queue('arg1', 'arg2');
+
+            expect(getQueue).toHaveBeenCalledTimes(1);
+            expect(getQueue).toHaveBeenCalledWith(name);
+            expect(result).toBe(stubQueue);
+        });
+
+        it ('passes job args through to a dynamic queueName method', () => {
+            const arg1          = TestHelpers.Faker.Text.randomString();
+            const arg2          = TestHelpers.Faker.Math.randomNumber();
+            const queueNameSpy  = jest.fn(() => 'dynamic-queue');
+            const Subclass      = defineJobSubclass(AbstractJob, { queueNameFn: queueNameSpy });
+            getQueue.mockReturnValue({ queueJob: jest.fn() });
+
+            Subclass.queue(arg1, arg2);
+
+            expect(queueNameSpy).toHaveBeenCalledWith(arg1, arg2);
+            expect(getQueue).toHaveBeenCalledWith('dynamic-queue');
+        });
+    });
+
+
+    describe('.queueJob', () => {
+        it ('enqueues the job on the resolved queue with the args and settings', async () => {
+            const name      = TestHelpers.Faker.Text.randomString();
+            const Subclass  = defineJobSubclass(AbstractJob, { queueName: name });
+            const stubQueue = { queueJob: jest.fn().mockResolvedValue(undefined) };
+            getQueue.mockReturnValue(stubQueue);
+            const arg1 = TestHelpers.Faker.Text.randomString();
+            const arg2 = TestHelpers.Faker.Math.randomNumber();
+
+            await Subclass.queueJob(arg1, arg2);
+
+            expect(stubQueue.queueJob).toHaveBeenCalledTimes(1);
+            expect(stubQueue.queueJob).toHaveBeenCalledWith(
+                Subclass,
+                [arg1, arg2],
+                Subclass.queueSettings(arg1, arg2),
+            );
+        });
+
+        it ('awaits the underlying queueJob call', async () => {
+            const Subclass = defineJobSubclass(AbstractJob);
+            let resolveQueueJob;
+            const queueJobPromise = new Promise((resolve) => { resolveQueueJob = resolve; });
+            getQueue.mockReturnValue({ queueJob: jest.fn().mockReturnValue(queueJobPromise) });
+
+            const callPromise = Subclass.queueJob();
+            let resolved      = false;
+            callPromise.then(() => { resolved = true; });
+            await Promise.resolve();
+            expect(resolved).toBe(false);
+
+            resolveQueueJob();
+            await callPromise;
+            expect(resolved).toBe(true);
+        });
+    });
+
+
+    describe('.queueSettings', () => {
+        it ('returns default retry settings', () => {
+            const Subclass = defineJobSubclass(AbstractJob);
+
+            expect(Subclass.queueSettings()).toEqual({
+                attempts: 3,
+                backoff:  { type: 'exponential', delay: 2000 },
+            });
+        });
+
+        it ('reflects subclass overrides for retry settings', () => {
+            const numRetries        = TestHelpers.Faker.Math.randomNumber(20);
+            const retryBackoffType  = TestHelpers.Faker.Text.randomString();
+            const retryBackoffDelay = TestHelpers.Faker.Math.randomNumber(10000);
+            const Subclass          = defineJobSubclass(AbstractJob, {
+                numRetries,
+                retryBackoffType,
+                retryBackoffDelay,
+            });
+
+            expect(Subclass.queueSettings()).toEqual({
+                attempts: numRetries,
+                backoff:  { type: retryBackoffType, delay: retryBackoffDelay },
+            });
+        });
+    });
+
+
+    describe('default static getters', () => {
+        it ('.numRetries defaults to 3',                       () => expect(AbstractJob.numRetries).toEqual(3));
+        it ('.retryBackoffType defaults to "exponential"',     () => expect(AbstractJob.retryBackoffType).toEqual('exponential'));
+        it ('.retryBackoffDelay defaults to 2000',             () => expect(AbstractJob.retryBackoffDelay).toEqual(2000));
+    });
+
+
+    describe('#_run', () => {
+        it ('stores the id and exposes it via #id', async () => {
+            const Subclass = defineJobSubclass(AbstractJob);
+            const job      = new Subclass();
+            const id       = TestHelpers.Faker.Text.randomString();
+
+            await job._run(id, [], jest.fn());
+
+            expect(job.id).toEqual(id);
+        });
+
+        it ('calls run with the spread args', async () => {
+            const runSpy   = jest.fn().mockResolvedValue(undefined);
+            const Subclass = defineJobSubclass(AbstractJob, { run: runSpy });
+            const job      = new Subclass();
+            const args     = [TestHelpers.Faker.Text.randomString(), TestHelpers.Faker.Math.randomNumber()];
+
+            await job._run('id', args, jest.fn());
+
+            expect(runSpy).toHaveBeenCalledTimes(1);
+            expect(runSpy).toHaveBeenCalledWith(...args);
+        });
+
+        it ('propagates rejections from run', async () => {
+            const error    = new Error(TestHelpers.Faker.Text.randomString());
+            const Subclass = defineJobSubclass(AbstractJob, { run: jest.fn().mockRejectedValue(error) });
+            const job      = new Subclass();
+
+            await expect(job._run('id', [], jest.fn())).rejects.toBe(error);
+        });
+
+        it ('stores the updateProgress callback for later use', async () => {
+            const Subclass = defineJobSubclass(AbstractJob);
+            const job      = new Subclass();
+            const callback = jest.fn().mockResolvedValue(undefined);
+
+            await job._run('id', [], callback);
+            const payload = TestHelpers.Faker.Text.randomString();
+            await job.updateProgress(payload);
+
+            expect(callback).toHaveBeenCalledTimes(1);
+            expect(callback).toHaveBeenCalledWith(payload);
+        });
+    });
+
+
+    describe('#id', () => {
+        it ('returns undefined before _run has been invoked', () => {
+            const Subclass = defineJobSubclass(AbstractJob);
+            const job      = new Subclass();
+
+            expect(job.id).toBeUndefined();
+        });
+    });
+
+
+    describe('#updateProgress', () => {
+        it ('forwards all arguments to the stored callback', async () => {
+            const Subclass = defineJobSubclass(AbstractJob);
+            const job      = new Subclass();
+            const callback = jest.fn().mockResolvedValue(undefined);
+            await job._run('id', [], callback);
+
+            const arg1 = TestHelpers.Faker.Math.randomNumber();
+            const arg2 = TestHelpers.Faker.Text.randomString();
+            await job.updateProgress(arg1, arg2);
+
+            expect(callback).toHaveBeenCalledWith(arg1, arg2);
+        });
+
+        it ('awaits the callback', async () => {
+            const Subclass = defineJobSubclass(AbstractJob);
+            const job      = new Subclass();
+            let resolveCallback;
+            const callback = jest.fn(() => new Promise((res) => { resolveCallback = res; }));
+            await job._run('id', [], callback);
+
+            const callPromise = job.updateProgress();
+            let resolved      = false;
+            callPromise.then(() => { resolved = true; });
+            await Promise.resolve();
+            expect(resolved).toBe(false);
+
+            resolveCallback();
+            await callPromise;
+            expect(resolved).toBe(true);
+        });
+    });
+
+
+    describe('#addApmAttribute', () => {
+        it ('delegates to APM.addCustomAttribute', () => {
+            const Subclass = defineJobSubclass(AbstractJob);
+            const job      = new Subclass();
+            const key      = TestHelpers.Faker.Text.randomString();
+            const value    = TestHelpers.Faker.Text.randomString();
+
+            job.addApmAttribute(key, value);
+
+            expect(APM.addCustomAttribute).toHaveBeenCalledTimes(1);
+            expect(APM.addCustomAttribute).toHaveBeenCalledWith(key, value);
+        });
+    });
+
+
+    describe('#startApmSegment', () => {
+        it ('delegates to APM.startSegment and returns its result', () => {
+            const Subclass = defineJobSubclass(AbstractJob);
+            const job      = new Subclass();
+            const name     = TestHelpers.Faker.Text.randomString();
+            const sentinel = TestHelpers.Faker.Text.randomString();
+            const handler  = jest.fn(() => sentinel);
+
+            const result = job.startApmSegment(name, true, handler);
+
+            expect(APM.startSegment).toHaveBeenCalledTimes(1);
+            expect(APM.startSegment).toHaveBeenCalledWith(name, true, handler);
+            expect(result).toEqual(sentinel);
+        });
+    });
+
+
+    describe('#logger', () => {
+        it ('returns a child of the constructor-named scope keyed by job id', async () => {
+            const Subclass = defineJobSubclass(AbstractJob);
+            const job      = new Subclass();
+            const id       = TestHelpers.Faker.Text.randomString();
+            await job._run(id, [], jest.fn());
+
+            const scope = logger[Subclass.name];
+            const child = job.logger;
+
+            expect(scope.child).toHaveBeenCalledWith(id);
+            expect(child).toBe(scope.child.mock.results[0].value);
+        });
+    });
+});

package/test/jobQueue/abstractJobComponent.test.js

@@ -0,0 +1,110 @@
+const { AbstractJobComponent } = require('../../lib/jobQueue/abstractJobComponent');
+const   TestHelpers            = require('@vida-global/test-helpers');
+const { snapshotEnv }          = require('../helpers/env');
+
+
+let restoreEnv;
+
+beforeEach(() => {
+    restoreEnv = snapshotEnv([
+        'NODE_ENV',
+        'REDIS_BULL_HOST',
+        'REDIS_BULL_PORT',
+        'REDIS_BULL_PASSWORD',
+    ]);
+});
+
+
+afterEach(() => {
+    restoreEnv();
+});
+
+
+describe('AbstractJobComponent', () => {
+    describe('.fullQueueName', () => {
+        it ('builds a name suffixed with the current NODE_ENV', () => {
+            const queueName = TestHelpers.Faker.Text.randomString();
+            const env       = TestHelpers.Faker.Text.randomString();
+            process.env.NODE_ENV = env;
+
+            expect(AbstractJobComponent.fullQueueName(queueName)).toEqual(`${queueName}-${env}`);
+        });
+
+        it ('reflects changes to NODE_ENV between calls', () => {
+            const queueName = TestHelpers.Faker.Text.randomString();
+            const env1      = TestHelpers.Faker.Text.randomString();
+            const env2      = TestHelpers.Faker.Text.randomString();
+
+            process.env.NODE_ENV = env1;
+            const first  = AbstractJobComponent.fullQueueName(queueName);
+            process.env.NODE_ENV = env2;
+            const second = AbstractJobComponent.fullQueueName(queueName);
+
+            expect(first).toEqual(`${queueName}-${env1}`);
+            expect(second).toEqual(`${queueName}-${env2}`);
+        });
+    });
+
+
+    describe('.env', () => {
+        it ('returns the current NODE_ENV', () => {
+            const env = TestHelpers.Faker.Text.randomString();
+            process.env.NODE_ENV = env;
+
+            expect(AbstractJobComponent.env).toEqual(env);
+        });
+
+        it ('returns undefined when NODE_ENV is not set', () => {
+            delete process.env.NODE_ENV;
+
+            expect(AbstractJobComponent.env).toBeUndefined();
+        });
+    });
+
+
+    describe('#fullQueueName', () => {
+        it ('delegates to the static method using `this.queueName`', () => {
+            const queueName = TestHelpers.Faker.Text.randomString();
+            const env       = TestHelpers.Faker.Text.randomString();
+            process.env.NODE_ENV = env;
+
+            class Concrete extends AbstractJobComponent {
+                get queueName() { return queueName; }
+            }
+            const instance = new Concrete();
+
+            expect(instance.fullQueueName).toEqual(`${queueName}-${env}`);
+        });
+    });
+
+
+    describe('#redisConnectionDetails', () => {
+        it ('returns the connection details from REDIS_BULL_* environment variables', () => {
+            const host     = TestHelpers.Faker.Text.randomString();
+            const port     = String(TestHelpers.Faker.Math.randomNumber(65000));
+            const password = TestHelpers.Faker.Text.randomString();
+            process.env.REDIS_BULL_HOST     = host;
+            process.env.REDIS_BULL_PORT     = port;
+            process.env.REDIS_BULL_PASSWORD = password;
+
+            const instance = new AbstractJobComponent();
+
+            expect(instance.redisConnectionDetails).toEqual({ host, password, port });
+        });
+    });
+
+
+    describe('individual redis env getters', () => {
+        it.each([
+            ['host',     'REDIS_BULL_HOST'],
+            ['port',     'REDIS_BULL_PORT'],
+            ['password', 'REDIS_BULL_PASSWORD'],
+        ])('#%s returns process.env.%s', (getter, envVar) => {
+            const value           = TestHelpers.Faker.Text.randomString();
+            process.env[envVar]   = value;
+            const instance        = new AbstractJobComponent();
+
+            expect(instance[getter]).toEqual(value);
+        });
+    });
+});

package/test/jobQueue/helpers/abstractJob.js

@@ -0,0 +1,26 @@
+const TestHelpers = require('@vida-global/test-helpers');
+
+
+/***************************************************************************************************
+* SUBCLASS FACTORY
+***************************************************************************************************/
+function defineJobSubclass(AbstractJob, { queueName, queueNameFn, run, ...overrides } = {}) {
+    const resolvedName = queueName || TestHelpers.Faker.Text.randomString();
+    const nameFunction = queueNameFn || (() => resolvedName);
+    const Subclass = class extends AbstractJob {
+        static queueName(...jobArgs) { return nameFunction(...jobArgs); }
+        async run(...args) {
+            if (run) return await run(...args);
+        }
+    };
+    for (const [key, value] of Object.entries(overrides)) {
+        Object.defineProperty(Subclass, key, { value });
+    }
+    Subclass.expectedQueueName = resolvedName;
+    return Subclass;
+}
+
+
+module.exports = {
+    defineJobSubclass,
+}

package/test/jobQueue/helpers/apmMock.js

@@ -0,0 +1,20 @@
+/***************************************************************************************************
+* MOCKS
+***************************************************************************************************/
+function buildApmMock() {
+    return {
+        addCustomAttribute:         jest.fn(),
+        recordCustomEvent:          jest.fn(),
+        recordMetric:               jest.fn(),
+        reportError:                jest.fn(),
+        setControllerName:          jest.fn(),
+        setUserId:                  jest.fn(),
+        startBackgroundTransaction: jest.fn((name, group, handler) => handler()),
+        startSegment:               jest.fn((name, record, handler) => handler()),
+    };
+}
+
+
+module.exports = {
+    buildApmMock,
+}

package/test/jobQueue/helpers/bullmqMock.js

@@ -0,0 +1,67 @@
+/***************************************************************************************************
+* MOCKS
+***************************************************************************************************/
+const instances = {
+    queues:  [],
+    workers: [],
+};
+
+
+class MockBullQueue {
+    constructor(name, options) {
+        this.name    = name;
+        this.options = options;
+
+        this.add            = jest.fn();
+        this.close          = jest.fn();
+        this.pause          = jest.fn();
+        this.resume         = jest.fn();
+        this.count          = jest.fn();
+        this.getJobs        = jest.fn();
+        this.getActiveCount = jest.fn();
+        this.getActive      = jest.fn();
+        this.getFailedCount = jest.fn();
+        this.getFailed      = jest.fn();
+        this.clean          = jest.fn();
+        this.drain          = jest.fn();
+        this.getWorkers     = jest.fn();
+        this.on             = jest.fn();
+
+        instances.queues.push(this);
+    }
+}
+
+
+class MockBullWorker {
+    constructor(name, processor, options) {
+        this.name      = name;
+        this.processor = processor;
+        this.options   = options;
+
+        this.run = jest.fn();
+        this.on  = jest.fn();
+
+        instances.workers.push(this);
+    }
+}
+
+
+function reset() {
+    instances.queues.length  = 0;
+    instances.workers.length = 0;
+}
+
+
+function listenerFor(emitter, event) {
+    const call = emitter.on.mock.calls.find(([name]) => name === event);
+    return call ? call[1] : undefined;
+}
+
+
+module.exports = {
+    Queue:  MockBullQueue,
+    Worker: MockBullWorker,
+    instances,
+    reset,
+    listenerFor,
+}

package/test/jobQueue/helpers/env.js

@@ -0,0 +1,29 @@
+const TestHelpers     = require('@vida-global/test-helpers');
+const { snapshotEnv } = require('../../helpers/env');
+
+
+/***************************************************************************************************
+* ENV SETUP
+***************************************************************************************************/
+function setupJobQueueEnv(extraKeysToClear = []) {
+    const restore = snapshotEnv([
+        'NODE_ENV',
+        'REDIS_BULL_HOST',
+        'REDIS_BULL_PORT',
+        'REDIS_BULL_PASSWORD',
+        ...extraKeysToClear,
+    ]);
+    process.env.NODE_ENV            = 'test';
+    process.env.REDIS_BULL_HOST     = TestHelpers.Faker.Text.randomString();
+    process.env.REDIS_BULL_PORT     = String(TestHelpers.Faker.Math.randomNumber(65000));
+    process.env.REDIS_BULL_PASSWORD = TestHelpers.Faker.Text.randomString();
+    for (const key of extraKeysToClear) {
+        delete process.env[key];
+    }
+    return restore;
+}
+
+
+module.exports = {
+    setupJobQueueEnv,
+}

package/test/jobQueue/helpers/fixtureJobs/notAJob.js

@@ -0,0 +1,8 @@
+class NotAJob {
+    run() {}
+}
+
+
+module.exports = {
+    NotAJob,
+}

package/test/jobQueue/helpers/fixtureJobs/testJobA.js

@@ -0,0 +1,14 @@
+const { AbstractJob } = require('../../../../lib/jobQueue/abstractJob');
+
+
+class TestJobA extends AbstractJob {
+    static queueName() { return 'fixture-queue-a'; }
+
+    async run() {
+    }
+}
+
+
+module.exports = {
+    TestJobA,
+}

package/test/jobQueue/helpers/fixtureJobs/testJobB.js

@@ -0,0 +1,14 @@
+const { AbstractJob } = require('../../../../lib/jobQueue/abstractJob');
+
+
+class TestJobB extends AbstractJob {
+    static queueName() { return 'fixture-queue-b'; }
+
+    async run() {
+    }
+}
+
+
+module.exports = {
+    TestJobB,
+}

package/test/jobQueue/helpers/loggerMock.js

@@ -0,0 +1,43 @@
+/***************************************************************************************************
+* MOCKS
+***************************************************************************************************/
+function createLeaf(name) {
+    const leaf = {
+        name,
+        debug:   jest.fn(),
+        info:    jest.fn(),
+        error:   jest.fn(),
+        warn:    jest.fn(),
+        verbose: jest.fn(),
+        silly:   jest.fn(),
+    };
+
+    const children = {};
+    leaf.child = jest.fn((id) => {
+        if (!children[id]) children[id] = createLeaf(`${name}:${id}`);
+        return children[id];
+    });
+
+    return leaf;
+}
+
+
+function buildLoggerMock() {
+    const scopes = {};
+    const root   = createLeaf('root');
+    root.addScope = jest.fn();
+
+    return new Proxy(root, {
+        get(target, prop) {
+            if (typeof prop !== 'string')      return target[prop];
+            if (Object.hasOwn(target, prop))   return target[prop];
+            if (!scopes[prop])                 scopes[prop] = createLeaf(prop);
+            return scopes[prop];
+        }
+    });
+}
+
+
+module.exports = {
+    buildLoggerMock,
+}

package/test/jobQueue/helpers/worker.js

@@ -0,0 +1,38 @@
+const TestHelpers = require('@vida-global/test-helpers');
+const path        = require('path');
+
+
+const FIXTURE_JOBS_DIR = path.join(__dirname, 'fixtureJobs');
+
+
+/***************************************************************************************************
+* WORKER FACTORY
+***************************************************************************************************/
+function buildWorker(Worker, queueName) {
+    class TestWorker extends Worker {
+        get jobDirectories() { return [FIXTURE_JOBS_DIR]; }
+    }
+    return new TestWorker(queueName || TestHelpers.Faker.Text.randomString());
+}
+
+
+/***************************************************************************************************
+* BULL JOB BUILDER
+***************************************************************************************************/
+function buildFakeBullJob(overrides = {}) {
+    return {
+        name:           'TestJobA',
+        data:           { id: TestHelpers.Faker.Text.randomString(), args: [] },
+        updateProgress: jest.fn(),
+        attemptsMade:   0,
+        opts:           { attempts: 3 },
+        ...overrides,
+    };
+}
+
+
+module.exports = {
+    FIXTURE_JOBS_DIR,
+    buildFakeBullJob,
+    buildWorker,
+}