@vida-global/core 2.3.3 → 2.3.5

package/AGENTS.md

@@ -2,12 +2,53 @@
 
 Use this guide to understand and write code for the vida-core repo.
 
+`@vida-global/core` is the shared library behind all Vida apps. It also ships to
+customers inside `vida-apps-tools`, so the exported surface is a public API.
+Treat a changed or removed export as a breaking change, not a refactor.
+
+CommonJS throughout (`require` / `module.exports`). There is no linter in this
+repo — the style guide below is the only enforcement, so follow it closely.
+
+
 # Style and conventions
+
+Always in force:
+
 @agents/style.md
-@agents/server.md
-@agents/db.md
-@agents/apis.md
 @agents/testing.md
 
+Read only when the work touches that area:
+
+- `agents/server.md` — Express endpoints, controllers, validation, status codes
+- `agents/db.md` — ActiveRecord, Sequelize, migrations, caching
+- `agents/apis.md` — outbound HTTP clients to third parties
+- `agents/git.md` — branches, commits, GitHub
+- `agents/frontend.md` — Next.js/React only. Not used by this package.
+
+
+# Commands
+
+    npm test                     # jest, coverage on by default
+    npm test -- test/server      # narrow to a directory
+    npm test -- -t 'name'        # narrow by test name
+    npm run develop              # prerelease via @vida-global/release
+    npm run release              # release via @vida-global/release
+
+`npm test` carries required flags (`LOG_LEVEL=test`, `NODE_NO_WARNINGS=1`,
+`node --experimental-vm-modules`). Always go through the script. Calling `jest`
+directly drops them and the run misbehaves.
+
+Coverage is collected on every run. `/helpers/` is excluded by design.
+
+
+# Repository map
+
+`index.js` is the whole public surface. `lib/` holds the modules; `test/` mirrors
+`lib/` one directory per module. Per-module guides live next to the code and are
+listed in `README.md`: `activeRecord`, `http`, `logger`, `server`, `jobQueue`,
+plus `cache`, `redis`, `apm`, `observability`, `utils`.
 
-# Helpers for common use cases
+One non-obvious mechanic in `index.js`: server error classes are exported by
+filtering `lib/server` exports on `prototype instanceof AbstractServerError`. A
+new error class that extends it is exported automatically — do not add it to
+`module.exports` by hand. One that does not extend it is silently absent.

package/lib/activeRecord/README.md

@@ -72,6 +72,14 @@ Wire up the migration CLI by adding scripts to `package.json`:
 
 Generate a migration with `npm run db:create_migration createUsers`. Pass `-- --databaseId metrics` to scope the migration to a non-default database. Run `npm run db:migrate` to apply migrations or `npm run db:rollback` to undo the most recent one.
 
