@vida-global/core 2.0.0 → 2.0.3

package/test/server/serverController.test.js

@@ -27,23 +27,37 @@ describe('VidaServerController', () => {
     });
 
 
-    describe('.autoLoadHelpers', () => {
+    describe('.autoLoadMixins', () => {
         class AutoLoadTestController extends VidaServerController {
-            static get autoLoadHelperPath() {
+            static get mixinDirectory() {
                 return `${process.cwd()}/test/server/helpers/autoload/${this.name}.js`;
             }
         }
 
-        it ('does nothing if there is no helper', () => {
+        it ('calls loadMixin with an empty mixin when there is no mixin file at the expected path', () => {
             class TmpController extends AutoLoadTestController {}
-            TmpController.autoLoadHelpers();
-            expect(TmpController.anInstanceMethod).toBe(undefined);
-            expect(TmpController.aProperty).toBe(undefined);
+            const loadMixinSpy = jest.spyOn(TmpController, 'loadMixin');
+
+            TmpController.autoLoadMixins();
+
+            expect(loadMixinSpy).toHaveBeenCalledTimes(1);
+            expect(loadMixinSpy).toHaveBeenCalledWith({});
         });
 
-        it ('loads instance methods and accessors from the helper', () => {
+        it ('does not add any own prototype or static properties when there is no mixin', () => {
+            class TmpController extends AutoLoadTestController {}
+            const protoKeysBefore  = Object.getOwnPropertyNames(TmpController.prototype);
+            const staticKeysBefore = Object.getOwnPropertyNames(TmpController);
+
+            TmpController.autoLoadMixins();
+
+            expect(Object.getOwnPropertyNames(TmpController.prototype)).toEqual(protoKeysBefore);
+            expect(Object.getOwnPropertyNames(TmpController)).toEqual(staticKeysBefore);
+        });
+
+        it ('loads instance methods and accessors from the mixin', () => {
             class TmpWithHelpersController extends AutoLoadTestController {}
-            TmpWithHelpersController.autoLoadHelpers();
+            TmpWithHelpersController.autoLoadMixins();
 
             const { InstanceMethods, Accessors } = require('./helpers/autoload/TmpWithHelpersController');
 
@@ -156,6 +170,52 @@ describe('VidaServerController', () => {
     });
 
 
+    describe('#coerceString', () => {
+        const controller = new FooController({}, {});
+
+        it ('returns the string when passed a non-empty string', () => {
+            const value = TestHelpers.Faker.Text.randomString();
+            expect(controller.coerceString(value)).toBe(value);
+        });
+
+        it ('trims surrounding whitespace', () => {
+            const value = TestHelpers.Faker.Text.randomString();
+            expect(controller.coerceString(`  ${value}  `)).toBe(value);
+        });
+
+        it ('returns the fallback for an empty string', () => {
+            const fallback = TestHelpers.Faker.Text.randomString();
+            expect(controller.coerceString('', {fallback})).toBe(fallback);
+        });
+
+        it ('returns the fallback for a whitespace-only string', () => {
+            const fallback = TestHelpers.Faker.Text.randomString();
+            expect(controller.coerceString('   ', {fallback})).toBe(fallback);
+        });
+
+        it.each([
+            [null],
+            [undefined],
+            [123],
+            [true],
+            [false],
+            [{}],
+            [[]],
+        ])('returns the fallback for non-string input (%p)', (input) => {
+            const fallback = TestHelpers.Faker.Text.randomString();
+            expect(controller.coerceString(input, {fallback})).toBe(fallback);
+        });
+
+        it ('defaults the fallback to an empty string when no options are given', () => {
+            expect(controller.coerceString(null)).toBe('');
+        });
+
+        it ('defaults the fallback to an empty string for empty input when no options are given', () => {
+            expect(controller.coerceString('   ')).toBe('');
+        });
+    });
+
+
     describe('#coerceBoolean', () => {
         const controller = new FooController({}, {});
 
@@ -304,7 +364,6 @@ describe('VidaServerController', () => {
         const paramName2      = TestHelpers.Faker.Text.randomString();
         const value1          = TestHelpers.Faker.Text.randomString();
         const value2          = TestHelpers.Faker.Text.randomString();
-        const params          = {[paramName1]: value1, [paramName2]: value2};
         const validationType1 = TestHelpers.Faker.Text.randomString();
         const validationType2 = TestHelpers.Faker.Text.randomString();
         const options1        = [TestHelpers.Faker.Text.randomString()];
@@ -312,11 +371,13 @@ describe('VidaServerController', () => {
         const error1          = TestHelpers.Faker.Text.randomString()
         const error2          = TestHelpers.Faker.Text.randomString()
 
+        let params;
         let controller;
         let response;
         let validator1;
         let validator2;
         beforeEach(() => {
+            params                                             = {[paramName1]: value1, [paramName2]: value2};
             response                                           = {json: jest.fn(), statusCode: 200};
             controller                                         = new FooController({params}, response);
             controller.render                                  = jest.fn();
@@ -343,7 +404,14 @@ describe('VidaServerController', () => {
 
         it ('throws a `ValidationError` when there\'s an error', async () => {
             validator1.mockImplementation(() => error1);
-            await expect(controller.validateParameters(validations)).rejects.toThrow();
+            await expect(controller.validateParameters(validations)).rejects.toThrow(Errors.ValidationError);
+        });
+
+        it ('attaches the failing parameter and error message to the ValidationError fields', async () => {
+            validator1.mockImplementation(() => error1);
+            await expect(controller.validateParameters(validations)).rejects.toMatchObject({
+                fields: {[paramName1]: [error1], [paramName2]: [error1]}
+            });
         });
 
         it ('throws a `ValidationError` when there are multiple errors', async () => {
@@ -371,16 +439,86 @@ describe('VidaServerController', () => {
 
         it ('does not error when optional parameters are not included', async () => {
             const validations = {foo: {isString: true, optional: true}};
-            expect(controller.validateParameters(validations)).resolves.not.toThrow();
+            await expect(controller.validateParameters(validations)).resolves.not.toThrow();
         });
 
-        it ('does  error when optional parameters are invalid', async () => {
+        it ('does error when optional parameters are invalid', async () => {
             const validations = {foo: {isString: {length: {gte: 2}}, optional: true}};
             params.foo = '';
 
             await expect(controller.validateParameters(validations)).rejects.toThrow(Errors.ValidationError);
+        });
+    });
+
 
-            delete params.foo;
+    describe('.validateAction', () => {
+        it ('is a no-op when the controller has no parametersFor<Action> method', async () => {
+            class C extends VidaServerController {}
+            const controller = new C({}, {});
+            controller.validateParameters = jest.fn();
+
+            await controller.validateAction('getThing');
+            expect(controller.validateParameters).not.toHaveBeenCalled();
+        });
+
+        it ('calls validateParameters with the value returned by parametersFor<Action>', async () => {
+            const params = {foo: {isString: true}};
+            class C extends VidaServerController {
+                static parametersForGetThing() { return params; }
+            }
+            const controller = new C({}, {});
+            controller.validateParameters = jest.fn();
+
+            await controller.validateAction('getThing');
+            expect(controller.validateParameters).toHaveBeenCalledTimes(1);
+            expect(controller.validateParameters).toHaveBeenCalledWith(params);
+        });
+
+        it ('camelizes the action name when looking up the parametersFor method', async () => {
+            const params = {foo: {isString: true}};
+            class C extends VidaServerController {
+                static parametersForGetFooBar() { return params; }
+            }
+            const controller = new C({}, {});
+            controller.validateParameters = jest.fn();
+
+            await controller.validateAction('getFooBar');
+            expect(controller.validateParameters).toHaveBeenCalledWith(params);
+        });
+
+        it ('propagates ValidationError thrown by validateParameters', async () => {
+            class C extends VidaServerController {
+                static parametersForGetThing() { return {foo: {isString: true}}; }
+            }
+            const request = { params: {}, query: {}, body: {foo: 42} };
+            const controller = new C(request, {});
+
+            await expect(controller.validateAction('getThing')).rejects.toThrow(Errors.ValidationError);
+        });
+    });
+
+
+    describe('.parametersForAction', () => {
+        it ('returns null when no parametersFor method is defined', () => {
+            class C extends VidaServerController {}
+            expect(C.parametersForAction('getThing')).toBe(null);
+        });
+
+        it ('returns the value of the matching parametersFor<Action> method', () => {
+            const params = {foo: {isString: true}};
+            class C extends VidaServerController {
+                static parametersForGetThing() { return params; }
+            }
+            expect(C.parametersForAction('getThing')).toBe(params);
+        });
+    });
+
+
+    describe('.parametersMethodForAction', () => {
+        it ('returns the camelized parametersFor<Action> method name', () => {
+            class C extends VidaServerController {}
+            expect(C.parametersMethodForAction('getFooBar')).toBe('parametersForGetFooBar');
+            expect(C.parametersMethodForAction('postIndex')).toBe('parametersForPostIndex');
         });
     });
 
@@ -566,32 +704,32 @@ describe('VidaServerController', () => {
 
     describe('.validateIsDateTime', () => {
         const controller = new FooController({}, {});
-        it ('returns undefined when passed a string of format YYYY-MM-DD', () => {
+        it ('returns undefined when passed a date string of format YYYY-MM-DD', () => {
             const result = controller.validateIsDateTime('2025-12-17');
             expect(result).toBe(undefined);
         });
 
-        it ('returns undefined when passed a string of format MM/DD/YY', () => {
+        it ('returns undefined when passed a date string of format MM/DD/YY', () => {
             const result = controller.validateIsDateTime('12/17/25');
             expect(result).toBe(undefined);
         });
 
-        it ('returns undefined when passed a string of format Month name DD, YYY', () => {
+        it ('returns undefined when passed a date string of format Month name DD, YYYY', () => {
             const result = controller.validateIsDateTime('December 17, 2025');
             expect(result).toBe(undefined);
         });
 
-        it ('returns undefined when passed a string of format YYYY-MM-DD HH:MM:SS', () => {
+        it ('returns undefined when passed a datetime string of format YYYY-MM-DD HH:MM:SS', () => {
             const result = controller.validateIsDateTime('2025-12-17 01:05:00');
             expect(result).toBe(undefined);
         });
 
-        it ('returns undefined when passed a string of format MM/DD/YY', () => {
+        it ('returns undefined when passed a datetime string of format MM/DD/YY HH:MM:SS', () => {
             const result = controller.validateIsDateTime('12/17/25 01:05:00');
             expect(result).toBe(undefined);
         });
 
-        it ('returns undefined when passed a string of format Month name DD, YYY', () => {
+        it ('returns undefined when passed a datetime string of format Month name DD, YYYY HH:MM:SS', () => {
             const result = controller.validateIsDateTime('December 17, 2025 01:05:00');
             expect(result).toBe(undefined);
         });
@@ -655,7 +793,7 @@ describe('VidaServerController', () => {
         const error        = TestHelpers.Faker.Text.randomString();
         const validator    = (value) => value == correctValue ? undefined : error;
 
-        it ('returns undefiend when passed a valid value', async () => {
+        it ('returns undefined when passed a valid value', async () => {
             const result = await controller.validateFunction(correctValue, validator);
             expect(result).toBe(undefined);
         });
@@ -725,6 +863,20 @@ describe('VidaServerController', () => {
             expect(controller.statusCode).toEqual(500);
             expect(controller.render).toHaveBeenCalledWith({errors: {message: null}});
         });
+
+        it ('awaits render before calling response.end (regression: ERR_HTTP_HEADERS_SENT)', async () => {
+            const response   = { json: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const controller = new FooController({}, response);
+            controller.testAction = jest.fn(async () => ({foo: TestHelpers.Faker.Text.randomString()}));
+
+            await controller.performRequest('testAction');
+
+            expect(response.json).toHaveBeenCalledTimes(1);
+            expect(response.end).toHaveBeenCalledTimes(1);
+            const jsonOrder = response.json.mock.invocationCallOrder[0];
+            const endOrder  = response.end.mock.invocationCallOrder[0];
+            expect(jsonOrder).toBeLessThan(endOrder);
+        });
     });
 
 
@@ -876,6 +1028,118 @@ describe('VidaServerController', () => {
     });
 
 
+    describe('#render', () => {
+        let response;
+        let controller;
+        beforeEach(() => {
+            response   = {json: jest.fn(), send: jest.fn(), statusCode: 200};
+            controller = new FooController({}, response);
+        });
+
+        it ('calls response.send (not response.json) when the body is a string', async () => {
+            const body = TestHelpers.Faker.Text.randomString();
+            await controller.render(body);
+
+            expect(response.send).toHaveBeenCalledTimes(1);
+            expect(response.send).toHaveBeenCalledWith(body);
+            expect(response.json).not.toHaveBeenCalled();
+        });
+
+        it ('marks the controller as rendered after a string render', async () => {
+            await controller.render('hello');
+            expect(controller.rendered).toBe(true);
+        });
+
+        it ('is a no-op when the controller has already been rendered', async () => {
+            controller.markRendered();
+            await controller.render('hello');
+            expect(response.send).not.toHaveBeenCalled();
+            expect(response.json).not.toHaveBeenCalled();
+        });
+
+        it ('is a no-op when the controller is streaming', async () => {
+            controller._isStreaming = true;
+            await controller.render('hello');
+            await controller.render({foo: 'bar'});
+
+            expect(response.send).not.toHaveBeenCalled();
+            expect(response.json).not.toHaveBeenCalled();
+        });
+
+        it ('does not mark the controller as rendered when streaming', async () => {
+            controller._isStreaming = true;
+            await controller.render('hello');
+            expect(controller.rendered).toBe(false);
+        });
+    });
+
+
+    describe('#processJSONBody', () => {
+        let controller;
+        beforeEach(() => {
+            controller = new FooController({}, {});
+        });
+
+        it ('returns null when the body is undefined', async () => {
+            expect(await controller.processJSONBody(undefined, {})).toBe(null);
+        });
+
+        it ('returns null when the body is null', async () => {
+            expect(await controller.processJSONBody(null, {})).toBe(null);
+        });
+
+        it ('returns primitives unchanged', async () => {
+            expect(await controller.processJSONBody('hello', {})).toBe('hello');
+            expect(await controller.processJSONBody(42,      {})).toBe(42);
+            expect(await controller.processJSONBody(true,    {})).toBe(true);
+        });
+
+        it ('returns Date instances as their epoch ms via getTime', async () => {
+            const date = new Date('2020-01-02T03:04:05Z');
+            expect(await controller.processJSONBody(date, {})).toBe(date.getTime());
+        });
+
+        it ('recursively processes Date values inside objects', async () => {
+            const date = new Date('2021-02-03T00:00:00Z');
+            const result = await controller.processJSONBody({createdAt: date, name: 'foo'}, {});
+            expect(result).toEqual({createdAt: date.getTime(), name: 'foo'});
+        });
+
+        it ('recursively processes arrays', async () => {
+            const date = new Date('2022-03-04T00:00:00Z');
+            const result = await controller.processJSONBody([1, date, {ts: date}], {});
+            expect(result).toEqual([1, date.getTime(), {ts: date.getTime()}]);
+        });
+
+        it ('invokes toApiResponse on objects that define it and recurses on the result', async () => {
+            const date     = new Date('2023-04-05T00:00:00Z');
+            const apiModel = {
+                async toApiResponse() { return {id: 1, createdAt: date}; }
+            };
+            const result = await controller.processJSONBody(apiModel, {});
+            expect(result).toEqual({id: 1, createdAt: date.getTime()});
+        });
+
+        it ('passes the options argument through to toApiResponse', async () => {
+            const options    = {standardize: false, extra: 'flag'};
+            const toApi      = jest.fn().mockResolvedValue({});
+            const apiModel   = {toApiResponse: toApi};
+
+            await controller.processJSONBody(apiModel, options);
+            expect(toApi).toHaveBeenCalledWith(options);
+        });
+
+        it ('recurses through arrays of objects with toApiResponse', async () => {
+            const apiModels = [
+                {toApiResponse: async () => ({id: 'a'})},
+                {toApiResponse: async () => ({id: 'b'})},
+            ];
+            const result = await controller.processJSONBody(apiModels, {});
+            expect(result).toEqual([{id: 'a'}, {id: 'b'}]);
+        });
+    });
+
+
     describe('Request Properties', () => {
         let request;
         let response;
@@ -910,6 +1174,56 @@ describe('VidaServerController', () => {
         });
 
 
+        describe('#userAgent', () => {
+            it ('returns the user-agent request header', () => {
+                const ua = TestHelpers.Faker.Text.randomString();
+                request.headers['user-agent'] = ua;
+                expect(controller.userAgent).toEqual(ua);
+            });
+        });
+
+
+        describe('#requestBody', () => {
+            it ('returns the underlying request body', () => {
+                const body = {foo: TestHelpers.Faker.Text.randomString()};
+                request.body = body;
+                expect(controller.requestBody).toBe(body);
+            });
+        });
+
+
+        describe('#requestId', () => {
+            it ('returns the request id', () => {
+                request.id = TestHelpers.Faker.Text.randomString();
+                expect(controller.requestId).toEqual(request.id);
+            });
+        });
+
+
+        describe('#requestIp', () => {
+            it ('returns the request ip', () => {
+                request.ip = TestHelpers.Faker.Text.randomString();
+                expect(controller.requestIp).toEqual(request.ip);
+            });
+        });
+
+
+        describe('#requestMethod', () => {
+            it ('returns the request method', () => {
+                request.method = 'POST';
+                expect(controller.requestMethod).toEqual('POST');
+            });
+        });
+
+
+        describe('#url', () => {
+            it ('returns the request originalUrl', () => {
+                request.originalUrl = `/${TestHelpers.Faker.Text.randomString()}`;
+                expect(controller.url).toEqual(request.originalUrl);
+            });
+        });
+
+
         describe('#logger', () => {
             it ('returns a child of the passed logger, scoped to the request id', () => {
                 const childLogger  = {};
@@ -954,23 +1268,368 @@ describe('VidaServerController', () => {
                 expect(response.statusCode).toEqual(code);
             });
         });
+
+
+        describe('#bearerToken', () => {
+            beforeEach(() => {
+                delete request.headers.authorization;
+            });
+
+            it ('returns null when there is no authorization header', () => {
+                expect(controller.bearerToken).toBe(null);
+            });
+
+            it ('returns null when the authorization header is empty', () => {
+                request.headers.authorization = '';
+                expect(controller.bearerToken).toBe(null);
+            });
+
+            it ('returns null when the authorization scheme is not bearer', () => {
+                request.headers.authorization = 'Basic dXNlcjpwYXNz';
+                expect(controller.bearerToken).toBe(null);
+            });
+
+            it ('extracts the token after a lowercase bearer scheme', () => {
+                request.headers.authorization = 'bearer abc123';
+                expect(controller.bearerToken).toBe('abc123');
+            });
+
+            it ('extracts the token regardless of bearer scheme casing', () => {
+                request.headers.authorization = 'Bearer abc123';
+                expect(controller.bearerToken).toBe('abc123');
+
+                const c2 = new FooController({headers: {authorization: 'BEARER xyz'}}, response);
+                expect(c2.bearerToken).toBe('xyz');
+            });
+
+            it ('tolerates leading whitespace and trims trailing whitespace from the token', () => {
+                request.headers.authorization = '   Bearer   tokenValue   ';
+                expect(controller.bearerToken).toBe('tokenValue');
+            });
+        });
     });
 
 
     describe('#setupCallbacks', () => {
-        it ('is only called once', () => {
+        it ('is called once during construction and then cleared from the instance', () => {
             class CallbacksTestController extends VidaServerController {}
             CallbacksTestController.prototype.setupCallbacks = jest.fn();
             const controller = new CallbacksTestController({}, {});
 
             expect(CallbacksTestController.prototype.setupCallbacks).toHaveBeenCalledTimes(1);
             expect(controller.setupCallbacks).toBe(undefined);
+        });
 
+        it ('is only called once per class across multiple instances', () => {
+            class CallbacksOnceController extends VidaServerController {}
+            CallbacksOnceController.prototype.setupCallbacks = jest.fn();
+
+            new CallbacksOnceController({}, {});
+            new CallbacksOnceController({}, {});
+            new CallbacksOnceController({}, {});
+
+            expect(CallbacksOnceController.prototype.setupCallbacks).toHaveBeenCalledTimes(1);
+        });
+
+        it ('does not duplicate registered callbacks across instances of the same class', async () => {
+            const callback = jest.fn();
+
+            class CallbacksAccumController extends VidaServerController {
+                setupCallbacks() { this.beforeCallback(callback); }
+            }
+
+            new CallbacksAccumController({}, {});
+            new CallbacksAccumController({}, {});
+            new CallbacksAccumController({}, {});
+            const controller = new CallbacksAccumController({}, {});
+
+            await controller._runCallbacks('before', 'getIndex');
+            expect(callback).toHaveBeenCalledTimes(1);
+        });
+
+        it ('does not share callbacks across different controller classes', async () => {
+            const callbackA = jest.fn();
+            const callbackB = jest.fn();
+
+            class CallbacksClassA extends VidaServerController {
+                setupCallbacks() { this.beforeCallback(callbackA); }
+            }
+            class CallbacksClassB extends VidaServerController {
+                setupCallbacks() { this.beforeCallback(callbackB); }
+            }
+
+            const a = new CallbacksClassA({}, {});
+            const b = new CallbacksClassB({}, {});
+
+            await a._runCallbacks('before', 'someAction');
+            expect(callbackA).toHaveBeenCalledTimes(1);
+            expect(callbackB).toHaveBeenCalledTimes(0);
+
+            await b._runCallbacks('before', 'someAction');
+            expect(callbackA).toHaveBeenCalledTimes(1);
+            expect(callbackB).toHaveBeenCalledTimes(1);
         });
     });
 
 
-    describe('Request Properties', () => {
+    describe('#_runCallbacks', () => {
+        it ('runs before-callbacks in registration order then the action', async () => {
+            const order = [];
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(() => { order.push('before1') });
+                    this.beforeCallback('namedBefore');
+                }
+                namedBefore() { order.push('before2') }
+                testAction()  { order.push('action');  return {} }
+            }
+            const response   = { json: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const controller = new C({}, response);
+
+            await controller.performRequest('testAction');
+            expect(order).toEqual(['before1', 'before2', 'action']);
+        });
+
+        it ('runs after-callbacks in registration order after the action', async () => {
+            const order = [];
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.afterCallback(() => { order.push('after1') });
+                    this.afterCallback('namedAfter');
+                }
+                namedAfter() { order.push('after2') }
+                testAction() { order.push('action'); return {} }
+            }
+            const response   = { json: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const controller = new C({}, response);
+
+            await controller.performRequest('testAction');
+            expect(order).toEqual(['action', 'after1', 'after2']);
+        });
+
+        it ('skips the action when a before-callback returns false', async () => {
+            const testAction = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() { this.beforeCallback(() => false) }
+            }
+            C.prototype.testAction = testAction;
+            const response   = { json: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const controller = new C({}, response);
+
+            await controller.performRequest('testAction');
+            expect(testAction).not.toHaveBeenCalled();
+        });
+
+        it ('skips remaining before-callbacks when one returns false', async () => {
+            const second = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(() => false);
+                    this.beforeCallback(second);
+                }
+                testAction() { return {} }
+            }
+            const response   = { json: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const controller = new C({}, response);
+
+            await controller.performRequest('testAction');
+            expect(second).not.toHaveBeenCalled();
+        });
+
+        it ('skips after-callbacks when a before-callback returns false', async () => {
+            const after = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(() => false);
+                    this.afterCallback(after);
+                }
+                testAction() { return {} }
+            }
+            const response   = { json: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const controller = new C({}, response);
+
+            await controller.performRequest('testAction');
+            expect(after).not.toHaveBeenCalled();
+        });
+
+        it ('respects only/except options when running callbacks', async () => {
+            const onlyCb   = jest.fn();
+            const exceptCb = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(onlyCb,   {only:   ['allowed']});
+                    this.beforeCallback(exceptCb, {except: ['blocked']});
+                }
+            }
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('before', 'allowed');
+            expect(onlyCb).toHaveBeenCalledTimes(1);
+            expect(exceptCb).toHaveBeenCalledTimes(1);
+
+            await controller._runCallbacks('before', 'blocked');
+            expect(onlyCb).toHaveBeenCalledTimes(1);
+            expect(exceptCb).toHaveBeenCalledTimes(1);
+
+            await controller._runCallbacks('before', 'other');
+            expect(onlyCb).toHaveBeenCalledTimes(1);
+            expect(exceptCb).toHaveBeenCalledTimes(2);
+        });
+
+        it ('supports both function and method-name string callbacks', async () => {
+            const fnCb = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(fnCb);
+                    this.beforeCallback('namedCb');
+                }
+            }
+            C.prototype.namedCb = jest.fn();
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('before', 'someAction');
+            expect(fnCb).toHaveBeenCalledTimes(1);
+            expect(C.prototype.namedCb).toHaveBeenCalledTimes(1);
+        });
+    });
+
+
+    describe('#skipBeforeCallback / #skipAfterCallback', () => {
+        it ('skips a registered before-callback when the same function reference is in the skip list', async () => {
+            const skipped = jest.fn();
+            const kept    = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(skipped);
+                    this.beforeCallback(kept);
+                    this.skipBeforeCallback(skipped);
+                }
+            }
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('before', 'someAction');
+            expect(skipped).not.toHaveBeenCalled();
+            expect(kept).toHaveBeenCalledTimes(1);
+        });
+
+        it ('skips a registered before-callback by method-name string', async () => {
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback('namedCb');
+                    this.skipBeforeCallback('namedCb');
+                }
+            }
+            C.prototype.namedCb = jest.fn();
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('before', 'someAction');
+            expect(C.prototype.namedCb).not.toHaveBeenCalled();
+        });
+
+        it ('skips a registered after-callback when in the after skip list', async () => {
+            const skipped = jest.fn();
+            const kept    = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.afterCallback(skipped);
+                    this.afterCallback(kept);
+                    this.skipAfterCallback(skipped);
+                }
+            }
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('after', 'someAction');
+            expect(skipped).not.toHaveBeenCalled();
+            expect(kept).toHaveBeenCalledTimes(1);
+        });
+
+        it ('only applies the skip on actions matching the skip\'s only option', async () => {
+            const cb = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(cb);
+                    this.skipBeforeCallback(cb, {only: 'skipMe'});
+                }
+            }
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('before', 'skipMe');
+            expect(cb).not.toHaveBeenCalled();
+
+            await controller._runCallbacks('before', 'otherAction');
+            expect(cb).toHaveBeenCalledTimes(1);
+        });
+
+        it ('applies the skip on all actions except those listed in the skip\'s except option', async () => {
+            const cb = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(cb);
+                    this.skipBeforeCallback(cb, {except: 'keepMe'});
+                }
+            }
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('before', 'keepMe');
+            expect(cb).toHaveBeenCalledTimes(1);
+
+            await controller._runCallbacks('before', 'somethingElse');
+            expect(cb).toHaveBeenCalledTimes(1);
+        });
+
+        it ('does not affect callbacks whose identity does not match the skip entry', async () => {
+            const cb    = jest.fn();
+            const other = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(cb);
+                    this.skipBeforeCallback(other);
+                }
+            }
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('before', 'anyAction');
+            expect(cb).toHaveBeenCalledTimes(1);
+        });
+    });
+
+
+    describe('#isAuthenticatedAction', () => {
+        it ('returns false when no authenticateRequest callback is registered', () => {
+            class NoAuthController extends VidaServerController {}
+            const controller = new NoAuthController({}, {});
+            expect(controller.isAuthenticatedAction('getIndex')).toBe(false);
+        });
+
+        it ('returns true for any action when authenticateRequest is registered without restrictions', () => {
+            class AuthAllController extends VidaServerController {
+                setupCallbacks() { this.beforeCallback('authenticateRequest'); }
+                authenticateRequest() {}
+            }
+            const controller = new AuthAllController({}, {});
+            expect(controller.isAuthenticatedAction('getIndex')).toBe(true);
+            expect(controller.isAuthenticatedAction('getOther')).toBe(true);
+        });
+
+        it ('respects the `except` option on the authenticateRequest callback', () => {
+            class AuthExceptController extends VidaServerController {
+                setupCallbacks() { this.beforeCallback('authenticateRequest', {except: 'getOpen'}); }
+                authenticateRequest() {}
+            }
+            const controller = new AuthExceptController({}, {});
+            expect(controller.isAuthenticatedAction('getIndex')).toBe(true);
+            expect(controller.isAuthenticatedAction('getOpen')).toBe(false);
+        });
+
+        it ('respects the `only` option on the authenticateRequest callback', () => {
+            class AuthOnlyController extends VidaServerController {
+                setupCallbacks() { this.beforeCallback('authenticateRequest', {only: ['getSecret']}); }
+                authenticateRequest() {}
+            }
+            const controller = new AuthOnlyController({}, {});
+            expect(controller.isAuthenticatedAction('getSecret')).toBe(true);
+            expect(controller.isAuthenticatedAction('getIndex')).toBe(false);
+        });
     });
 
 
@@ -1164,4 +1823,191 @@ describe('VidaServerController', () => {
             }, jest.fn(), abortController);
         });
     });
+
+
+    describe('cookies / getCookie / setCookie', () => {
+        let request;
+        let response;
+        let controller;
+
+
+        beforeEach(() => {
+            request    = { cookies: { sessionId: 'abc', theme: 'dark' } };
+            response   = { cookie: jest.fn() };
+            controller = new FooController(request, response);
+        });
+
+
+        describe('#cookies', () => {
+            it ('returns the cookies object from the request', () => {
+                expect(controller.cookies).toEqual({ sessionId: 'abc', theme: 'dark' });
+            });
+
+
+            it ('returns an empty object when request.cookies is undefined', () => {
+                controller = new FooController({}, response);
+                expect(controller.cookies).toEqual({});
+            });
+        });
+
+
+        describe('#getCookie', () => {
+            it ('returns the value for an existing cookie', () => {
+                expect(controller.getCookie('sessionId')).toBe('abc');
+            });
+
+
+            it ('returns null for a missing cookie', () => {
+                expect(controller.getCookie('missing')).toBeNull();
+            });
+
+
+            it ('returns null when name is empty', () => {
+                expect(controller.getCookie('')).toBeNull();
+            });
+
+
+            it ('returns null when name is null', () => {
+                expect(controller.getCookie(null)).toBeNull();
+            });
+        });
+
+
+        describe('#setCookie', () => {
+            it ('invokes response.cookie with the given name, value, and options', () => {
+                const options = { path: '/foo', maxAge: 60000, httpOnly: true, secure: true, sameSite: 'None' };
+                controller.setCookie('sessionId', 'xyz', options);
+                expect(response.cookie).toHaveBeenCalledTimes(1);
+                expect(response.cookie).toHaveBeenCalledWith('sessionId', 'xyz', options);
+            });
+
+
+            it ('defaults options to an empty object', () => {
+                controller.setCookie('sessionId', 'xyz');
+                expect(response.cookie).toHaveBeenCalledWith('sessionId', 'xyz', {});
+            });
+
+
+            it ('coerces null/undefined value to an empty string', () => {
+                controller.setCookie('sessionId', null);
+                expect(response.cookie).toHaveBeenCalledWith('sessionId', '', {});
+            });
+
+
+            it ('is a no-op when name is empty', () => {
+                controller.setCookie('', 'xyz');
+                expect(response.cookie).not.toHaveBeenCalled();
+            });
+
+
+            it ('is a no-op when name is null', () => {
+                controller.setCookie(null, 'xyz');
+                expect(response.cookie).not.toHaveBeenCalled();
+            });
+        });
+    });
+
+
+    describe('#renderFile', () => {
+        let request;
+        let response;
+        let controller;
+
+
+        beforeEach(() => {
+            request    = {};
+            response   = {
+                setHeader: jest.fn(),
+                sendFile:  jest.fn((path, options, cb) => cb()),
+            };
+            controller = new FooController(request, response);
+        });
+
+
+        it ('sets Content-Type from the explicit option when provided', async () => {
+            await controller.renderFile('/var/www/foo.bin', { contentType: 'application/x-custom' });
+            expect(response.setHeader).toHaveBeenCalledWith('Content-Type', 'application/x-custom');
+        });
+
+
+        it.each([
+            ['/a/b.html',  'text/html; charset=utf-8'],
+            ['/a/b.htm',   'text/html; charset=utf-8'],
+            ['/a/b.css',   'text/css; charset=utf-8'],
+            ['/a/b.js',    'application/javascript; charset=utf-8'],
+            ['/a/b.mjs',   'application/javascript; charset=utf-8'],
+            ['/a/b.json',  'application/json; charset=utf-8'],
+            ['/a/b.txt',   'text/plain; charset=utf-8'],
+            ['/a/b.png',   'image/png'],
+            ['/a/b.jpg',   'image/jpeg'],
+            ['/a/b.jpeg',  'image/jpeg'],
+            ['/a/b.gif',   'image/gif'],
+            ['/a/b.svg',   'image/svg+xml'],
+            ['/a/b.ico',   'image/x-icon'],
+            ['/a/b.webp',  'image/webp'],
+            ['/a/b.woff',  'font/woff'],
+            ['/a/b.woff2', 'font/woff2'],
+            ['/a/b.ttf',   'font/ttf'],
+            ['/a/b.otf',   'font/otf'],
+            ['/a/b.JPG',   'image/jpeg'],
+        ])('guesses Content-Type for %s', async (filePath, expected) => {
+            await controller.renderFile(filePath);
+            expect(response.setHeader).toHaveBeenCalledWith('Content-Type', expected);
+        });
+
+
+        it ('falls back to application/octet-stream for unknown extensions', async () => {
+            await controller.renderFile('/var/www/foo.xyz');
+            expect(response.setHeader).toHaveBeenCalledWith('Content-Type', 'application/octet-stream');
+        });
+
+
+        it ('falls back to application/octet-stream when there is no extension', async () => {
+            await controller.renderFile('/var/www/foo');
+            expect(response.setHeader).toHaveBeenCalledWith('Content-Type', 'application/octet-stream');
+        });
+
+
+        it ('sets Cache-Control when provided', async () => {
+            await controller.renderFile('/var/www/foo.html', { cacheControl: 'no-store' });
+            expect(response.setHeader).toHaveBeenCalledWith('Cache-Control', 'no-store');
+        });
+
+
+        it ('does not set Cache-Control when omitted', async () => {
+            await controller.renderFile('/var/www/foo.html');
+            const cacheCalls = response.setHeader.mock.calls.filter(([name]) => name === 'Cache-Control');
+            expect(cacheCalls).toHaveLength(0);
+        });
+
+
+        it ('passes maxAge to res.sendFile', async () => {
+            await controller.renderFile('/var/www/foo.html', { maxAge: 300000 });
+            expect(response.sendFile).toHaveBeenCalledWith('/var/www/foo.html', { maxAge: 300000 }, expect.any(Function));
+        });
+
+
+        it ('marks the controller as rendered', async () => {
+            expect(controller.rendered).toBe(false);
+            await controller.renderFile('/var/www/foo.html');
+            expect(controller.rendered).toBe(true);
+        });
+
+
+        it ('throws when filePath is empty', () => {
+            expect(() => controller.renderFile('')).toThrow('renderFile requires a filePath');
+        });
+
+
+        it ('throws when filePath is null', () => {
+            expect(() => controller.renderFile(null)).toThrow('renderFile requires a filePath');
+        });
+
+
+        it ('rejects the returned promise when sendFile errors', async () => {
+            const sendError = new Error('disk read failed');
+            response.sendFile = jest.fn((path, options, cb) => cb(sendError));
+            await expect(controller.renderFile('/var/www/foo.html')).rejects.toBe(sendError);
+        });
+    });
 });