@vida-global/core 2.0.10 → 2.1.0

package/lib/server/controllerMixins/classScopedRegistry.js

@@ -0,0 +1,48 @@
+function appliesToAction(actionName, options) {
+    if (options.only) {
+        if (Array.isArray(options.only)) return options.only.includes(actionName);
+        return options.only == actionName;
+    }
+
+    if (options.except) {
+        if (Array.isArray(options.except)) return !options.except.includes(actionName);
+        return options.except != actionName;
+    }
+
+    return true;
+}
+
+
+class ClassScopedRegistry {
+    #lists = new Map();
+    #setup = new Map();
+
+
+    list(name, controller) {
+        const byClass = this.#listsFor(name);
+        const cls     = controller.constructor;
+        if (!byClass.has(cls)) byClass.set(cls, []);
+        return byClass.get(cls);
+    }
+
+
+    #listsFor(name) {
+        if (!this.#lists.has(name)) this.#lists.set(name, new Map());
+        return this.#lists.get(name);
+    }
+
+
+    applySetupOnce(controller, hookName) {
+        const cls = controller.constructor;
+        if (!this.#setup.has(cls)) {
+            controller[hookName]();
+            this.#setup.set(cls, true);
+        }
+
+        // run the hook once when the instance is constructed and prevent it from being called again
+        controller[hookName] = undefined;
+    }
+}
+
+
+module.exports = { ClassScopedRegistry, appliesToAction };

package/lib/server/controllerMixins/documentation.js