+`db:migrate` and `db:rollback` take an optional `--envFile <path>`. Both open a database connection, and the CLI runs as a bare node process, so nothing has loaded the environment that `config/db/config.js` reads from. Point the flag at a `.env` file and it is loaded before the command runs:
+
+```
+npm run db:migrate -- --envFile .env.staging
+```
+
+A variable already set in the environment wins over the file, so an inline override on the command line still takes effect. Leave the flag off and nothing is loaded, which is what an application that gets its environment some other way wants. `db:create_migration` only writes a file, so it does not accept the flag.
+
 Migration files are named `<timestamp>_<description>.js`, with the database id appended before the extension when one is given — for example `1754500000000_createUsers.js` or `1754500000000_createUsers.metrics.js`. The leading timestamp is the version recorded in `migration_versions` and the order migrations run in, so files sort chronologically by name. Files that don't match this pattern are ignored.
 
 ```js

package/lib/activeRecord/db/migrator.js

@@ -119,8 +119,11 @@ class Migrator {
 
 
     idColumn(idType=DEFAULT_ID_TYPE) {
+        if (idType === false) return {};
+
         if (!ID_TYPES.includes(idType)) {
-            throw new Error(`Unknown id type "${idType}". Use one of: ${ID_TYPES.join(', ')}`);
+            throw new Error(`Unknown id type "${idType}". Use one of: ${ID_TYPES.join(', ')}, or `
+                          + `false for a table that declares its own primary key.`);
         }
 
         return this[`${idType}IdColumn`];
@@ -140,9 +143,10 @@ class Migrator {
     get uuidIdColumn() {
         return {
           id: {
-            allowNull:  false,
-            primaryKey: true,
-            type:       this.DataTypes.UUID, }
+            allowNull:    false,
+            primaryKey:   true,
+            type:         this.DataTypes.UUID,
+            defaultValue: Sequelize.literal('gen_random_uuid()'), }
         };
     }
 
@@ -184,6 +188,20 @@ class Migrator {
     }
 
 
+    async tableExists(tableName) {
+        const tables = await this.#sequelizeQueryInterface.showAllTables(this.queryOptions);
+        return tables.some(table => (table?.tableName ?? table) == tableName);
+    }
+
+
+    // Escape hatch for DDL the typed methods cannot express — CHECK constraints, sequences shared
+    // between tables. Runs inside the migration transaction, so it rolls back with everything else.
+    // Prefer the typed methods; reach for this only when there is no other way.
+    async execute(sql, replacements) {
+        return await this.#connection._sequelize.query(sql, {...this.queryOptions, replacements});
+    }
+
+
     async addColumn(tableName, columnName, columnDetails) {
         await this.#sequelizeQueryInterface.addColumn(tableName, columnName, columnDetails, this.queryOptions);
     }

package/lib/server/controllerMixins/renderer.js

@@ -9,6 +9,13 @@ class StreamInProgressError extends Error {}
 class NoActiveStreamError   extends Error {}
 
 
+// xmlbuilder2's default object-notation control prefixes: @attribute, #text, $cdata,
+// !comment, ?processing-instruction. A key using one of these must survive sanitization
+// unmangled, or an intended attribute (e.g. {'@track': 'both'}) silently turns into a
+// child element (`<_track>both</_track>`) instead of `track="both"`.
+const XML_CONVERT_PREFIXES = ['@', '#', '$', '!', '?'];
+
+
 const CONTENT_TYPE_BY_EXTENSION = {
     css:   'text/css; charset=utf-8',
     gif:   'image/gif',
@@ -88,12 +95,17 @@ const InstanceMethods = {
         if (!this.responseContentType) this.responseContentType = CONTENT_TYPE_BY_EXTENSION.xml;
         const doc = create({ [this.xmlRootElement]: body });
         const xml = doc.end();
-        this._response.send(xml);
+        this._send(xml);
     },
 
 
     renderTextResponse(body) {
         if (!this.responseContentType) this.responseContentType = CONTENT_TYPE_BY_EXTENSION.txt;
+        this._send(body);
+    },
+
+
+    _send(body) {
         this._response.send(body);
     },
 
@@ -182,8 +194,23 @@ const InstanceMethods = {
 
     // XML element names can't start with a digit or contain spaces/other invalid characters,
     // so sanitize keys that would otherwise make xmlbuilder2 throw on dynamic response data.
+    // A leading xmlbuilder2 control prefix (see XML_CONVERT_PREFIXES) is preserved as-is;
+    // only the remainder (the attribute/PI name, if any) is sanitized.
     _toXMLElementName(key) {
-        let name = `${key}`.replace(/[^a-zA-Z0-9_.-]/g, '_');
+        key = `${key}`;
+
+        const prefix = XML_CONVERT_PREFIXES.find(p => key.startsWith(p));
+        if (prefix) {
+            const rest = key.slice(prefix.length);
+            return rest ? prefix + this._sanitizeXMLNamePart(rest) : prefix;
+        }
+
+        return this._sanitizeXMLNamePart(key);
+    },
+
+
+    _sanitizeXMLNamePart(name) {
+        name = name.replace(/[^a-zA-Z0-9_.-]/g, '_');
         if (!/^[a-zA-Z_]/.test(name)) name = `_${name}`;
         return name;
     },

package/lib/server/controllerMixins/requestDetails.js

@@ -47,8 +47,10 @@ const Accessors = {
 
     contentType:     { get() { return this.requestHeaders['content-type']          }},
     cookies:         { get() { return this._request.cookies || {}                  }},
+    isProxiedRequest:{ get() { return Boolean(this.requestHeaders['x-forwarded-for']) }},
     requestBody:     { get() { return this._request.body                           }},
     requestHeaders:  { get() { return structuredClone(this._request.headers || {}) }},
+    requestHost:     { get() { return this.requestHeaders.host                     }},
     requestId:       { get() { return this._request.id                             }},
     requestIp:       { get() { return this._request.ip                             }},
     requestMethod:   { get() { return this._request.method                         }},
@@ -73,6 +75,36 @@ const Accessors = {
             return match[1].trim();
         }
     },
+
+
+    // The absolute URL the caller addressed, rebuilt from the request. Webhook signature schemes
+    // sign this string, so it has to match what the sender used character for character.
+    requestUrl: {
+        get() { return `${this.requestProtocol}://${this.requestHost}${this.url}` }
+    },
+
+
+    // TLS usually terminates at a load balancer, and not every balancer forwards
+    // X-Forwarded-Proto, so `_request.protocol` can report http on a request the caller made over
+    // https. Prefer the forwarded protocol, assume https for anything else that arrived through a
+    // proxy, and fall back to the connection's own protocol for direct requests.
+    requestProtocol: {
+        get() {
+            if (this.forwardedProtocol) return this.forwardedProtocol;
+            if (this.isProxiedRequest)  return 'https';
+            return this._request.protocol;
+        }
+    },
+
+
+    // A comma-joined chain lists the original client's protocol first.
+    forwardedProtocol: {
+        get() {
+            const header = this.requestHeaders['x-forwarded-proto'];
+            if (!header) return null;
+            return header.split(',')[0].trim();
+        }
+    },
 }
 
 

