@vida-global/core 2.0.11 → 2.1.0

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)
+```

package/lib/server/doc/renderer.md

@@ -0,0 +1,115 @@
+# Rendering responses
+
+By default the controller renders the value returned from the action. Render walks the result recursively and calls `toApiResponse(opts)` on anything that defines it, then wraps the result in a standard envelope.
+
+```js
+class User {
+    toApiResponse(opts) {
+        const data = { name: this.name, email: this.email };
+        if (opts.includeTitle) data.title = this.title;
+        return data;
+    }
+}
+
+async getFoo() {
+    const user1    = new User('Bruce', 'bwayne@wayne-enterprises.inc');
+    const user2    = new User('Babs',  'bgordon@wayne-enterprises.inc');
+    return { bar: 1, baz: [user1, user2] };
+}
+```
+
+…produces:
+
+```json
+{
+  "data": {
+    "bar": 1,
+    "baz": [
+      { "name": "Bruce", "email": "bwayne@wayne-enterprises.inc" },
+      { "name": "Babs",  "email": "bgordon@wayne-enterprises.inc" }
+    ]
+  },
+  "status": "ok"
+}
+```
+
+Pass options through to `toApiResponse` by calling `render` explicitly:
+
+```js
+await this.render(response, { includeTitle: true });
+```
+
+## Status code helpers
+
+Don't set `this.statusCode` directly — use the helper that pairs the status with `render`:
+
+| Status | Helper |
+|---|---|
+| 201 Created | `this.renderCreationSuccessful(body)` |
+| 202 Accepted | `this.renderAccepted(body)` |
+| 204 No Content | `this.renderNoConent(body)` |
+| 301 Moved Permanently | `this.renderMovedPermanently(body)` |
+| 302 Found | `this.renderFound(body)` |
+| 304 Not Modified | `this.renderNotModified(body)` |
+| 307 Temporary Redirect | `this.renderTemporaryRedirect(body)` |
+| 308 Permanent Redirect | `this.renderPermanentRedirect(body)` |
+| 401 Unauthorized | `this.renderUnauthorized(message, body)` |
+| 402 Payment Required | `this.renderPaymentRequired(message, body)` |
+| 403 Forbidden | `this.renderForbidden(message, body)` |
+| 404 Not Found | `this.renderNotFound(message, body)` |
+| 405 Method Not Allowed | `this.renderMethodNotAllowed(message, body)` |
+| 408 Request Timeout | `this.renderRequestTimeout(message, body)` |
+| 409 Conflict | `this.renderConflict(message, body)` |
+| 410 Gone | `this.renderGone(message, body)` |
+| 413 Content Too Large | `this.renderContentTooLarge(message, body)` |
+| 415 Unsupported Media Type | `this.renderUnsupportedMediaType(message, body)` |
+| 422 Unprocessable Content | `this.renderUnprocessableContent(message, body)` |
+| 423 Locked | `this.renderLocked(message, body)` |
+| 429 Too Many Requests | `this.renderTooManyRequests(message, body)` |
+
+After a render helper runs, the action does not need to return — the response has already been sent.
+
+
+## Error handling
+
+```js
+await this.renderErrors('Something bad happened',
+                        { password: ['must be > 8 characters', 'must include numbers'] });
+// {data: {errors: {message: "Something bad happened", fields: {password: [...]}}}, status: "bad request"}
+
+await this.renderErrors('Something bad happened');
+// {data: {errors: {message: "Something bad happened"}}, status: "bad request"}
+
+await this.renderErrors({ password: ['must be > 8 characters', 'must include numbers'] });
+// {data: {errors: {fields: {password: [...]}}}, status: "bad request"}
+
+await this.renderUnauthorized('Nope');
+// {data: {message: "Nope"}, status: "unauthorized"}
+
+await this.renderForbidden('You shall not pass');
+// {data: {message: "You shall not pass"}, status: "forbidden"}
+```
+
+Throwing any of `this.Errors.Authorization(msg)`, `this.Errors.Forbidden(msg)`, `this.Errors.NotFound(msg)`, or `this.Errors.Validation(msg, fields)` from anywhere in the call chain triggers the matching render helper. Any other thrown error becomes a 500.
+
+
+## Server-Sent Events / streaming
+
+Use `streamSseResponse` to write a long-lived stream of events instead of a one-shot JSON response. The handler is run with `this` bound to the controller, and `writeStreamEvent(name, data)` emits SSE frames.
+
+```js
+async getEvents() {
+    const ctrl = new AbortController();
+    await this.streamSseResponse(
+        async () => {
+            for await (const evt of this.subscribeToEvents(ctrl.signal)) {
+                this.writeStreamEvent('update', JSON.stringify(evt));
+            }
+        },
+        async (err) => this.logger.error(err),
+        ctrl,
+    );
+}
+```
+
+A trailing `data: [DONE]\n\n` frame is emitted automatically when the handler returns. If the client disconnects, the abort controller (when provided) is aborted.