@vida-global/core 2.0.1 → 2.0.4

package/lib/server/README.md

@@ -1,50 +1,93 @@
 # VidaServer
-The `VidaServer` is a general purpose wrapper around an `express` server. It initializes standard middleware that we want running on all Vida application servers and leaves hooks for adding additional middleware on subclasses for specific use cases.
+`VidaServer` is a general-purpose wrapper around an `express` server. It initializes the middleware that should run on every Vida application server and exposes hooks that subclasses can override to customize behavior for a specific use case. Routes are not registered by hand — they come from subclasses of `VidaServerController` that the server auto-loads from disk.
 
-## Controllers
-The `VidaServer` works in conjunction with the `VidaServerController`. When a `VidaServer` begins listening, it searches its directory structure (as defined in the `controllerDirectories` getter) for subclasses of `VidaServerController` and autoloads their paths.
 
+## Setup
 
-## Routing
-When a controller is auto loaded, it generates routes based on all methods of the controller that are prefixed with `get`, `post`, `put`, `patch`, or `delete`. 
-The paths for these routes are defined by the directory structure of the controller, the name of the controller, and the name of the method. For example, a method `getFoo` defined on a `BarController` in the directory `/controllers/baz`, will create the route `GET /baz/bar/foo`. “Index” will yield an empty path (e.g. `getIndex` in the previously described controller generates `GET /baz/bar`). However, the default paths can be overridden by defining the `routes` getter.
-Each controller method will have direct access to request and response variables and a logger. Calling `render` will set the response body. It accepts either a string or a JSON object.
+```js
+const { VidaServer } = require('@vida-global/core');
+
+const server = new VidaServer({ port: 3000, host: 'localhost' });
+await server.listen();
+```
+
+On `listen()`, the server walks every path in its `controllerDirectories` getter (default: `./controllers`) and registers every `VidaServerController` subclass it finds. To register controllers from additional directories, override the getter on a `VidaServer` subclass.
+
+```js
+class MyServer extends VidaServer {
+    get controllerDirectories() {
+        return [
+            ...super.controllerDirectories,
+            `${process.cwd()}/admin/controllers`,
+        ];
+    }
+}
 ```