package/lib/server/doc/requestDetails.md

@@ -19,6 +19,11 @@ Within an action, the controller exposes:
 | `this.requestMethod` | HTTP method. |
 | `this.requestIp` | Client IP address. |
 | `this.url` | Original URL. |
+| `this.requestHost` | Shortcut for `requestHeaders['host']`. |
+| `this.requestUrl` | Absolute URL the caller addressed: `requestProtocol://requestHost + url`. Use this when verifying a webhook signature that covers the URL. |
+| `this.requestProtocol` | `forwardedProtocol`, else `https` when `isProxiedRequest`, else the connection's own protocol. |
+| `this.forwardedProtocol` | First entry of `X-Forwarded-Proto`, or `null`. |
+| `this.isProxiedRequest` | `true` when `X-Forwarded-For` is present. |
 | `this.bearerToken` | Parsed `Authorization: Bearer <token>` value, or `null`. |
 | `this.statusCode` | Current outgoing status (settable, but prefer the render helpers below). |
 | `this.logger` | Per-request child logger. |

package/lib/server/server.js

@@ -192,7 +192,7 @@ class VidaServer {
         const method         = action.method.toLowerCase();
         const requestHandler = this.requestHandler(action.action, controllerCls)
         if (process.env.NODE_ENV != 'test') {
-            this.logger.verbose(`ROUTE: ${method.toUpperCase().padEnd(6)} ${action.path}`);
+            this.logger.debug(`ROUTE: ${method.toUpperCase().padEnd(6)} ${action.path}`);
         }
         this['_'+method](action.path, requestHandler);
     }

package/lib/utils/envFile.js

@@ -0,0 +1,14 @@
+const dotenv = require('dotenv');
+const fs     = require('node:fs');
+
+
+function loadEnvFile(filePath) {
+    if (!filePath) return false;
+    if (!fs.existsSync(filePath)) throw new Error(`Environment file ${filePath} does not exist`);
+
+    dotenv.config({ path: filePath, quiet: true });
+    return true;
+}
+
+
+module.exports = { loadEnvFile };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vida-global/core",
-    "version": "2.3.3",
+    "version": "2.3.5",
     "description": "Core libraries for supporting Vida development",
     "author": "",
     "license": "ISC",
@@ -24,6 +24,7 @@
         "bullmq": "^5.0.0",
         "commander": "^13.1.0",
         "cookie-parser": "^1.4.7",
+        "dotenv": "^16.6.1",
         "express": "^4.21.2",
         "express-request-id": "1.4.1",
         "express-winston": "^4.0.0",

package/scripts/activeRecord/migrate.js

