@vida-global/core 1.4.4 → 1.4.6

package/test/logger/serverMiddleware.test.js

@@ -0,0 +1,73 @@
+jest.mock('express-winston', () => {
+    return {
+        logger: jest.fn(() => jest.fn()) // returns a noop middleware
+    };
+});
+
+const expressWinston = require('express-winston');
+
+// Loading the module triggers expressWinston.logger(options) — capturing options gives us
+// access to the otherwise-unexported msgFormatter
+require('../../lib/logger/serverMiddleware');
+
+const options       = expressWinston.logger.mock.calls[0][0];
+const msgFormatter  = options.msg;
+
+
+describe('logger/serverMiddleware', () => {
+    describe('msgFormatter', () => {
+        const baseRes = (overrides = {}) => ({
+            statusCode: 200,
+            _header:    'HTTP/1.1 200 OK\nX-Response-Time: 12ms\nContent-Type: application/json',
+            ...overrides
+        });
+
+        const baseReq = (overrides = {}) => ({
+            method: 'GET',
+            url:    '/api/things',
+            ip:     '127.0.0.1',
+            ...overrides
+        });
+
+        it ('uses Controller#action when req.controller is set', () => {
+            class FooController {}
+            const req = baseReq({ controller: new FooController(), action: 'getIndex' });
+            const res = baseRes();
+            const msg = msgFormatter(req, res);
+            expect(msg).toContain('FooController#getIndex');
+            expect(msg).toContain('req: GET /api/things for 127.0.0.1');
+            // The header parser splits on /:(.*)/, preserving the space after the colon —
+            // hence "responseTime= 12ms" rather than "responseTime=12ms".
+            expect(msg).toContain('res: statusCode=200 responseTime= 12ms');
+        });
+
+        it ('uses "request completed" when no controller and statusCode < 500', () => {
+            const msg = msgFormatter(baseReq(), baseRes({ statusCode: 200 }));
+            expect(msg).toContain('request completed');
+        });
+
+        it ('uses "request errored" when no controller and statusCode >= 500', () => {
+            const msg = msgFormatter(baseReq(), baseRes({ statusCode: 503 }));
+            expect(msg).toContain('request errored');
+        });
+
+        it ('strips the query string from the request URL', () => {
+            const req = baseReq({ url: '/api/things?limit=10&q=foo' });
+            const msg = msgFormatter(req, baseRes());
+            expect(msg).toContain('req: GET /api/things for 127.0.0.1');
+            expect(msg).not.toContain('limit=10');
+        });
+
+        it ('appends the error stack when res.error is present', () => {
+            const err = new Error('boom');
+            err.stack = 'Error: boom\n    at somewhere';
+            const msg = msgFormatter(baseReq(), baseRes({ error: err }));
+            expect(msg).toContain('Error: boom\n    at somewhere');
+        });
+
+        it ('does not append a stack when there is no res.error', () => {
+            const msg = msgFormatter(baseReq(), baseRes());
+            expect(msg).not.toContain('Error:');
+        });
+    });
+});

package/test/server/apiDocsGenerator.test.js

@@ -0,0 +1,38 @@
+const { ApiDocsGenerator } = require('../../lib/server/apiDocsGenerator');
+
+
+describe('ApiDocsGenerator', () => {
+    let generator;
+
+    beforeEach(() => {
+        generator = new ApiDocsGenerator({ controllerDirectories: [] });
+    });
+
+
+    describe('#formatEndpoint', () => {
+        it ('replaces a single :param with {param}', () => {
+            expect(generator.formatEndpoint({ path: '/users/:id' })).toEqual('/users/{id}');
+        });
+
+        it ('replaces multiple :params with {params}', () => {
+            expect(generator.formatEndpoint({ path: '/users/:userId/posts/:postId' }))
+                .toEqual('/users/{userId}/posts/{postId}');
+        });
+
+        it ('returns the path unchanged when there are no params', () => {
+            expect(generator.formatEndpoint({ path: '/users' })).toEqual('/users');
+        });
+
+        it ('handles a trailing :param', () => {
+            expect(generator.formatEndpoint({ path: '/foo/bar/:baz' })).toEqual('/foo/bar/{baz}');
+        });
+
+        it ('handles an empty path', () => {
+            expect(generator.formatEndpoint({ path: '' })).toEqual('');
+        });
+
+        it ('only replaces up to the next slash', () => {
+            expect(generator.formatEndpoint({ path: '/a/:x/b/:y' })).toEqual('/a/{x}/b/{y}');
+        });
+    });
+});

