@vida-global/core 2.3.5 → 2.4.0

package/test/jobQueue/abstractJob.test.js

@@ -106,12 +106,14 @@ describe('AbstractJob', () => {
 
 
     describe('.queueSettings', () => {
-        it ('returns default retry settings', () => {
+        it ('returns default retry and history settings', () => {
             const Subclass = defineJobSubclass(AbstractJob);
 
             expect(Subclass.queueSettings()).toEqual({
-                attempts: 3,
-                backoff:  { type: 'exponential', delay: 2000 },
+                attempts:         3,
+                backoff:          { type: 'exponential', delay: 2000 },
+                removeOnComplete: { age: 86400, count: 1000 },
+                removeOnFail:     { age: 604800 },
             });
         });
 
@@ -125,11 +127,34 @@ describe('AbstractJob', () => {
                 retryBackoffDelay,
             });
 
-            expect(Subclass.queueSettings()).toEqual({
+            expect(Subclass.queueSettings()).toMatchObject({
                 attempts: numRetries,
                 backoff:  { type: retryBackoffType, delay: retryBackoffDelay },
             });
         });
+
+        it ('reflects subclass overrides for how much history to keep', () => {
+            const Subclass = defineJobSubclass(AbstractJob, {
+                keepCompleted: true,
+                keepFailed:    50,
+            });
+
+            expect(Subclass.queueSettings()).toMatchObject({
+                removeOnComplete: true,
+                removeOnFail:     50,
+            });
+        });
+    });
+
+
+    describe('history defaults', () => {
+        it ('.keepCompleted bounds by age and count', () => {
+            expect(AbstractJob.keepCompleted).toEqual({ age: 86400, count: 1000 });
+        });
+
+        it ('.keepFailed keeps a week', () => {
+            expect(AbstractJob.keepFailed).toEqual({ age: 604800 });
+        });
     });
 
 
@@ -196,6 +221,40 @@ describe('AbstractJob', () => {
     });
 
 
+    describe('attempt tracking', () => {
+        it ('exposes the attempt the worker handed it', async () => {
+            const Subclass = defineJobSubclass(AbstractJob);
+            const job      = new Subclass();
+
+            await job._run('id', [], jest.fn(), { attempt: 2, maxAttempts: 3 });
+
+            expect(job.attempt).toEqual(2);
+            expect(job.maxAttempts).toEqual(3);
+            expect(job.isFinalAttempt).toBe(false);
+        });
+
+        it ('is on its final attempt once the attempts are spent', async () => {
+            const Subclass = defineJobSubclass(AbstractJob);
+            const job      = new Subclass();
+
+            await job._run('id', [], jest.fn(), { attempt: 3, maxAttempts: 3 });
+
+            expect(job.isFinalAttempt).toBe(true);
+        });
+
+        it ('reads as a single final attempt when the worker said nothing', async () => {
+            const Subclass = defineJobSubclass(AbstractJob);
+            const job      = new Subclass();
+
+            await job._run('id', [], jest.fn());
+
+            expect(job.attempt).toEqual(1);
+            expect(job.maxAttempts).toEqual(1);
+            expect(job.isFinalAttempt).toBe(true);
+        });
+    });
+
+
     describe('#updateProgress', () => {
         it ('forwards all arguments to the stored callback', async () => {
             const Subclass = defineJobSubclass(AbstractJob);
@@ -269,7 +328,7 @@ describe('AbstractJob', () => {
             const id       = TestHelpers.Faker.Text.randomString();
             await job._run(id, [], jest.fn());
 
-            const scope = job.loggerLibrary[Subclass.name];
+            const scope = job.loggerLibrary.scope(Subclass.name);
             const child = job.logger;
 
             expect(scope.child).toHaveBeenCalledWith(id);

package/test/jobQueue/helpers/bullmqMock.js

@@ -12,20 +12,22 @@ class MockBullQueue {
         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();
+        this.add                     = jest.fn();
+        this.close                   = jest.fn();
+        this.pause                   = jest.fn();
+        this.resume                  = jest.fn();
+        this.getJobCounts            = jest.fn();
+        this.getJobs                 = jest.fn();
+        this.getActive               = jest.fn();
+        this.getFailed               = jest.fn();
+        this.getJob                  = jest.fn();
+        this.clean                   = jest.fn();
+        this.drain                   = jest.fn();
+        this.getWorkers              = jest.fn();
+        this.setGlobalConcurrency    = jest.fn();
+        this.getGlobalConcurrency    = jest.fn();
+        this.removeGlobalConcurrency = jest.fn();
+        this.on                      = jest.fn();
 
         instances.queues.push(this);
     }
@@ -38,8 +40,9 @@ class MockBullWorker {
         this.processor = processor;
         this.options   = options;
 
-        this.run = jest.fn();
-        this.on  = jest.fn();
+        this.run   = jest.fn();
+        this.close = jest.fn();
+        this.on    = jest.fn();
 
         instances.workers.push(this);
     }

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

@@ -0,0 +1,18 @@
+const { AbstractJob } = require('../../../../lib/jobQueue/abstractJob');
+
+
+// Opts in as the fallback for one specific queue, which is what lets a worker consume a payload
+// whose name matches no registered job — the shape bull writes for an unnamed job.
+class DefaultJobForBeta extends AbstractJob {
+    static defaultFor = 'beta';
+
+    static queueName() { return 'beta'; }
+
+    async run() {
+    }
+}
+
+
+module.exports = {
+    DefaultJobForBeta,
+}

package/test/jobQueue/helpers/loggerMock.js

@@ -22,17 +22,28 @@ function createLeaf(name) {
 }
 
 
+// Registration answers to both spellings, as the real Logger does. An unregistered name only
+// resolves if it is lowercase — a double that invented a scope for any spelling would hide the bug
+// where production code indexes with a class name and silently gets undefined.
 function buildLoggerMock() {
     const scopes = {};
     const root   = createLeaf('root');
-    root.addScope = jest.fn();
+
+    const resolveScope = (name) => {
+        const key = `${name}`.toLowerCase();
+        return scopes[name] = scopes[key] ||= createLeaf(key);
+    };
+
+    root.addScope = jest.fn(resolveScope);
+    root.scope    = jest.fn(resolveScope);
 
     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];
+            if (typeof prop !== 'string')    return target[prop];
+            if (Object.hasOwn(target, prop)) return target[prop];
+            if (scopes[prop])                return scopes[prop];
+            if (prop !== prop.toLowerCase()) return undefined;
+            return resolveScope(prop);
         }
     });
 }

package/test/jobQueue/helpers/queue.js

@@ -1,19 +1,17 @@
 /***************************************************************************************************
 * QUEUE FACTORY
 * bullmqMock/loggerMock are required lazily so the mock instances align with whatever the test
-* re-requires after jest.resetModules(). MockQueue injects the BullMQ, crypto, and logger seams.
+* re-requires after jest.resetModules(). MockQueue injects the BullMQ and logger seams.
 ***************************************************************************************************/
 function buildQueue(queueName) {
     const { Queue }           = require('../../../lib/jobQueue/queue');
     const bullmqMock          = require('./bullmqMock');
     const { buildLoggerMock } = require('./loggerMock');
 
-    const loggerMock  = buildLoggerMock();
-    const idGenerator = jest.fn();
+    const loggerMock = buildLoggerMock();
 
     class MockQueue extends Queue {
         get queueClass()    { return bullmqMock.Queue; }
-        get idGenerator()   { return idGenerator; }
         get loggerLibrary() { return loggerMock; }
     }
 

package/test/jobQueue/helpers/worker.js

@@ -10,22 +10,28 @@ const FIXTURE_JOBS_DIR = path.join(__dirname, 'fixtureJobs');
 * bullmqMock/loggerMock/apmMock are required lazily so the mock instances align with whatever the
 * test re-requires after jest.resetModules() (used to reset the worker's module-level registeredJobs).
 ***************************************************************************************************/
-function buildWorker(Worker, queueName) {
+function buildWorker(Worker, queueName, options) {
     const bullmqMock          = require('./bullmqMock');
     const { buildLoggerMock } = require('./loggerMock');
     const { buildApmMock }    = require('./apmMock');
 
     const loggerMock = buildLoggerMock();
     const apmMock    = buildApmMock();
+    // listen() applies the queue limits, which would otherwise reach a real BullMQ queue.
+    const queueMock  = {
+        setMaximumConcurrency:    jest.fn(),
+        removeMaximumConcurrency: jest.fn(),
+    };
 
     class TestWorker extends Worker {
         get jobDirectories() { return [FIXTURE_JOBS_DIR]; }
         get workerClass()    { return bullmqMock.Worker; }
         get loggerLibrary()  { return loggerMock; }
         get apm()            { return apmMock; }
+        get queue()          { return queueMock; }
     }
 
-    return new TestWorker(queueName || TestHelpers.Faker.Text.randomString());
+    return new TestWorker(queueName || TestHelpers.Faker.Text.randomString(), options);
 }
 
 
@@ -35,7 +41,8 @@ function buildWorker(Worker, queueName) {
 function buildFakeBullJob(overrides = {}) {
     return {
         name:           'TestJobA',
-        data:           { id: TestHelpers.Faker.Text.randomString(), args: [] },
+        id:             TestHelpers.Faker.Text.randomString(),
+        data:           { args: [] },
         updateProgress: jest.fn(),
         attemptsMade:   0,
         opts:           { attempts: 3 },

package/test/jobQueue/queue.test.js

@@ -110,7 +110,7 @@ describe('Queue', () => {
         });
 
         it ('constructs the BullMQ queue with fullQueueName and connection options on first use', async () => {
-            await queue.numQueuedJobs();
+            await queue.getJobCounts();
 
             expect(bullmqMock.instances.queues).toHaveLength(1);
             const instance = bullmqMock.instances.queues[0];
@@ -119,15 +119,15 @@ describe('Queue', () => {
         });
 
         it ('reuses the same BullMQ queue across multiple method calls', async () => {
-            await queue.numQueuedJobs();
-            await queue.numActiveJobs();
+            await queue.getJobCounts();
+            await queue.pause();
             await queue.close();
 
             expect(bullmqMock.instances.queues).toHaveLength(1);
         });
 
         it ('registers an error handler on the BullMQ queue', async () => {
-            await queue.numQueuedJobs();
+            await queue.getJobCounts();
 
             const instance = bullmqMock.instances.queues[0];
             expect(instance.on).toHaveBeenCalledWith('error', expect.any(Function));
@@ -136,9 +136,7 @@ describe('Queue', () => {
 
 
     describe('#queueJob', () => {
-        it ('adds the job to the BullMQ queue with a generated UUID, args, and settings', async () => {
-            const id       = TestHelpers.Faker.Text.randomString();
-            queue.idGenerator.mockReturnValue(id);
+        it ('adds the job to the BullMQ queue with its args and settings', async () => {
             const args     = [TestHelpers.Faker.Text.randomString(), TestHelpers.Faker.Math.randomNumber()];
             const settings = { attempts: TestHelpers.Faker.Math.randomNumber(10) };
             const jobClass = { name: TestHelpers.Faker.Text.randomString() };
@@ -147,7 +145,7 @@ describe('Queue', () => {
 
             const instance = bullmqMock.instances.queues[0];
             expect(instance.add).toHaveBeenCalledTimes(1);
-            expect(instance.add).toHaveBeenCalledWith(jobClass.name, { id, args }, settings);
+            expect(instance.add).toHaveBeenCalledWith(jobClass.name, { args }, settings);
         });
     });
 
@@ -166,26 +164,20 @@ describe('Queue', () => {
     });
 
 
-    describe('count-style queries', () => {
-        it.each([
-            ['numQueuedJobs', 'count'],
-            ['numActiveJobs', 'getActiveCount'],
-            ['numFailedJobs', 'getFailedCount'],
-        ])('#%s delegates to bullmq queue.%s and returns its value', async (method, bullMethod) => {
-            const expectedCount = TestHelpers.Faker.Math.randomNumber();
-            const queueInstance = (() => { queue[method](); return bullmqMock.instances.queues[0]; })();
-            queueInstance[bullMethod].mockResolvedValue(expectedCount);
+    describe('#getJobCounts', () => {
+        it ('returns what bullmq reports', async () => {
+            const counts        = { waiting: 1, active: 2, completed: 3, failed: 4, delayed: 5, paused: 6 };
+            const queueInstance = (() => { queue.getJobCounts(); return bullmqMock.instances.queues[0]; })();
+            queueInstance.getJobCounts.mockResolvedValue(counts);
 
-            const result = await queue[method]();
-
-            expect(result).toEqual(expectedCount);
+            await expect(queue.getJobCounts()).resolves.toEqual(counts);
         });
     });
 
 
     describe('#numWorkers', () => {
         it ('returns the length of bullmq queue.getWorkers()', async () => {
-            await queue.numQueuedJobs();
+            await queue.getJobCounts();
             const instance = bullmqMock.instances.queues[0];
             const workers  = Array.from({ length: TestHelpers.Faker.Math.randomNumber(10) }, () => ({}));
             instance.getWorkers.mockResolvedValue(workers);
@@ -195,22 +187,29 @@ describe('Queue', () => {
     });
 
 
-    describe('clear methods', () => {
-        it ('#clearFailedJobs calls bullmq clean(0, null, "failed")', async () => {
-            await queue.clearFailedJobs();
+    describe('#clean', () => {
+        it ('passes the grace period, limit and type through in bullmq order', async () => {
+            const grace = TestHelpers.Faker.Math.randomNumber(100000);
+            const limit = TestHelpers.Faker.Math.randomNumber(100);
+
+            await queue.clean(grace, limit, 'failed');
 
             const instance = bullmqMock.instances.queues[0];
-            expect(instance.clean).toHaveBeenCalledWith(0, null, 'failed');
+            expect(instance.clean).toHaveBeenCalledWith(grace, limit, 'failed');
         });
 
-        it ('#clearCompletedJobs calls bullmq clean(0, null, "completed")', async () => {
-            await queue.clearCompletedJobs();
+        it ('returns the jobs bullmq removed', async () => {
+            const removed       = [TestHelpers.Faker.Text.randomString()];
+            const queueInstance = (() => { queue.clean(0, 1, 'failed'); return bullmqMock.instances.queues[0]; })();
+            queueInstance.clean.mockResolvedValue(removed);
 
-            const instance = bullmqMock.instances.queues[0];
-            expect(instance.clean).toHaveBeenCalledWith(0, null, 'completed');
+            await expect(queue.clean(0, 1, 'failed')).resolves.toEqual(removed);
         });
+    });
 
-        it ('#clearQueuedJobs calls bullmq drain()', async () => {
+
+    describe('#clearQueuedJobs', () => {
+        it ('calls bullmq drain()', async () => {
             await queue.clearQueuedJobs();
 
             const instance = bullmqMock.instances.queues[0];
@@ -219,6 +218,33 @@ describe('Queue', () => {
     });
 
 
+    describe('maximum concurrency', () => {
+        it ('sets the queue maximum', async () => {
+            const maximum = TestHelpers.Faker.Math.randomNumber(20);
+
+            await queue.setMaximumConcurrency(maximum);
+
+            const instance = bullmqMock.instances.queues[0];
+            expect(instance.setGlobalConcurrency).toHaveBeenCalledWith(maximum);
+        });
+
+        it ('reads the queue maximum back', async () => {
+            const maximum       = TestHelpers.Faker.Math.randomNumber(20);
+            const queueInstance = (() => { queue.maximumConcurrency(); return bullmqMock.instances.queues[0]; })();
+            queueInstance.getGlobalConcurrency.mockResolvedValue(maximum);
+
+            await expect(queue.maximumConcurrency()).resolves.toEqual(maximum);
+        });
+
+        it ('removes the queue maximum', async () => {
+            await queue.removeMaximumConcurrency();
+
+            const instance = bullmqMock.instances.queues[0];
+            expect(instance.removeGlobalConcurrency).toHaveBeenCalled();
+        });
+    });
+
+
     describe('job-list queries', () => {
         function buildBullJob(overrides = {}) {
             return {
@@ -251,7 +277,7 @@ describe('Queue', () => {
         it ('#getQueuedJobs maps getJobs(["paused","wait","prioritized","delayed"]) to formatted shape', async () => {
             const bullJob1 = buildBullJob();
             const bullJob2 = buildBullJob();
-            await queue.numQueuedJobs();
+            await queue.getJobCounts();
             const instance = bullmqMock.instances.queues[0];
             instance.getJobs.mockResolvedValue([bullJob1, bullJob2]);
 
@@ -263,7 +289,7 @@ describe('Queue', () => {
 
         it ('#getActiveJobs maps getActive() to formatted shape', async () => {
             const bullJob = buildBullJob();
-            await queue.numQueuedJobs();
+            await queue.getJobCounts();
             const instance = bullmqMock.instances.queues[0];
             instance.getActive.mockResolvedValue([bullJob]);
 
@@ -274,7 +300,7 @@ describe('Queue', () => {
 
         it ('#getFailedJobs maps getFailed() to formatted shape', async () => {
             const bullJob = buildBullJob();
-            await queue.numQueuedJobs();
+            await queue.getJobCounts();
             const instance = bullmqMock.instances.queues[0];
             instance.getFailed.mockResolvedValue([bullJob]);
 
@@ -282,12 +308,32 @@ describe('Queue', () => {
 
             expect(result).toEqual([expectedShape(bullJob)]);
         });
+
+        // The way a single failed job gets fetched for inspection or replay.
+        it ('#getJob maps one job by id to the formatted shape', async () => {
+            const bullJob = buildBullJob();
+            await queue.getJobCounts();
+            const instance = bullmqMock.instances.queues[0];
+            instance.getJob.mockResolvedValue(bullJob);
+
+            const result = await queue.getJob(bullJob.id);
+
+            expect(instance.getJob).toHaveBeenCalledWith(bullJob.id);
+            expect(result).toEqual(expectedShape(bullJob));
+        });
+
+        it ('#getJob returns null when there is no such job', async () => {
+            await queue.getJobCounts();
+            bullmqMock.instances.queues[0].getJob.mockResolvedValue(undefined);
+
+            await expect(queue.getJob('nope')).resolves.toBeNull();
+        });
     });
 
 
     describe('error handler', () => {
         it ('forwards arguments from the bullmq error event to logger.error', async () => {
-            await queue.numQueuedJobs();
+            await queue.getJobCounts();
             const instance      = bullmqMock.instances.queues[0];
             const errorListener = bullmqMock.listenerFor(instance, 'error');
             const err           = new Error(TestHelpers.Faker.Text.randomString());