@@ -1,36 +1,68 @@
-const { camelize }  = require('inflection');
+const { ClassScopedRegistry, appliesToAction } = require('./classScopedRegistry');
 
 
-const StaticMethods = {
-    documentationForAction(actionName) {
-        const methodName = this.documentationMethodForAction(actionName);
-        if (this[methodName]) return this[methodName]();
-        return null;
+const registry = new ClassScopedRegistry();
+
+
+const InstanceMethods = {
+    setupDocumentation() {},
+
+
+    _applyDocumentation() {
+        registry.applySetupOnce(this, 'setupDocumentation');
     },
 
 
-    documentationMethodForAction(actionName) {
-        return `document${camelize(actionName)}`;
+    documentationTag(name, options = {}) {
+        registry.list('tags', this).push({ name, options });
     },
 
 
+    tagsForAction(actionName) {
+        return registry.list('tags', this)
+            .filter(({ options }) => appliesToAction(actionName, options))
+            .map(({ name }) => name);
+    }
+}
+
+
+const StaticMethods = {
     isAuthenticatedAction(actionName) {
-        const controller = new this();
+        const controller = new this({}, {});
         return controller.isAuthenticatedAction(actionName);
     },
 
 
     _authenticationDocumentation(actionName) {
         if (!this.isAuthenticatedAction(actionName)) return undefined;
+        return [this.authenticationDocumentation(actionName)];
     },
 
 
     authenticationDocumentation(actionName) {
         return {apiKeyAuth: []};
+    },
+
+
+    _tagsDocumentation(actionName) {
+        const controller = new this({}, {});
+        return controller.tagsForAction(actionName);
+    },
+
+
+    documentationTagDefinitions() {
+        const controller  = new this({}, {});
+        const list        = registry.list('tags', controller);
+        const definitions = new Map();
+        for (const { name, options } of list) {
+            if (!definitions.has(name)) definitions.set(name, options.description || '');
+        }
+        return [...definitions].map(([name, description]) => ({ name, description }));
     }
 }
 
 
 module.exports = {
+    InstanceMethods,
     StaticMethods
 }

package/lib/server/controllerMixins/renderer.js

@@ -1,4 +1,8 @@
-const Errors = require('../errors');
+const { create } = require('xmlbuilder2');
+
+
+const   Errors         = require('../errors');
+const { STATUS_TEXTS } = require('../statusTexts');
 
 
 class StreamInProgressError extends Error {}
@@ -6,25 +10,26 @@ class NoActiveStreamError   extends Error {}
 
 
 const CONTENT_TYPE_BY_EXTENSION = {
-    html:  'text/html; charset=utf-8',
-    htm:   'text/html; charset=utf-8',
     css:   'text/css; charset=utf-8',
+    gif:   'image/gif',
+    htm:   'text/html; charset=utf-8',
+    html:  'text/html; charset=utf-8',
+    ico:   'image/x-icon',
+    jpeg:  'image/jpeg',
+    jpg:   'image/jpeg',
     js:    'application/javascript; charset=utf-8',
-    mjs:   'application/javascript; charset=utf-8',
     json:  'application/json; charset=utf-8',
-    txt:   'text/plain; charset=utf-8',
+    map:   'application/json; charset=utf-8',
+    mjs:   'application/javascript; charset=utf-8',
+    otf:   'font/otf',
     png:   'image/png',
-    jpg:   'image/jpeg',
-    jpeg:  'image/jpeg',
-    gif:   'image/gif',
     svg:   'image/svg+xml',
-    ico:   'image/x-icon',
+    ttf:   'font/ttf',
+    txt:   'text/plain; charset=utf-8',
     webp:  'image/webp',
     woff:  'font/woff',
     woff2: 'font/woff2',
-    ttf:   'font/ttf',
-    otf:   'font/otf',
-    map:   'application/json; charset=utf-8',
+    xml:   'application/xml; charset=utf-8',
 };
 
 
@@ -51,23 +56,46 @@ const InstanceMethods = {
         if (this.isStreaming) return;
 
         if (typeof body == 'string') {
-            this._response.send(body);
+            this.renderTextResponse(body);
         } else {
-            body = await this.processJSONBody(body, options);
+            body = await this._serializeResponseBody(body, options);
 
             const  errors = body.errors || null;
             delete body.errors;
 
-            body = this.formatJSONBody(body, errors, options);
-            this._response.json(body);
+            body = this.formatResponseBody(body, errors, options);
+
+            if (this.isXMLRequest) {
+                this.renderXMLResponse(body);
+            } else {
+                this.renderJSONResponse(body);
+            }
         }
         this.markRendered();
     },
 
 
-    async renderErrors(message, fields) {
-        const errors = {message: null, fields: {}};
+    renderJSONResponse(body) {
+        this.setHeader('content-type', CONTENT_TYPE_BY_EXTENSION.json);
+        this._response.json(body);
+    },
 
+
+    renderXMLResponse(body) {
+        this.setHeader('content-type', CONTENT_TYPE_BY_EXTENSION.xml);
+        const doc = create({ response: body });
+        const xml = doc.end();
+        this._response.send(xml);
+    },
+
+
+    renderTextResponse(body) {
+        this.setHeader('content-type', CONTENT_TYPE_BY_EXTENSION.txt);
+        this._response.send(body);
+    },
+
+
+    async renderErrors(message, fields) {
         if (message && !fields && typeof message == 'object') {
             fields  = message;
             message = null;
@@ -77,50 +105,84 @@ const InstanceMethods = {
           for (const [field, values] of Object.entries(fields)) {
               if (!Array.isArray(values)) fields[field] = [values];
           }
-          errors.fields = fields;
         }
 
+        const errors = this.constructor.formatErrors(message, fields);
         await this.renderBadRequest(message, { errors });
     },
 
 
-    formatJSONBody(body, errors, options) {
-        if (options.standardize === false) return body;
-
-        const response = {data: body, status: this.statusText};
-        if (errors) response.errors = errors;
-
-        return response;
+    formatResponseBody(body, errors, options={}) {
+        return this.constructor.formatResponseBody(body, errors, {
+            statusCode: this.statusCode,
+            statusText: this.statusText,
+        });
     },
 
 
-    async processJSONBody(body, options) {
+    async _serializeResponseBody(body, options) {
         if (body === undefined)               return null;
         if (!body || typeof body != 'object') return body;
 
-        let processedBody;
-
         if (body.toApiResponse) {
             const formattedBody = await body.toApiResponse(options);
-            return await this.processJSONBody(formattedBody, options);
+            return await this._serializeResponseBody(formattedBody, options);
 
         } else if (Array.isArray(body)) {
-            const processed = [];
-            for (const idx in body) {
-                processed.push(await this.processJSONBody(body[idx], options));
-            }
-            return processed;
+            return await this._serializeArrayForResponseBody(body, options);
 
         } else if (body.constructor == Date) {
-            return body.getTime();
+            return await this._serializeDateForResponseBody(body, options);
 
         } else {
-            const processed = {};
-            for (let [key, val] of Object.entries(body)) {
-                processed[key] = await this.processJSONBody(val, options);
+            return await this._serializeDefaultResponseBody(body, options);
+        }
+    },
+
+
+    async _serializeArrayForResponseBody(arr, options) {
+        const children = [];
+        const response = this.isXMLRequest ? {'#': children} : children;
+
+        for (const child of arr) {
+            let serialized = await this._serializeResponseBody(child, options);
+            if (this.isXMLRequest) {
+                serialized = this._wrapXMLArrayItem(child, serialized);
             }
-            return processed;
+            children.push(serialized);
         }
+
+        return response;
+    },
+
+
+    _wrapXMLArrayItem(child, serialized) {
+        const tagName = child?.apiXMLTagName || 'item';
+        return {[tagName]: serialized};
+    },
+
+
+    _serializeDateForResponseBody(date, options) {
+        return date.getTime();
+    },
+
+
+    async _serializeDefaultResponseBody(body, options) {
+        const processed = {};
+        for (let [key, val] of Object.entries(body)) {
+            const outputKey      = this.isXMLRequest ? this._toXMLElementName(key) : key;
+            processed[outputKey] = await this._serializeResponseBody(val, options);
+        }
+        return processed;
+    },
+
+
+    // 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.
+    _toXMLElementName(key) {
+        let name = `${key}`.replace(/[^a-zA-Z0-9_.-]/g, '_');
+        if (!/^[a-zA-Z_]/.test(name)) name = `_${name}`;
+        return name;
     },
 
 
@@ -243,67 +305,45 @@ const InstanceMethods = {
 }
 
 
+const StaticMethods = {
+    formatResponseBody(body, errors, { statusCode, statusText }) {
+        const response = {data: body, status: statusText};
+        if (errors) response.errors = errors;
+
+        return response;
+    },
+
+
+    formatErrors(message, fields) {
+        return { message: message ?? null, fields: fields ?? {} };
+    },
+}
+
+
 const Accessors = {
+    requestedFormat: {
+        get() {
+            const override = `${this.params._format || ''}`.toLowerCase();
+            if (override === 'xml' || override === 'json') return override;
+            if (/\bxml\b/i.test(this.requestHeaders.accept || '')) return 'xml';
+            return 'json';
+        }
+    },
+
+
+    isJSONRequest: {
+        get() { return this.requestedFormat === 'json' }
+    },
+
+
+    isXMLRequest: {
+        get() { return this.requestedFormat === 'xml' }
+    },
+
+
     statusText: {
         get() {
-            switch(this.statusCode) {
-                case 200:
-                    return 'ok';
-                case 201:
-                    return 'created';
-                case 202:
-                    return 'accepted';
-                case 204:
-                    return 'no content';
-                case 301:
-                  return 'moved permanently';
-                case 302:
-                  return 'found';
-                case 304:
-                  return 'not modified';
-                case 307:
-                  return 'temporary redirect';
-                case 308:
-                  return 'permanent redirect';
-                case 400:
-                    return 'bad request'
-                case 401:
-                    return 'unauthorized';
-                case 402:
-                    return 'payment required';
-                case 403:
-                    return 'forbidden';
-                case 404:
-                    return 'not found';
-                case 405:
-                    return 'method not allowed';
-                case 408:
-                    return 'request timeout';
-                case 409:
-                    return 'conflict';
-                case 410:
-                    return 'gone';
-                case 413:
-                    return 'content too large';
-                case 415:
-                    return 'unsupported media type';
-                case 422:
-                    return 'unprocessable content';
-                case 423:
-                    return 'locked';
-                case 429:
-                    return 'too many requests';
-                case 500:
-                    return 'server error';
-                case 501:
-                    return 'not implemented';
-                case 502:
-                    return 'bad gateway';
-                case 503:
-                    return 'service unavailable';
-                case 504:
-                    return 'gateway timeout';
-            }
+            return STATUS_TEXTS[this.statusCode];
         },
     }
 }
@@ -312,6 +352,7 @@ const Accessors = {
 module.exports = {
     Accessors,
     InstanceMethods,
+    StaticMethods,
     NoActiveStreamError,
-    StreamInProgressError 
+    StreamInProgressError
 }

package/lib/server/controllerMixins/validations.js

@@ -101,6 +101,63 @@ const InstanceMethods = {
     },
 
 
+    validateIsNumber(value, options) {
+        if (typeof value == 'string' && !value.match(/^[\s\d,.]+$/)) return 'must be a number';
+        const num = parseFloat(value);
+        if (isNaN(num)) return 'must be a number';
+
+        if (options?.gte !== undefined) {
+            if (num < options.gte) return `must be greater than or equal to ${options.gte}`;
+        }
+        if (options?.lte !== undefined) {
+            if (num > options.lte) return `must be less than or equal to ${options.lte}`;
+        }
+    },
+
+
+    async validateIsArray(value, options) {
+        if (!Array.isArray(value)) return 'must be an array';
+
+        const lengthError = this.validateArrayLength(value, options?.length);
+        if (lengthError) return lengthError;
+
+        if (options?.of) return await this.validateArrayElements(value, options.of);
+    },
+
+
+    validateArrayLength(value, length) {
+        if (length?.gte !== undefined) {
+            if (value.length < length.gte) return `must have at least ${length.gte} items`;
+        }
+        if (length?.lte !== undefined) {
+            if (value.length > length.lte) return `must have at most ${length.lte} items`;
+        }
+    },
+
+
+    async validateArrayElements(value, elementValidations) {
+        for (const element of value) {
+            const errors = await this.validateParameter(element, elementValidations);
+            if (errors.length) return `elements ${errors.join(', ')}`;
+        }
+    },
+
+
+    async validateIsObject(value, options) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) return 'must be an object';
+
+        if (options?.properties) return await this.validateObjectProperties(value, options.properties);
+    },
+
+
+    async validateObjectProperties(value, properties) {
+        for (const [propertyName, propertyValidations] of Object.entries(properties)) {
+            const errors = await this.validateParameter(value[propertyName], propertyValidations);
+            if (errors.length) return `${propertyName} ${errors.join(', ')}`;
+        }
+    },
+
+
     async validateFunction(value, fnc) {
         const error = await fnc.call(this, value);
         if (error) return error;

package/lib/server/doc/callbacks.md

@@ -0,0 +1,23 @@
+# Callbacks
+
+Callbacks are methods that run before or after an action. They are used for authentication, action setup, cleanup, etc. If a callback returns `false`, execution stops and no further callbacks or the action are run. Define callbacks in `setupCallbacks()` on the controller.
+
+```js
+setupCallbacks() {
+    // Runs before every action except getIndex; halts in production
+    this.beforeCallback(() => process.env.NODE_ENV != 'production', { except: 'getIndex' });
+
+    // Runs the `setUpSomeStuff` instance method before every action
+    this.beforeCallback('setUpSomeStuff');
+
+    // Runs `cleanupRequest` after getFoo and getBar
+    this.afterCallback('cleanupRequest', { only: ['getFoo', 'getBar'] });
+}
+```
+
+A subclass can suppress a callback inherited from a parent without removing it for everyone:
+
+```js
+this.skipBeforeCallback('authenticateRequest', { only: 'getHealthCheck' });
+this.skipAfterCallback('logActivity',          { except: ['getRecord'] });
+```

package/lib/server/doc/documentation.md

@@ -0,0 +1,135 @@
+# API Documentation (OpenAPI)
+
+The server can generate an OpenAPI 3.0 specification for every controller action. Documentation is **opt-in per action**: an action only appears in the spec once it has a description. The spec is assembled by `ApiDocsGenerator` (`lib/server/openApi/apiDocsGenerator.js`), which walks every registered controller action and merges the pieces described below.
+
+
+## Describing an action (YAML)
+
+The human-written parts of an operation — its summary, description, and response shapes — live in a YAML file, not in the controller. For each action, `ApiDocGenerator` looks for:
+
+```
+docs/controllers<routePrefix>Controller/<actionName>.yaml
+```
+
+For example, `UsersController` (routed at `/api/v2/users`) documents its `getIndex` action in `docs/controllers/api/v2/usersController/getIndex.yaml`:
+
+```yaml
+summary: List users
+description: Returns a paginated list of users.
+responses:
+  '200':
+    description: A page of users
+    body:
+      users:
+        - ref: User
+      total: 0
+```
+
+An action is only included in the spec when its YAML defines a `description`. Actions with no YAML file (or no `description`) are skipped.
+
+Inside a `responses.<status>.body`, plain values describe the shape directly; an object with a `ref` key emits a `$ref` to a registered component schema (see [Schema references](#schema-references)). If no `responses` are declared, the action defaults to `200` with `Successful response`.
+
+The `body` you write describes only the **`data`** payload, and its shape passes through to the documented schema as-authored (with any `ref` resolved to a `$ref`). The generator then wraps it in the controller's standard response envelope — it feeds your body schema through the controller's own static `formatResponseBody`/`formatErrors` (the same code that shapes runtime responses), so the documented schema always matches what the server returns even when a controller overrides the envelope. For the default envelope, the `getIndex` example above produces:
+
+```yaml
+responses:
+  '200':
+    description: A page of users
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            data:
+              users:
+                - $ref: '#/components/schemas/User'
+              total: 0
+            status:
+              type: string
+              example: ok
+```
+
+Responses with a status `>= 400` additionally document an `errors` object (`{ message, fields }`) inside the envelope. A controller whose envelope spreads the body (rather than nesting it under `data`) instead flattens the body's properties into the envelope's `properties`.
+
+
+## Parameters and request body
+
+Parameters and request bodies are **derived automatically** from the action's `parametersFor<ActionName>` validator definitions (see [Validations](./validations.md)) — there is no need to repeat them in YAML. Each declared parameter is placed by location:
+
+- **Path parameters** — any parameter whose name appears in the route (e.g. `:id`). Always required.
+- **Query parameters** — for `GET`/`DELETE` actions, or any parameter marked `{ queryParameter: true }`.
+- **Request body** — for `POST`/`PUT` actions, declared params become a `requestBody` object schema; non-`optional` params are listed as `required`. The body defaults to `application/json`, but switches to `multipart/form-data` automatically when any body param declares `{ format: 'binary' }` (rendered as `{ type: 'string', format: 'binary' }` — the standard way to document a file upload).
+
+The validator definition itself becomes the parameter's JSON schema, and `example`, `default`, `format`, and `nullable` pass through when present. Set `{ nullable: true }` to document a value that may be `null`.
+
+For a path or query parameter, an `example` is emitted at the **parameter-object** level (a sibling of `schema`), so Swagger UI's "Try it out" pre-fills it. For a request-body property, the `example` stays inside the property's schema.
+
+```js
+static parametersForPostImport() {
+    return {
+        file:  { isString: true, format: 'binary' },       // → multipart/form-data
+        label: { isString: true, optional: true, example: 'Q3 report', nullable: true },
+    };
+}
+```
+
+
+## Tags
+
+Group operations under OpenAPI tags by declaring them in `setupDocumentation()` on the controller. Like callbacks, a tag applies to **every action by default** but honors `only` / `except`:
+
+```js
+setupDocumentation() {
+    // Tag every action in this controller
+    this.documentationTag('Users', { description: 'User management endpoints' });
+
+    // Tag only specific actions
+    this.documentationTag('Admin', { only: ['deleteRecord'] });
+}
+```
+
+Each operation emits a `tags: [...]` list, and the full spec emits a de-duplicated top-level `tags: [{ name, description }]` (the first non-empty description for a name wins; an empty description is omitted). Tags are entirely opt-in — declare none and no `tags` key is produced.
+
+
+## Schema references
+
+To reuse a schema across operations, point a `ref` at a class that exposes a static `documentationSchema()` method. The method returns a bare properties map; the generator wraps it in `{ type: 'object', properties: ... }`, emits a `$ref`, and registers the schema under `components.schemas`:
+
+```js
+class User {
+    static documentationSchema() {
+        return { id: { type: 'integer' }, email: { type: 'string' } };
+    }
+}
+```
+
+```yaml
+responses:
+  '200':
+    description: A single user
+    body:
+      ref: User
+```
+
+The component is named after the class (`User`); set a static `documentationSchemaName` to override it. Referencing two different classes that resolve to the same name throws a duplicate-name error.
+
+
+## Authentication
+
+Actions guarded by authentication (via the `authenticateRequest` before-callback — see [Callbacks](./callbacks.md)) automatically emit `security: [{ apiKeyAuth: [] }]`. The spec declares the matching `apiKeyAuth` security scheme (an `Authorization` header) under `components.securitySchemes`.
+
+
+## The full specification
+
+`ApiDocsGenerator` produces a single OpenAPI 3.0.0 document with this top-level shape:
+
+```
+openapi  — "3.0.0"
+info     — title / version / description (from constructor args, falling back to package.json)
+servers  — [{ url: <server origin> }]
+tags     — de-duplicated tag definitions (omitted when none are declared)
+paths    — every documented action, keyed by endpoint and lowercase method
+components
+  securitySchemes.apiKeyAuth
+  schemas — every referenced documentationSchema (omitted when none are used)
+```