package/test/server/server.test.js

@@ -5,17 +5,39 @@ const { Request }       = require('jest-express/lib/request');
 const { Response }      = require('jest-express/lib/response');
 const { TestServer }    = require('./helpers/server');
 const { VidaServer }    = require('../../lib/server');
+const   express         = require('express');
+const   IoServer        = require('socket.io');
+const { Server: HttpServer } = require('http');
+
+
+const lastApp = () => express.__instances[express.__instances.length - 1];
 
 
 jest.mock('express', () => {
-    const   express    = require('jest-express');
-    const { Response } = require('jest-express/lib/response');
+    const   jestExpress = require('jest-express');
+    const { Response }  = require('jest-express/lib/response');
 
     // missing functions in mock express
     Response.prototype.on = jest.fn();
-    express.raw           = jest.fn();
 
-    return express;
+    // Wrap the factory so tests can inspect the most recently created Express app.
+    const instances = [];
+    const wrapped   = (...args) => {
+        const app = jestExpress(...args);
+        instances.push(app);
+        return app;
+    };
+    Object.assign(wrapped, jestExpress);
+    wrapped.raw         = jest.fn();
+    wrapped.__instances = instances;
+
+    return wrapped;
+});
+
+jest.mock('socket.io', () => jest.fn());
+jest.mock('http', () => {
+    const actual = jest.requireActual('http');
+    return { ...actual, Server: jest.fn() };
 });
 
 
@@ -187,4 +209,164 @@ describe('VidaServer', () => {
             expect(afterSpy5).toHaveBeenCalledTimes(0);
         });
     });