-// defined in the /api/v2 directory
-class UsersController extends ServerController {
 
+
+## Core Concepts
+
+A request is handled by an instance of a `VidaServerController` subclass that the server constructs per request. The controller exposes:
+
+- **Action methods** prefixed with `get`, `post`, `put`, `patch`, `delete`, or `head` — these become routes.
+- **Request state** as getters (`params`, `requestHeaders`, `cookies`, etc.).
+- **Render helpers** for every HTTP status code that needs one.
+- **Callbacks** that run before or after actions for auth, validation setup, cleanup, etc.
+
+Heavy logic lives in a paired helper module under `lib/controllers/...` that mirrors the controller's path; the framework auto-loads it and mixes `InstanceMethods`, `Accessors`, and `StaticMethods` into the controller class.
+
+
+## Routing
+
+When a controller is auto-loaded, every method whose name matches `get|post|put|patch|delete|head` followed by a CamelCase suffix is turned into a route. The path comes from the controller's directory, the controller name, and the method name.
+
+```js
+// defined in ./controllers/api/v2/usersController.js
+class UsersController extends VidaServerController {
     // GET /api/v2/users
     getIndex() {}
 
-    // POST /api/v2/user/:id
-    postRecord() {
+    // GET /api/v2/user/:id  -- "Record" is singularized and gets an :id param
+    getRecord() {
         const user = User.find(this.params.id);
     }
 
+    // GET /api/v2/user/:id/status
+    getRecordStatus() {}
+
     // PUT /api/v2/users/foo
     putFoo() {}
 
-    // Delete /foo/bar/baz
+    // DELETE /foo/bar/baz  -- explicit override
     deleteSomething() {}
 
     static get routes() {
-        return {deleteSomething: '/foo/bar/baz'};
+        return { deleteSomething: '/foo/bar/baz' };
     }
 }
 ```
 
+`Index` produces the empty suffix (so the route is just the controller's prefix). `Record` produces a singularized prefix with an `:id` path parameter.
 
-## Helpers 🚨IMPORTANT🚨
-Controller actions should be kept slim with most of the logic in helper files. Helper files that follow the same directory structure as the controller, but in the `/lib` directory will be auto loaded and can add instance methods and custom accessors.
-```
+
+## Helpers 🚨 IMPORTANT 🚨
+
+Keep controller actions slim. Put detailed logic in a helper file under `lib/controllers/` whose path mirrors the controller's path. The framework auto-loads it and applies `InstanceMethods`, `Accessors`, and `StaticMethods`.
+
+```js
 // ./controllers/api/v2/fooController.js
-class FooController extends ServerController {
+class FooController extends VidaServerController {
     async getBar() {
-        await this.validateParameters({playerNumber: {isInteger: true}});
         return this.doTheThing();
     }
+
+    static parametersForGetBar() {
+        return { playerNumber: { isInteger: true } };
+    }
 }
+```
 
+```js
 // ./lib/controllers/api/v2/fooController.js
 const InstanceMethods = {
     doTheThing() {
@@ -56,7 +99,7 @@ const InstanceMethods = {
     getTheThing() {
         return new User();
     }
-}
+};
 
 const Accessors = {
     playerName: {
@@ -64,157 +107,267 @@ const Accessors = {
             return `Player ${this.params.playerNumber}`;
         }
     }
-}
+};
 
-
-module.exports = {
-    InstanceMethods,
-    Accessors
-}
+module.exports = { InstanceMethods, Accessors };
 ```
 
 
 ## Request Properties
-Within an action, the controller has access to:
-- `this.params` includes:
-  - any parameters from the route (e.g. `/foo/:bar/:baz` would provide `this.params.bar` and `this.params.baz`)
-  - any values from a JSON formatted request body
-  - any URL query parameters
-- `this.requestHeaders` the headers sent with the request
-- `this.responseHeaders` the headers to be sent with the response (can be updated)
-- `this.contentType`
 
+Within an action, the controller exposes:
+
+| Property | Description |
+|---|---|
+| `this.params` | Merged route, query, and JSON-body parameters. Returns a structured clone — mutate freely. |
+| `this.requestHeaders` | Cloned request headers. |
+| `this.responseHeaders` | Outgoing response headers (mutable). |
+| `this.contentType` | Shortcut for `requestHeaders['content-type']`. |
+| `this.userAgent` | Shortcut for `requestHeaders['user-agent']`. |
+| `this.requestId` | Unique request id (added by `express-request-id`). |
+| `this.requestBody` | Raw request body. |
+| `this.requestMethod` | HTTP method. |
+| `this.requestIp` | Client IP address. |
+| `this.url` | Original URL. |
+| `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. |
 
-## Rendering a response
-By default, the controller will render the value returned from the action. It recursively searches the result for any objects with a `toApiResponse` and renders that. For example...
+
+## Cookies
+
+```js
+// All cookies (object)
+const all = this.cookies;
+
+// A single cookie, or null if missing
+const session = this.getCookie('session');
+
+// Set a cookie. Options are passed through to express `res.cookie`.
+this.setCookie('session', token, { httpOnly: true, secure: true, maxAge: 86400_000 });
 ```
+
+
+## Parameter coercion
+
+Use these on the controller instance to normalize inbound params without throwing. Each accepts a `{ fallback }` option (and other shape-specific options) and returns the fallback for unusable input.
+
+```js
+this.hasParam('agentId');                                       // true/false
+this.coerceString(this.params.name, { fallback: 'anonymous' }); // trims; empty -> fallback
+this.coerceBoolean(this.params.enabled, { fallback: false });   // accepts true/false, "true"/"false"/"1"/"0"/"yes"/"no"/"on"/"off"
+this.coerceInteger(this.params.limit,
+                   { min: 1, max: 100, fallback: 25 });          // floors, clamps, nonNegative supported
+this.coerceObject(this.params.filters, { fallback: {} });        // arrays return fallback
+```
+
+
+## Validations
+
+Prefer the static `parametersFor<ActionName>` method on the controller class — the framework runs it before the action and renders a 400 response with structured field errors if anything fails.
+
+```js
+class UsersController extends VidaServerController {
+    static parametersForGetIndex() {
+        return {
+            pageSize: { isInteger: { gte: 1, lte: 100 }, optional: true },
+            email:    { presence: true, isString: { regex: /\S+@\S+\.\S+/ } },
+            role:     { isEnum: { enums: ['admin', 'member', 'guest'] } },
+            title:    { function: this.prototype.validateUniqueTitle },
+        };
+    }
+
+    async getIndex() {
+        // pageSize/email/role/title are already validated when this runs
+    }
+
+    async validateUniqueTitle(title) {
+        if (await User.findByTitle(title)) return 'must be unique';
+    }
+}
+```
+
+If you need to validate values that are constructed mid-action, call `this.validateParameters(...)` directly with the same shape.
+
+### Supported validators
+
+- `{ optional: true }` — skip validation when the value is `undefined`.
+- `{ presence: true }`
+- `{ isInteger: true }` or `{ isInteger: { gte: 0, lte: 100 } }`
+- `{ isString: true }` or `{ isString: { length: { gte: 10, lte: 100 }, regex: /foo/ } }`
+- `{ isBoolean: true }` or `{ isBoolean: false }` (asserts the exact value)
+- `{ isDateTime: true }`
+- `{ isEnum: { enums: ['a', 'b', 'c'], error: 'optional message' } }`
+- `{ function: someFn }` — return a string to flag an error.
+
+
+## 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}
+        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");
-    const response = {bar: 1, baz: [user1, user2]};
-    return response;
+    const user1    = new User('Bruce', 'bwayne@wayne-enterprises.inc');
+    const user2    = new User('Babs',  'bgordon@wayne-enterprises.inc');
+    return { bar: 1, baz: [user1, user2] };
 }
 ```
-...will generate the response
-```
-{data: {bar: 1,
-        baz: [
-            {name: "Bruce", email: "bwayne@wayne-enterprises.inc"},
-            {name: "Babs", email: "bgordon@wayne-enterprises.inc"],
-        ]
-}, status: "ok"}
-```
 
-Additional options can be passed to `toApiResponse` by explicitly calling `render`
-```
-await this.render(response, {includeTitle: true});
+…produces:
+
+```json
+{
+  "data": {
+    "bar": 1,
+    "baz": [
+      { "name": "Bruce", "email": "bwayne@wayne-enterprises.inc" },
+      { "name": "Babs",  "email": "bgordon@wayne-enterprises.inc" }
+    ]
+  },
+  "status": "ok"
+}
 ```
 
-### Other Status Codes
-There is no need to set `statusCode` directly as there are helper methods for all statuses.
+Pass options through to `toApiResponse` by calling `render` explicitly:
+
+```js
+await this.render(response, { includeTitle: true });
 ```
-201 - this.renderCreationSuccessful
-202 - this.renderAccepted
-204 - this.renderNoConent
-301 - this.renderMovedPermanently
-302 - this.renderFound
-304 - this.renderNotModified
-307 - this.renderTemporaryRedirect
-308 - this.renderPermanentRedirect
-401 - this.renderUnauthorizedResponse
-402 - this.renderPaymentRequired
-403 - this.renderForbiddenResponse
-404 - this.renderNotFoundResponse
-405 - this.renderMethodNotAllowed
-408 - this.renderRequestTimeout
-409 - this.renderConflictResponse
-410 - this.renderGone
-413 - this.renderContentTooLarge
-415 - this.renderUnsupportedMediaType
-422 - this.renderUnprocessableContent
-423 - this.renderLocked
-429 - this.renderTooManyRequests
+
+To skip the standard envelope and emit the body verbatim (legacy clients, file-style payloads):
+
+```js
+return await this.render(response, { standardize: false });
 ```
 
+### 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
-HTTP 400
-```
-await this.renderErrors("Something bad happened", {password: ['must be > 8 characters', 'must include numbers']})
-// renders {data: {errors: {message: "Soemthing bad happened", fields: {password: [...]}}}, status: "bad request"}
 
-await this.renderErrors("Something bad happened"})
-// renders {data: {errors: {message: "Soemthing bad happened"}}, status: "bad request"}
+```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({password: ['must be > 8 characters', 'must include numbers']}
-// renders {data: {errors: {fields: {password: [...]}}}, status: "bad request"}
-```
-HTTP 401
-```
-await this.renderUnauthorized("Nope")
-// renders {data: {message: "Nope"}, status: "unauthorized"}
-```
-HTTP 403
-```
-await this.renderForbidden("You shall not pass")
-// renders {data: {message: "You shall not pass"}, status: "forbidden"}
+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"}
 ```
-* _Other statuses detailed above._
 
-Throwing any of `this.Errors.Authorization(msg)`, `this.Errors.Forbidden(msg)`, `this.Errors.NotFound(msg)`, `this.Errors.Validation(msg, errors)` from anywhere in the code will trigger the corresponding error handler. All other errors will generate a 500 error.
+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.
 
 
 ## Callbacks
-Callbacks are methods that will run before or after an action has performed. They can be used for authentication, action setup, etc. If a callback returns false, execution is stopped and no other callbacks or the action are run.
-```
-// This will run on all actions except for getIndex and will halt execution if the environment is production (e.g. development routes)
-this.beforeCallback(() => process.env.NODE_ENV != 'production', {except: 'getIndex'});
 
-// This will run an instance method, `setUpSomeStuff` before every action
-this.beforeCallback('setUpSomeStuff');
+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');
 
-// This will run an instance method, 'cleanupRequest', after `getFoo` and `getBar`
-this.afterCallback('cleanupRequest', {only: ['getFoo', 'getBar']})
+    // Runs `cleanupRequest` after getFoo and getBar
+    this.afterCallback('cleanupRequest', { only: ['getFoo', 'getBar'] });
+}
 ```
 
-## Validations
-The `validateParameters` method can be called to automatically validate parameters based on given criteria. If validation fails, execution is stopped and a response is sent with a 400 code and body `{data: {errors: {field1: [errorMsg]}}, status: "bad request"}`
+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'] });
 ```
-async getFoo() {
-    // validates that the pageSize parameter is an integer greater than or equal to one
-    await this.validateParameters({pageSize: {isInteger: true, gte: 1}});
-}
 
-async postBar() {
-    await this.validateParameters(this.barValidations);
-}
 
-get barValidations() {
-    return {
-        name: {presence: true},
-        role: {isEnum: {enums: ['CEO', 'COO', 'other']}},
-        email: {regex: /\w@\w\.com/},
-        title: {function: this.titleUniqueness}
-    }
-}
+## Server-Sent Events / streaming
 
-titleUniqueness(title) {
-    if (User.findByTitle(title)) return 'must be unique';
+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,
+    );
 }
 ```
 
-### Supported Validations
-- `{presence: true}`
-- `{isInteger: true}`, `{isInteger: {gte: 0, lte: 100}}`
-- `{isDateTime}`
-- `{isEnum: {enums: [a, b, c]}}`
-- `{isString: true}`, `{isString: {length: {gte: 10, lte: 100}, regex: /foo/}}
-- `{function: someFunction}` If the function returns a string, that is considered an error and returned as the validation message
+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.
+
+
+## Advanced
+
+These hooks let a `VidaServer` subclass tune the middleware stack and integrations. Override the getter on the subclass.
+
+| Hook | Default | Purpose |
+|---|---|---|
+| `corsOrigins` | `[]` | List of allowed origins for the Socket.IO server. |
+| `staticFilesDirectory` | `${cwd}/static` | Served under `/static`. |
+| `viewsDirectory` | `${cwd}/views` | Mustache views root. |
+| `jsonParsingMiddleware` | `express.json({...})` | Customize JSON body parsing limits. |
+| `octetStreamLimit` | `'128mb'` | Limit applied to `application/octet-stream` bodies. |
+| `octetStreamParsingMiddleware` | `express.raw({...})` | Full replacement for the octet-stream parser. |
+| `loggingMiddleware` | Vida logging middleware | Replace the request logger. |
+| `connectionAbortedMiddleware` | Silent ECONNABORTED handler | Replace the abort handler. |
+| `setupMiddleware()` | Wires everything above | Override to fully control the middleware order. |
+
+WebSocket helpers expose Socket.IO:
+
+```js
+server.emitWebSocketEvent(channel, eventName, eventData);
+server.addWebSocketEventHandler(eventName, handler);
+```

package/lib/server/controllerImporter.js

@@ -15,7 +15,7 @@ class ControllerImporter extends AbstractAutoImporter {
 
     processImport(obj, directoryPrefix) {
         obj.directoryPrefix = directoryPrefix;
-        obj.autoLoadHelpers();
+        obj.autoLoadMixins();
         obj.autoLoadDocumentation();
     }
 }

package/lib/server/controllerMixins/callbacks.js

@@ -0,0 +1,132 @@
+const APM = require('../../apm');
+
+
+const AUTH_CALLBACK_NAME = 'authenticateRequest';
+
+
+const afterCallbacks        = new Map();
+const afterCallbacksToSkip  = new Map();
+const beforeCallbacks       = new Map();
+const beforeCallbacksToSkip = new Map();
+const callbacksSetup        = new Map();
+
+
+function callbacksListForController(list, controller) {
+    const cls = controller.constructor;
+    if (!list.has(cls)) {
+        list.set(cls, []);
+    }
+    return list.get(cls);
+}
+
+
+function addCallback(controller, callback, options, callbacksList) {
+    const list = callbacksListForController(callbacksList, controller)
+    list.push({ callback, options });
+}
+
+
+function shouldRunCallback(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;
+}
+
+
+async function runCallbacks(callbacksList, callbacksToSkipList, actionName, controller) {
+    let toSkip = callbacksToSkipList.filter(({ callback, options }) => {
+        return shouldRunCallback(actionName, options);
+    });
+    toSkip = toSkip.map(({ callback }) => callback);
+
+    for (const  { callback, options } of callbacksList) {
+        if (!shouldRunCallback(actionName, options)) continue;
+        if (toSkip.includes(callback))               continue;
+        const result = await runCallback(callback, controller)
+        if (result === false) return false;
+    }
+
+    return true;
+}
+
+
+async function runCallback(callback, controller) {
+    if (typeof callback == 'function') return await callback.call(controller);
+    return await controller[callback]();
+}
+
+
+const InstanceMethods = {
+    setupCallbacks() {},
+
+
+    _applyCallbacks() {
+        const cls = this.constructor;
+        if (!callbacksSetup.has(cls)) {
+            this.setupCallbacks();
+            callbacksSetup.set(cls, true)
+        }
+
+        // set up the callbacks when the instance is constructed and prevent it from being called again
+        this.setupCallbacks = undefined;
+    },
+
+
+    beforeCallback(callback, options={}) {
+        addCallback(this, callback, options, beforeCallbacks);
+    },
+
+
+    afterCallback(callback, options={}) {
+        addCallback(this, callback, options, afterCallbacks);
+    },
+
+
+    skipBeforeCallback(callback, options={}) {
+        addCallback(this, callback, options, beforeCallbacksToSkip);
+    },
+
+
+    skipAfterCallback(callback, options={}) {
+        addCallback(this, callback, options, afterCallbacksToSkip);
+    },
+
+
+    async _runCallbacks(type, actionName) {
+        let callbacksList, callbacksToSkipList;
+
+        switch(type) {
+            case 'after':
+                callbacksList       = callbacksListForController(afterCallbacks, this);
+                callbacksToSkipList = callbacksListForController(afterCallbacksToSkip, this);
+                break;
+            case 'before':
+                callbacksList       = callbacksListForController(beforeCallbacks, this);
+                callbacksToSkipList = callbacksListForController(beforeCallbacksToSkip, this);
+                break;
+        }
+
+        return await APM.startSegment(`${type}Callbacks`, true, () => {
+            return runCallbacks(callbacksList, callbacksToSkipList, actionName, this);
+        })
+    },
+
+
+    isAuthenticatedAction(actionName) {
+        const list  = callbacksListForController(beforeCallbacks, this);
+        const entry = list.find(({ callback }) => callback === AUTH_CALLBACK_NAME);
+        if (!entry) return false;
+        return shouldRunCallback(actionName, entry.options);
+    }
+}
+
+
+module.exports = { InstanceMethods };

package/lib/server/controllerMixins/documentation.js

@@ -0,0 +1,36 @@
+const { camelize }  = require('inflection');
+
+
+const StaticMethods = {
+    documentationForAction(actionName) {
+        const methodName = this.documentationMethodForAction(actionName);
+        if (this[methodName]) return this[methodName]();
+        return null;
+    },
+
+
+    documentationMethodForAction(actionName) {
+        return `document${camelize(actionName)}`;
+    },
+
+
+    isAuthenticatedAction(actionName) {
+        const controller = new this();
+        return controller.isAuthenticatedAction(actionName);
+    },
+
+
+    _authenticationDocumentation(actionName) {
+        if (!this.isAuthenticatedAction(actionName)) return undefined;
+    },
+
+
+    authenticationDocumentation(actionName) {
+        return {apiKeyAuth: []};
+    }
+}
+
+
+module.exports = {
+    StaticMethods
+}