@vida-global/core 2.3.6 → 2.4.1

package/lib/server/README.md

@@ -130,7 +130,38 @@ See [Callbacks](./doc/callbacks.md) — before/after action callbacks and how su
 
 ## Rendering responses
 
-See [Rendering responses](./doc/renderer.md) — the render envelope, status-code helpers, error handling, and Server-Sent Events / streaming.
+See [Rendering responses](./doc/renderer.md) — the render envelope, status-code helpers, binary and file responses, error handling, and Server-Sent Events / streaming.
+
+
+## App dependencies
+
+`AppDependencies` is a registry for the long-lived collaborators an application builds at boot — helper libraries, service objects, queues. Code that runs far from that wiring reaches them by name instead of having them threaded through every call.
+
+```js
+// at boot
+const { AppDependencies } = require('@vida-global/core');
+
+AppDependencies.setDependency('billingHelper', billingHelper);
+AppDependencies.installOn(MyBaseController);
+```
+
+`installOn` exposes every registered name as a getter on that controller class, so controllers read the dependency directly:
+
+```js
+class InvoicesController extends MyBaseController {
+    async getIndex() {
+        return await this.billingHelper.invoicesFor(this.currentUser);
+    }
+}
+```
+
+Anything else reads them off the registry:
+
+```js
+const helper = AppDependencies.get('billingHelper');   // null when nothing is registered
+```
+
+Registration order does not matter — a dependency registered after `installOn` still gets its accessor. A controller that already defines the name keeps its own property. `reset()` clears the registry, which tests need so their doubles do not leak into the next one.
 
 
 ## Documentation

package/lib/server/controllerMixins/renderer.js

@@ -244,6 +244,17 @@ const InstanceMethods = {
     /***********************************************************************************************
     * FILE RENDERING
     ***********************************************************************************************/
+    renderBinary(body, { contentType, filename } = {}) {
+        if (this.rendered)    return;
+        if (this.isStreaming) return;
+
+        this._response.setHeader('Content-Type', contentType);
+        if (filename) this._response.attachment(filename);
+        this._send(body);
+        this.markRendered();
+    },
+
+
     renderFile(filePath, { contentType, cacheControl, maxAge } = {}) {
         if (!filePath) throw new Error('renderFile requires a filePath');
         const resolvedType = contentType || guessContentType(filePath);

package/lib/server/doc/renderer.md

@@ -70,6 +70,29 @@ Don't set `this.statusCode` directly — use the helper that pairs the status wi
 After a render helper runs, the action does not need to return — the response has already been sent.
 
 
+## Binary responses
+
+`render` JSON encodes its body, which corrupts anything that is not text. Use `renderBinary` for a
+body you already hold in memory — a buffer proxied from another service, a generated document.
+
+```js
+async getRecordRecording() {
+    const { body, contentType } = await fetchRecording(sid);
+    this.renderBinary(body, { contentType });
+}
+```
+
+Naming a `filename` sets `Content-Disposition`, so the browser downloads the body instead of
+displaying it:
+
+```js
+this.renderBinary(csv, { contentType: 'text/csv', filename: 'report.csv' });
+```
+
+To send a file from disk rather than from memory, use `renderFile(path, { contentType,
+cacheControl, maxAge })` instead — it streams and guesses the content type from the extension.
+
+
 ## Error handling
 
 ```js

package/package.json

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

package/test/appDependencies/appDependencies.test.js

@@ -0,0 +1,93 @@
+const { AppDependencies } = require('../../lib/appDependencies');
+
+
+class FooController {}
+class BarController {}
+
+
+afterEach(() => AppDependencies.reset());
+
+
+describe('AppDependencies', () => {
+    describe('#get', () => {
+        it ('returns what was registered', () => {
+            const helper = { name: 'helper' };
+
+            AppDependencies.setDependency('myHelper', helper);
+
+            expect(AppDependencies.get('myHelper')).toBe(helper);
+        });
+
+
+        // Null rather than undefined, so a missing dependency reads the same as one registered as
+        // nothing and callers can test it with a single check.
+        it ('returns null for a name nothing registered', () => {
+            expect(AppDependencies.get('nothingHere')).toBeNull();
+        });
+
+
+        it ('replaces a name that is registered twice', () => {
+            AppDependencies.setDependency('myHelper', 'first');
+            AppDependencies.setDependency('myHelper', 'second');
+
+            expect(AppDependencies.get('myHelper')).toBe('second');
+        });
+    });
+
+
+    describe('#reset', () => {
+        it ('forgets everything registered', () => {
+            AppDependencies.setDependency('myHelper', 'something');
+
+            AppDependencies.reset();
+
+            expect(AppDependencies.get('myHelper')).toBeNull();
+        });
+    });
+
+
+    describe('#installOn', () => {
+        it ('exposes what was registered before the install as a getter', () => {
+            AppDependencies.setDependency('myHelper', 'early');
+
+            AppDependencies.installOn(FooController);
+
+            expect(new FooController().myHelper).toBe('early');
+        });
+
+
+        // Wiring order must not matter: a dependency registered after the install still appears.
+        it ('exposes what is registered after the install', () => {
+            AppDependencies.installOn(FooController);
+
+            AppDependencies.setDependency('lateHelper', 'late');
+
+            expect(new FooController().lateHelper).toBe('late');
+        });
+
+
+        it ('reads through, so a later replacement is picked up', () => {
+            AppDependencies.installOn(FooController);
+            AppDependencies.setDependency('myHelper', 'first');
+            const controller = new FooController();
+
+            AppDependencies.setDependency('myHelper', 'second');
+
+            expect(controller.myHelper).toBe('second');
+        });
+
+
+        // A controller that defines the name itself keeps its own.
+        it ('does not overwrite a property the controller already has', () => {
+            Object.defineProperty(BarController.prototype, 'ownProperty', {
+                configurable: true,
+                get() { return 'mine' },
+            });
+
+            AppDependencies.setDependency('ownProperty', 'theirs');
+            AppDependencies.installOn(BarController);
+
+            expect(new BarController().ownProperty).toBe('mine');
+        });
+    });
+});

package/test/http/client.test.js

@@ -109,6 +109,27 @@ describe('HttpClient', () => {
                     expect.objectContaining({ body: JSON.stringify(body) }),
                 );
             });
+
+            it('sends string request bodies without JSON serialization', async () => {
+                const body    = 'firstname=Jane&lastname=Doe';
+                const headers = { 'Content-Type': 'application/x-www-form-urlencoded' };
+
+                await client[methodName](Helpers.apiUrl, { body, headers });
+
+                expect(fetch).toHaveBeenCalledWith(
+                    Helpers.apiUrl,
+                    expect.objectContaining({ body, headers: expect.objectContaining(headers) }),
+                );
+            });
+
+            it('preserves empty string request bodies', async () => {
+                await client[methodName](Helpers.apiUrl, { body: '' });
+
+                expect(fetch).toHaveBeenCalledWith(
+                    Helpers.apiUrl,
+                    expect.objectContaining({ body: '' }),
+                );
+            });
         }
 
         if (behavior.supportsParams) {

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 },