+
+
+    describe('VidaServer#listen', () => {
+        it ('starts the http server on the configured host/port and invokes the callback', async () => {
+            const fakeHttpServer = { listen: jest.fn((port, host, cb) => cb()) };
+            HttpServer.mockReturnValueOnce(fakeHttpServer);
+
+            const server   = new TestServer({ port: 4321, host: '0.0.0.0' });
+            const callback = jest.fn();
+            jest.spyOn(server, 'registerControllers').mockResolvedValue();
+
+            await server.listen(callback);
+            expect(fakeHttpServer.listen).toHaveBeenCalledWith(4321, '0.0.0.0', expect.any(Function));
+            expect(callback).toHaveBeenCalledTimes(1);
+        });
+
+        it ('does not require a callback', async () => {
+            const fakeHttpServer = { listen: jest.fn((port, host, cb) => cb()) };
+            HttpServer.mockReturnValueOnce(fakeHttpServer);
+
+            const server = new TestServer({ port: 5000, host: 'localhost' });
+            jest.spyOn(server, 'registerControllers').mockResolvedValue();
+
+            await expect(server.listen()).resolves.toBeUndefined();
+            expect(fakeHttpServer.listen).toHaveBeenCalledTimes(1);
+        });
+    });
+
+
+    describe('VidaServer#corsOrigins', () => {
+        it ('defaults to an empty array', () => {
+            expect(new TestServer().corsOrigins).toEqual([]);
+        });
+    });
+
+
+    describe('VidaServer#viewsDirectory / staticFilesDirectory', () => {
+        it ('returns absolute paths under cwd', () => {
+            const server = new TestServer();
+            expect(server.viewsDirectory).toEqual(`${process.cwd()}/views`);
+            expect(server.staticFilesDirectory).toEqual(`${process.cwd()}/static`);
+        });
+    });
+
+
+    describe('VidaServer#controllerDirectories (default)', () => {
+        it ('returns cwd/controllers when not overridden', () => {
+            const server = new VidaServer();
+            expect(server.controllerDirectories).toEqual([`${process.cwd()}/controllers`]);
+        });
+    });
+
+
+    describe('VidaServer#connectionAbortedMiddleware', () => {
+        it ('short-circuits with a 400 when err.code === ECONNABORTED', async () => {
+            const server     = new TestServer();
+            const middleware = server.connectionAbortedMiddleware;
+            const status     = jest.fn().mockReturnValue({ end: jest.fn() });
+            const res        = { status };
+            const next       = jest.fn();
+
+            await middleware({ code: 'ECONNABORTED' }, {}, res, next);
+            expect(status).toHaveBeenCalledWith(400);
+            expect(next).not.toHaveBeenCalled();
+        });
+
+        it ('calls next() for other errors', async () => {
+            const server     = new TestServer();
+            const middleware = server.connectionAbortedMiddleware;
+            const next       = jest.fn();
+
+            await middleware(new Error('something else'), {}, {}, next);
+            expect(next).toHaveBeenCalledTimes(1);
+        });
+
+        it ('calls next() when there is no error', async () => {
+            const server     = new TestServer();
+            const middleware = server.connectionAbortedMiddleware;
+            const next       = jest.fn();
+
+            await middleware(null, {}, {}, next);
+            expect(next).toHaveBeenCalledTimes(1);
+        });
+    });
+
+
+    describe('VidaServer HTTP verb wrappers', () => {
+        const verbs = ['get', 'post', 'put', 'delete', 'patch', 'head'];
+
+        it.each(verbs)('_%s delegates to express app.%s', (verb) => {
+            const server  = new TestServer();
+            const handler = jest.fn();
+            const app     = lastApp();
+            app[verb].mockClear();
+
+            server[`_${verb}`]('/path', handler);
+            expect(app[verb]).toHaveBeenCalledWith('/path', handler);
+        });
+    });
+
+
+    describe('VidaServer deprecated routing methods', () => {
+        const verbs = ['get', 'post', 'put', 'patch', 'head', 'delete'];
+
+        it.each(verbs)('%s emits a DeprecationWarning and delegates to express app.%s', (verb) => {
+            const emitSpy = jest.spyOn(process, 'emitWarning').mockImplementation(() => {});
+            try {
+                const server  = new TestServer();
+                const handler = jest.fn();
+                const app     = lastApp();
+                app[verb].mockClear();
+
+                server[verb]('/path', handler);
+                expect(emitSpy).toHaveBeenCalledWith(expect.stringContaining(`\`${verb}\` is deprecated`), 'DeprecationWarning');
+                expect(app[verb]).toHaveBeenCalledWith('/path', handler);
+            } finally {
+                emitSpy.mockRestore();
+            }
+        });
+
+        it ('only emits the warning once per method name', () => {
+            const emitSpy = jest.spyOn(process, 'emitWarning').mockImplementation(() => {});
+            try {
+                const server = new TestServer();
+                server.post('/a', jest.fn());
+                server.post('/b', jest.fn());
+                server.post('/c', jest.fn());
+
+                const postWarnings = emitSpy.mock.calls.filter(c => c[0].includes('`post`'));
+                expect(postWarnings).toHaveLength(1);
+            } finally {
+                emitSpy.mockRestore();
+            }
+        });
+    });
+
+
+    describe('VidaServer web socket helpers', () => {
+        let fakeIo;
+        let server;
+
+        beforeEach(() => {
+            fakeIo = { to: jest.fn(() => fakeIo), emit: jest.fn(), on: jest.fn() };
+            IoServer.mockReturnValueOnce(fakeIo);
+            HttpServer.mockReturnValueOnce({ listen: jest.fn() });
+            server = new TestServer();
+        });
+
+        it ('emitWebSocketEvent forwards channel/event/data to the io server', () => {
+            server.emitWebSocketEvent('chan', 'evt', { hello: 'world' });
+            expect(fakeIo.to).toHaveBeenCalledWith('chan');
+            expect(fakeIo.emit).toHaveBeenCalledWith('evt', { hello: 'world' });
+        });
+
+        it ('addWebSocketEventHandler registers the handler on the io server', () => {
+            const handler = jest.fn();
+            server.addWebSocketEventHandler('connection', handler);
+            expect(fakeIo.on).toHaveBeenCalledWith('connection', handler);
+        });
+    });
 });