@@ -1,5 +1,13 @@
-const   migration = require('../../lib/activeRecord/db/migration');
-const { Command } = require('commander');
+const { loadEnvFile } = require('../../lib/utils/envFile');
+const   migration     = require('../../lib/activeRecord/db/migration');
+const { Command }     = require('commander');
+
+
+// Declared on the commands that touch the database rather than on the program, so it can be passed
+// after the command name, which is where npm puts it: `npm run db:migrate -- --envFile .env.staging`.
+function withEnvFileOption(command) {
+    return command.option('--envFile <path>', 'a .env file to load before the command runs');
+}
 
 
 const program = new Command();
@@ -7,6 +15,10 @@ program.name('Active Record Migration')
        .description('A CLI for generating and running Active Record migrations')
        .version('1.0.0');
 
+program.hook('preAction', (_program, command) => {
+    loadEnvFile(command.opts().envFile);
+});
+
 
 program.command('create_migration')
        .argument('<Description>', 'Description of your migration')
@@ -16,12 +28,13 @@ program.command('create_migration')
        });
 
 
-program.command('migrate')
+withEnvFileOption(program.command('migrate'))
        .action(async () => {
             await migration.runMigrations();
        });
 
-program.command('rollback')
+
+withEnvFileOption(program.command('rollback'))
        .action(async () => {
             await migration.rollbackMigration();
        });

package/test/activeRecord/db/migrator.test.js

@@ -161,13 +161,28 @@ describe('Migrator', () => {
             expect(columns.id).toEqual({ allowNull: false, autoIncrement: true, primaryKey: true, type: 'INTEGER' });
         });
 