package/test/server/serverController.test.js

@@ -5,7 +5,11 @@ const   Errors                 = require('../../lib/server/errors');
 const { logger }               = require('../../lib/logger');
 const { randomPayload }        = require('./helpers/serverController');
 const   TestHelpers            = require('@vida-global/test-helpers');
-const { VidaServerController } = require('../../lib/server');
+const {
+    NoActiveStreamError,
+    StreamInProgressError,
+    VidaServerController
+}                              = require('../../lib/server/serverController');
 
 describe('VidaServerController', () => {
     describe('.actionNames', () => {
@@ -444,6 +448,35 @@ describe('VidaServerController', () => {
     });
 
 
+    describe('.validateIsBoolean', () => {
+        const controller = new FooController({}, {});
+        it ('returns undefined when passed a matching boolean', () => {
+            const result1 = controller.validateIsBoolean(true, true);
+            const result2 = controller.validateIsBoolean(false, false);
+            expect(result1).toBe(undefined);
+            expect(result2).toBe(undefined);
+        });
+
+        it ('returns an error when passed an non matching boolean', () => {
+            const result1 = controller.validateIsBoolean(true, false);
+            const result2 = controller.validateIsBoolean(false, true);
+            expect(result1).toBe('must be false');
+            expect(result2).toBe('must be true');
+        });
+
+        it ('returns an error when passed an non boolean', () => {
+            const result1 = controller.validateIsBoolean('', false);
+            const result2 = controller.validateIsBoolean(0, false);
+            const result3 = controller.validateIsBoolean('foo', true);
+            const result4 = controller.validateIsBoolean(1, true);
+            expect(result1).toBe('must be false');
+            expect(result2).toBe('must be false');
+            expect(result3).toBe('must be true');
+            expect(result4).toBe('must be true');
+        });
+    });
+
+
     describe('.validateFunction', () => {
         const controller   = new FooController({}, {});
         const correctValue = Math.random();
@@ -494,8 +527,6 @@ describe('VidaServerController', () => {
             const body       = {[key]: value};
             const message    = TestHelpers.Faker.Text.randomString();
 
-          if (!Errors[errorClsName]) console.log(errorClsName);
-
             const error      = new Errors[errorClsName](message, body);
             if (handlerName == 'renderErrors') error.errors = randomPayload();
 
@@ -708,8 +739,17 @@ describe('VidaServerController', () => {
 
 
         describe('#logger', () => {
-            it ('uses the standard logger', () => {
-                expect(controller.logger).toBe(logger);
+            it ('uses the a logger with http scope', () => {
+                expect(controller.logger.scope).toBe('http');
+            });
+
+            it ('uses the request id', () => {
+                const id1         = TestHelpers.Faker.Text.randomString();
+                const id2         = TestHelpers.Faker.Text.randomString();
+                const controller1 = new FooController({ id: id1 }, response);
+                const controller2 = new FooController({ id: id2 }, response);
+                expect(controller1.logger.id).toBe(id1);
+                expect(controller2.logger.id).toBe(id2);
             });
         });
 
@@ -762,4 +802,196 @@ describe('VidaServerController', () => {
 
     describe('Request Properties', () => {
     });
+
+
+    describe('#statusText', () => {
+        const cases = [
+            [200, 'ok'],
+            [201, 'created'],
+            [202, 'accepted'],
+            [204, 'no content'],
+            [301, 'moved permanently'],
+            [302, 'found'],
+            [304, 'not modified'],
+            [307, 'temporary redirect'],
+            [308, 'permanent redirect'],
+            [400, 'bad request'],
+            [401, 'unauthorized'],
+            [402, 'payment required'],
+            [403, 'forbidden'],
+            [404, 'not found'],
+            [405, 'method not allowed'],
+            [408, 'request timeout'],
+            [409, 'conflict'],
+            [410, 'gone'],
+            [413, 'content too large'],
+            [415, 'unsupported media type'],
+            [422, 'unprocessable content'],
+            [423, 'locked'],
+            [429, 'too many requests'],
+            [500, 'server error'],
+            [501, 'not implemented'],
+            [502, 'bad gateway'],
+            [503, 'service unavailable'],
+            [504, 'gateway timeout'],
+        ];
+
+        it.each(cases)('returns "%s" text for status %s', (statusCode, expected) => {
+            const controller = new FooController({}, { statusCode });
+            expect(controller.statusText).toEqual(expected);
+        });
+
+        it ('returns undefined for an unmapped status code', () => {
+            const controller = new FooController({}, { statusCode: 418 });
+            expect(controller.statusText).toBeUndefined();
+        });
+    });
+
+
+    describe('#streamSseResponse', () => {
+        let controller;
+        let response;
+        let request;
+        let setHeaderSpy;
+
+        beforeEach(() => {
+            request          = { on: jest.fn(), off: jest.fn() };
+            response         = {
+                setHeader:     jest.fn(),
+                flushHeaders:  jest.fn(),
+                write:         jest.fn(),
+                end:           jest.fn(),
+                writableEnded: false
+            };
+            controller       = new FooController(request, response);
+            setHeaderSpy     = response.setHeader;
+        });
+
+        it ('sets SSE headers, flushes them, and marks rendered before invoking handler', async () => {
+            const handler = jest.fn(async function () {
+                expect(this).toBe(controller);
+                expect(controller.rendered).toBe(true);
+                expect(setHeaderSpy).toHaveBeenCalledWith('Content-Type',      'text/event-stream; charset=utf-8');
+                expect(setHeaderSpy).toHaveBeenCalledWith('Cache-Control',     'no-cache');
+                expect(setHeaderSpy).toHaveBeenCalledWith('Connection',        'keep-alive');
+                expect(setHeaderSpy).toHaveBeenCalledWith('X-Accel-Buffering', 'no');
+                expect(response.flushHeaders).toHaveBeenCalledTimes(1);
+                expect(controller.statusCode).toBe(200);
+            });
+            await controller.streamSseResponse(handler, jest.fn());
+            expect(handler).toHaveBeenCalledTimes(1);
+        });
+
+        it ('writes [DONE] and ends the response in the finally block', async () => {
+            await controller.streamSseResponse(jest.fn(), jest.fn());
+            expect(response.write).toHaveBeenLastCalledWith('data: [DONE]\n\n');
+            expect(response.end).toHaveBeenCalledTimes(1);
+        });
+
+        it ('throws StreamInProgressError when called while already streaming', async () => {
+            await controller.streamSseResponse(async () => {
+                await expect(controller.streamSseResponse(jest.fn(), jest.fn()))
+                    .rejects.toBeInstanceOf(StreamInProgressError);
+            }, jest.fn());
+        });
+
+        it ('invokes errorHandler and rethrows when handler throws', async () => {
+            const err          = new Error('boom');
+            const handler      = jest.fn(async () => { throw err; });
+            const errorHandler = jest.fn();
+            await expect(controller.streamSseResponse(handler, errorHandler)).rejects.toThrow('boom');
+            expect(errorHandler).toHaveBeenCalledWith(err);
+        });
+
+        it ('still ends the response when handler throws', async () => {
+            const errorHandler = jest.fn();
+            await expect(controller.streamSseResponse(
+                async () => { throw new Error('boom'); },
+                errorHandler
+            )).rejects.toThrow();
+            expect(response.end).toHaveBeenCalledTimes(1);
+        });
+
+        it ('wires close listener to abortController when one is provided', async () => {
+            const abortController = { abort: jest.fn() };
+            await controller.streamSseResponse(jest.fn(), jest.fn(), abortController);
+            expect(request.on).toHaveBeenCalledWith('close', expect.any(Function));
+            expect(request.off).toHaveBeenCalledWith('close', expect.any(Function));
+            // The handler registered on 'close' should call abort.
+            const closeHandler = request.on.mock.calls.find(c => c[0] === 'close')[1];
+            closeHandler();
+            expect(abortController.abort).toHaveBeenCalledTimes(1);
+        });
+
+        it ('does not register a close listener when no abortController is provided', async () => {
+            await controller.streamSseResponse(jest.fn(), jest.fn());
+            expect(request.on).not.toHaveBeenCalled();
+            expect(request.off).not.toHaveBeenCalled();
+        });
+
+        it ('resets streaming state after completion so a new stream can start', async () => {
+            await controller.streamSseResponse(jest.fn(), jest.fn());
+            // Second call should not throw StreamInProgressError.
+            await expect(controller.streamSseResponse(jest.fn(), jest.fn())).resolves.toBeUndefined();
+        });
+    });
+
+
+    describe('#writeStreamEvent', () => {
+        let controller;
+        let response;
+
+        beforeEach(() => {
+            response   = {
+                setHeader:     jest.fn(),
+                flushHeaders:  jest.fn(),
+                write:         jest.fn(),
+                end:           jest.fn(),
+                writableEnded: false
+            };
+            controller = new FooController({ on: jest.fn(), off: jest.fn() }, response);
+        });
+
+        it ('throws NoActiveStreamError when called outside a stream', () => {
+            expect(() => controller.writeStreamEvent('msg', 'hello'))
+                .toThrow(NoActiveStreamError);
+        });
+
+        it ('writes both event and data lines when an event name is provided', async () => {
+            await controller.streamSseResponse(async () => {
+                response.write.mockClear();
+                controller.writeStreamEvent('progress', 'halfway');
+                expect(response.write).toHaveBeenNthCalledWith(1, 'event: progress\n');
+                expect(response.write).toHaveBeenNthCalledWith(2, 'data: halfway\n\n');
+            }, jest.fn());
+        });
+
+        it ('writes only the data line when no event name is provided', async () => {
+            await controller.streamSseResponse(async () => {
+                response.write.mockClear();
+                controller.writeStreamEvent(null, 'plain');
+                expect(response.write).toHaveBeenCalledTimes(1);
+                expect(response.write).toHaveBeenCalledWith('data: plain\n\n');
+            }, jest.fn());
+        });
+
+        it ('is a no-op when the response is already ended', async () => {
+            await controller.streamSseResponse(async () => {
+                response.writableEnded = true;
+                response.write.mockClear();
+                controller.writeStreamEvent(null, 'ignored');
+                expect(response.write).not.toHaveBeenCalled();
+            }, jest.fn());
+        });
+
+        it ('is a no-op when the abort signal is aborted', async () => {
+            const abortController = { abort: jest.fn(), signal: { aborted: false } };
+            await controller.streamSseResponse(async () => {
+                abortController.signal.aborted = true;
+                response.write.mockClear();
+                controller.writeStreamEvent(null, 'ignored');
+                expect(response.write).not.toHaveBeenCalled();
+            }, jest.fn(), abortController);
+        });
+    });
 });