-        it ('gives the table a uuid id that the database does not generate', async () => {
+        it ('gives the table a uuid id the database generates', async () => {
             const tableName = Helpers.randomString();
 
             await Helpers.migrator.createTable(tableName, {}, { id: 'uuid' });
 
             const [, columns] = Helpers.mockQueryInterface.createTable.mock.calls[0];
-            expect(columns.id).toEqual({ allowNull: false, primaryKey: true, type: 'UUID' });
+            expect(columns.id).toEqual({
+                allowNull:    false,
+                primaryKey:   true,
+                type:         'UUID',
+                defaultValue: { literal: 'gen_random_uuid()' },
+            });
+        });
+
+
+        it ('does not give an auto-increment id a database default', async () => {
+            const tableName = Helpers.randomString();
+
+            await Helpers.migrator.createTable(tableName, {}, { id: 'bigint' });
+
+            const [, columns] = Helpers.mockQueryInterface.createTable.mock.calls[0];
+            expect(columns.id).not.toHaveProperty('defaultValue');
         });
 
         it ('refuses an id type it does not recognize', async () => {
@@ -177,6 +192,48 @@ describe('Migrator', () => {
                 .rejects.toThrow(`Unknown id type "${idType}". Use one of: bigint, int, uuid`);
         });
 
+        it ('tells the caller false is an option when refusing an id type', async () => {
+            await expect(Helpers.migrator.createTable(Helpers.randomString(), {}, { id: Helpers.randomString() }))
+                .rejects.toThrow('or false for a table that declares its own primary key');
+        });
+
+        // For a table whose primary key is a natural column, e.g. a baseline migration recreating
+        // a table that predates the migrations directory.
+        it ('adds no id column when id is false', async () => {
+            const tableName = Helpers.randomString();
+
+            await Helpers.migrator.createTable(tableName, {}, { id: false });
+
+            const [, columns] = Helpers.mockQueryInterface.createTable.mock.calls[0];
+            expect(columns).not.toHaveProperty('id');
+        });
+
+        it ('keeps the table details when id is false', async () => {
+            const tableName = Helpers.randomString();
+            const uuid      = { allowNull: false, primaryKey: true, type: 'UUID' };
+
+            await Helpers.migrator.createTable(tableName, { uuid }, { id: false, timestamps: false });
+
+            expect(Helpers.mockQueryInterface.createTable).toHaveBeenCalledWith(
+                tableName, { uuid }, Helpers.noTransaction,
+            );
+        });
+
+        const notFalseCases = [['null', null], ['zero', 0], ['an empty string', '']];
+        it.each(notFalseCases)('does not treat %s as false', async (_label, idType) => {
+            await expect(Helpers.migrator.createTable(Helpers.randomString(), {}, { id: idType }))
+                .rejects.toThrow('Unknown id type');
+        });
+
+        it ('still defaults to a bigint id when no id option is given', async () => {
+            const tableName = Helpers.randomString();
+
+            await Helpers.migrator.createTable(tableName, {}, {});
+
+            const [, columns] = Helpers.mockQueryInterface.createTable.mock.calls[0];
+            expect(columns.id).toEqual({ allowNull: false, autoIncrement: true, primaryKey: true, type: 'BIGINT' });
+        });
+
         it ('lets the details override the id column', async () => {
             const tableName = Helpers.randomString();
             const id        = { allowNull: false, primaryKey: true, type: 'UUID' };
@@ -255,6 +312,78 @@ describe('Migrator', () => {
     });
 
 
+    describe('Migrator#tableExists', () => {
+        it ('reports a table that is present', async () => {
+            const tableName = Helpers.randomString();
+            Helpers.mockQueryInterface.showAllTables.mockResolvedValue([Helpers.randomString(), tableName]);
+
+            await expect(Helpers.migrator.tableExists(tableName)).resolves.toBe(true);
+        });
+
+        it ('reports a table that is absent', async () => {
+            Helpers.mockQueryInterface.showAllTables.mockResolvedValue([Helpers.randomString()]);
+
+            await expect(Helpers.migrator.tableExists(Helpers.randomString())).resolves.toBe(false);
+        });
+
+        // Some dialects return objects rather than bare names.
+        it ('reads a name off an object entry', async () => {
+            const tableName = Helpers.randomString();
+            Helpers.mockQueryInterface.showAllTables.mockResolvedValue([{ tableName }]);
+
+            await expect(Helpers.migrator.tableExists(tableName)).resolves.toBe(true);
+        });
+
+        it ('runs inside the open transaction', async () => {
+            Helpers.mockQueryInterface.showAllTables.mockResolvedValue([]);
+
+            await Helpers.runInMigration(async function() {
+                await this.tableExists(Helpers.randomString());
+            });
+
+            expect(Helpers.mockQueryInterface.showAllTables).toHaveBeenCalledWith(Helpers.inTransaction);
+        });
+    });
+
+
+    describe('Migrator#execute', () => {
+        it ('runs the statement and returns its result', async () => {
+            const sql    = `CREATE SEQUENCE ${Helpers.randomString()}`;
+            const result = {};
+            Helpers.mockQuery.mockResolvedValue(result);
+
+            await expect(Helpers.migrator.execute(sql)).resolves.toBe(result);
+
+            expect(Helpers.mockQuery).toHaveBeenCalledWith(sql, {
+                ...Helpers.noTransaction,
+                replacements: undefined,
+            });
+        });
+
+        it ('passes replacements through for binding', async () => {
+            const sql          = 'SELECT :value';
+            const replacements = { value: Helpers.randomString() };
+            Helpers.mockQuery.mockResolvedValue(undefined);
+
+            await Helpers.migrator.execute(sql, replacements);
+
+            expect(Helpers.mockQuery).toHaveBeenCalledWith(sql, expect.objectContaining({ replacements }));
+        });
+
+        // Raw statements have to roll back with the rest of the migration.
+        it ('runs inside the open transaction', async () => {
+            const sql = `CREATE SEQUENCE ${Helpers.randomString()}`;
+            Helpers.mockQuery.mockResolvedValue(undefined);
+
+            await Helpers.runInMigration(async function() {
+                await this.execute(sql);
+            });
+
+            expect(Helpers.mockQuery).toHaveBeenCalledWith(sql, expect.objectContaining(Helpers.inTransaction));
+        });
+    });
+
+
     describe('Migrator#renameColumn', () => {
         it ('snake_cases renameColumn target', async () => {
             const tableName = Helpers.randomString();

package/test/activeRecord/helpers/migrator.js

@@ -16,6 +16,7 @@ const randomString       = TestHelpers.Faker.Text.randomString;
 const transaction        = { id: randomString() };
 const noTransaction      = { transaction: null };
 const inTransaction      = { transaction };
+const mockQuery          = jest.fn();
 const mockQueryInterface = {
     createTable: jest.fn(),
     dropTable: jest.fn(),
@@ -25,6 +26,7 @@ const mockQueryInterface = {
     removeIndex: jest.fn(),
     renameColumn: jest.fn(),
     changeColumn: jest.fn(),
+    showAllTables: jest.fn(),
 };
 
 
@@ -39,10 +41,12 @@ function randomColumnDetails() {
 jest.mock('sequelize', () => {
     class MockSequelize {
         static DataTypes = { BIGINT: 'BIGINT', DATE: 'DATE', INTEGER: 'INTEGER', UUID: 'UUID' };
+        static literal(sql) { return { literal: sql }; }
     }
     return { Sequelize: MockSequelize };
 });
 Sequelize.prototype.getQueryInterface = () => mockQueryInterface;
+Sequelize.prototype.query = (...args) => mockQuery(...args);
 
 
 jest.spyOn(ConnectionConfiguration, '_fetchAllConfigs').mockImplementation(() => ({
@@ -81,6 +85,7 @@ module.exports = {
   inTransaction,
   migrationModule,
   migrator,
+  mockQuery,
   mockQueryInterface,
   noTransaction,
   randomColumnDetails,

package/test/server/controllerMixins/renderer.test.js

@@ -494,6 +494,68 @@ describe('VidaServerController', () => {
             expect(controller._toXMLElementName('first name')).toBe('first_name');
             expect(controller._toXMLElementName('a:b')).toBe('a_b');
         });
+
+
+        // xmlbuilder2 reads these prefixes as instructions rather than as part of the name.
+        // Sanitizing one away silently turns an intended attribute into a child element.
+        const prefixCases = [
+            ['attribute',              '@', '@track',   'both'],
+            ['text',                   '#', '#text',    'value'],
+            ['cdata',                  '$', '$cdata',   'value'],
+            ['comment',                '!', '!comment', 'value'],
+            ['processing instruction', '?', '?target',  'value'],
+        ];
+        it.each(prefixCases)('preserves the %s prefix', (_label, _prefix, key) => {
+            expect(controller._toXMLElementName(key)).toBe(key);
+        });
+
+        it ('sanitizes the name after the prefix but keeps the prefix', () => {
+            expect(controller._toXMLElementName('@my attr')).toBe('@my_attr');
+            expect(controller._toXMLElementName('@a:b')).toBe('@a_b');
+        });
+
+        it ('underscores a prefixed name that starts with a digit', () => {
+            expect(controller._toXMLElementName('@123')).toBe('@_123');
+        });
+
+        it ('returns a bare prefix untouched', () => {
+            expect(controller._toXMLElementName('@')).toBe('@');
+            expect(controller._toXMLElementName('#')).toBe('#');
+        });
+
+        it ('only treats a prefix as a prefix in the leading position', () => {
+            expect(controller._toXMLElementName('track@')).toBe('track_');
+            expect(controller._toXMLElementName('a#b')).toBe('a_b');
+        });
+    });
+
+
+    // The end-to-end reason the prefixes are preserved: without it these render as child
+    // elements (<_track>both</_track>) rather than attributes.
+    describe('#renderXMLResponse attribute rendering', () => {
+        it ('renders @-prefixed keys as XML attributes', async () => {
+            const response   = buildResponseMock();
+            const controller = new FooController({query: {_format: 'xml'}}, response);
+            controller.formatResponseBody = body => body;
+
+            await controller.render({Record: {'@track': 'both', '@trim': 'do-not-trim'}});
+
+            expect(response.send).toHaveBeenCalledWith(
+                expect.stringContaining('<Record track="both" trim="do-not-trim"/>')
+            );
+        });
+
+        it ('still renders an ordinary key as a child element', async () => {
+            const response   = buildResponseMock();
+            const controller = new FooController({query: {_format: 'xml'}}, response);
+            controller.formatResponseBody = body => body;
+
+            await controller.render({Record: {'weird key!': 'x'}});
+
+            expect(response.send).toHaveBeenCalledWith(
+                expect.stringContaining('<weird_key_>x</weird_key_>')
+            );
+        });
     });
 
 

package/test/server/controllerMixins/requestDetails.test.js

@@ -88,6 +88,72 @@ describe('VidaServerController', () => {
         });
 
 
+        describe('#requestHost', () => {
+            it ('returns the host request header', () => {
+                request.headers.host = `${TestHelpers.Faker.Text.randomString()}.vida.dev`;
+                expect(controller.requestHost).toEqual(request.headers.host);
+            });
+        });
+
+
+        describe('#forwardedProtocol', () => {
+            it ('returns null when the proxy sends no forwarded protocol', () => {
+                delete request.headers['x-forwarded-proto'];
+                expect(controller.forwardedProtocol).toBe(null);
+            });
+
+            it ('returns the forwarded protocol', () => {
+                request.headers['x-forwarded-proto'] = 'https';
+                expect(controller.forwardedProtocol).toEqual('https');
+            });
+
+            it ('returns only the first entry of a forwarded protocol chain', () => {
+                request.headers['x-forwarded-proto'] = 'https, http';
+                expect(controller.forwardedProtocol).toEqual('https');
+            });
+        });
+
+
+        describe('#isProxiedRequest', () => {
+            it.each([
+                ['x-forwarded-for is present', '203.0.113.7', true],
+                ['x-forwarded-for is absent',  undefined,     false],
+            ])('returns %s -> %s', (_label, forwardedFor, expected) => {
+                delete request.headers['x-forwarded-for'];
+                if (forwardedFor) request.headers['x-forwarded-for'] = forwardedFor;
+                expect(controller.isProxiedRequest).toBe(expected);
+            });
+        });
+
+
+        describe('#requestUrl', () => {
+            beforeEach(() => {
+                request.headers.host = 'api.vida.dev';
+                request.originalUrl  = '/things?page=2';
+                request.protocol     = 'http';
+                delete request.headers['x-forwarded-proto'];
+                delete request.headers['x-forwarded-for'];
+            });
+
+            it ('uses the forwarded protocol when the proxy sends one', () => {
+                request.headers['x-forwarded-proto'] = 'https';
+                request.headers['x-forwarded-for']   = '203.0.113.7';
+                expect(controller.requestUrl).toEqual('https://api.vida.dev/things?page=2');
+            });
+
+            // Not every balancer forwards X-Forwarded-Proto, so a proxied request can look like
+            // plain http even though the caller addressed an https URL.
+            it ('assumes https for a proxied request that carries no forwarded protocol', () => {
+                request.headers['x-forwarded-for'] = '203.0.113.7';
+                expect(controller.requestUrl).toEqual('https://api.vida.dev/things?page=2');
+            });
+
+            it ('keeps the connection protocol for a direct request with no proxy headers', () => {
+                expect(controller.requestUrl).toEqual('http://api.vida.dev/things?page=2');
+            });
+        });
+
+
         describe('#statusCode', () => {
             it ('returns the response status code', () => {
                 expect(controller.statusCode).toEqual(response.statusCode);

package/test/utils/envFile.test.js

@@ -0,0 +1,46 @@
+const { loadEnvFile } = require('../../lib/utils/envFile');
+
+
+const fixturePath = `${__dirname}/helpers/envFile.fixture`;
+const fileKeys    = ['CORE_TEST_ENV_FILE_VALUE', 'CORE_TEST_ENV_FILE_PRESET'];
+
+
+beforeEach(() => {
+    fileKeys.forEach(key => delete process.env[key]);
+});
+
+
+afterEach(() => {
+    fileKeys.forEach(key => delete process.env[key]);
+});
+
+
+describe('utils/envFile', () => {
+    describe('loadEnvFile', () => {
+        it ('does nothing and reports false when given no path', () => {
+            expect(loadEnvFile(undefined)).toBe(false);
+            expect(process.env.CORE_TEST_ENV_FILE_VALUE).toBeUndefined();
+        });
+
+
+        it ('throws when the file does not exist', () => {
+            expect(() => loadEnvFile(`${fixturePath}.missing`))
+                .toThrow(`Environment file ${fixturePath}.missing does not exist`);
+        });
+
+
+        it ('loads the variables in the file into the environment', () => {
+            expect(loadEnvFile(fixturePath)).toBe(true);
+            expect(process.env.CORE_TEST_ENV_FILE_VALUE).toEqual('from_file');
+        });
+
+
+        it ('leaves a variable already set in the environment alone', () => {
+            process.env.CORE_TEST_ENV_FILE_PRESET = 'from_environment';
+
+            loadEnvFile(fixturePath);
+
+            expect(process.env.CORE_TEST_ENV_FILE_PRESET).toEqual('from_environment');
+        });
+    });
+});

package/test/utils/helpers/envFile.fixture

@@ -0,0 +1,2 @@
+CORE_TEST_ENV_FILE_VALUE=from_file
+CORE_TEST_ENV_FILE_PRESET=from_file