lumen-framework 3.1.0 → 4.0.0

package/dist/types/packages/controller/index.d.ts

@@ -1,455 +1,206 @@
 import type Serializer from '../serializer';
 import type { Model, ModelClass, Query } from '../database';
 import type { Request, Response } from '../server';
-import type { Controller$opts, Controller$beforeAction, Controller$afterAction } from './interfaces';
+import type { Visibility } from './visibility';
+import type { ControllerOptions, BeforeAction, AfterAction } from './interfaces';
 /**
- * ## Overview
- *
- * The Controller class is responsible for taking in requests from the outside
- * world and returning the appropriate response.
- *
- * Think of a Controller as a server at a restaurant. A client makes a request
- * to an application, that request is routed to the appropriate Controller and
- * then the Controller interprets the request and returns data relative to what
- * the client has request.
- *
- * #### Actions
- *
- * Controller actions are functions that call on a Controller in response to an
- * incoming HTTP request. The job of Controller actions are to return the data
- * that the Lumen Application will respond with.
- *
- * There is no special API for Controller actions. They are simply functions
- * that return a value. If an action returns a Query or Promise the resolved
- * value will be used rather than the immediate return value of the action.
- *
- * Below you will find a table showing the different types of responses you can
- * get from different action return values. Keep in mind, Lumen is agnostic to
- * whether or not the value is returned synchronously or resolved from a
- * Promise.
- *
- * | Return/Resolved Value        | Response                                   |
- * |------------------------------|--------------------------------------------|
- * | Array<Model> or Model        | Serialized JSON String                     |
- * | Array or Object Literal      | JSON String                                |
- * | String Literal               | Plain Text                                 |
- * | Number Literal               | [HTTP Status Code](https://goo.gl/T2lMc7)  |
- * | true                         | [204 No Content](https://goo.gl/GxKoqz)    |
- * | false                        | [401 Unauthorized](https://goo.gl/60QqCW)  |
- *
- * **Built-In Actions**
- *
- * Built-in actions refer to Controller actions that you get for free when
- * extending the Controller class (show, index, create, update, destroy). These
- * actions are highly optimized to load only the attributes and relationships
- * that are defined in the resolved Serializer for a Controller.
- *
- * If applicable, built-in actions support the following features described in
- * the [JSON API specification](http://jsonapi.org/):
- *
- * - [Sorting](http://jsonapi.org/format/#fetching-sorting)
- * - [Filtering](http://jsonapi.org/format/#fetching-filtering)
- * - [Pagination](http://jsonapi.org/format/#fetching-pagination)
- * - [Sparse Fieldsets](http://jsonapi.org/format/#fetching-sparse-fieldsets)
- * - [Including Related Resources](http://jsonapi.org/format/#fetching-includes)
- *
- * **Extending Built-In Actions**
- *
- * Considering the amount of functionality built-in actions provide, you will
- * rarely need to override the default behavior of a built-in action. In the
- * event that you do need to override a built-in action, you have the ability to
- * opt back into the built-in logic by calling the super class.
- *
- * Read actions such as index and show return a Query which allows us to chain
- * methods to the super call. In the following example  we will extend the
- * default behavior of the index action to only match records that meet an
- * additional hard-coded set of conditions. We will still be able to use all of
- * the functionality that the built-in index action provides.
+ * The base class of an app's controllers. A controller handles the requests
+ * for one resource; its built-in actions — `index`, `show`, `create`,
+ * `update`, `destroy`, and the relationship endpoints' `showRelationship` and
+ * `showRelated` — read and write records with sorting, filtering, paging,
+ * `include` and sparse fieldsets, so a controller is mostly configuration:
  *
  * ```javascript
  * // app/controllers/posts.js
  * import { Controller } from 'lumen-framework';
  *
  * class PostsController extends Controller {
- *    index(request, response) {
- *      return super.index(request, response).where({
- *        isPublic: true
- *      });
- *    }
- *  }
- *
- *  export default PostsController;
- * ```
- *
- * **Custom Actions**
- *
- * Sometimes it is necessary to add a custom action to a Controller. Lumen allows
- * you to do so by adding an instance method to a Controller. In the following
- * example you will see how to add a custom action with the name `check` to a
- * Controller. We are implementing this action to use as a health check for the
- * application so we want to return the `Number` literal `204`.
- *
- * ```javascript
- * // app/controllers/health.js
- * import { Controller } from 'lumen-framework';
- *
- * class HealthController extends Controller {
- *   async check() {
- *     return 204;
- *   }
- * }
- *
- * export default HealthController;
- * ```
- *
- * The example above is nice but we can make the code a bit more concise with an
- * Arrow `Function`.
- *
- * ```javascript
- * // app/controllers/health.js
- * import { Controller } from 'lumen-framework';
- *
- * class HealthController extends Controller {
- *   check = async () => 204;
- * }
- *
- * export default HealthController;
- * ```
- *
- * Using an Arrow Function instead of a traditional method Controller can be
- * useful when immediately returning a value. However, there are a few downsides
- * to using an Arrow `Function` for a Controller action, such as not being able
- * to call the `super class`. This can be an issue if you are looking to extend
- * a built-in action.
- *
- * Another use case for a custom action could be to return a specific scope of
- * data from a `Model`. Let's implement
- * a custom `drafts` route on a `PostsController`.
- *
- * ```javascript
- * // app/controllers/posts.js
- * import { Controller } from 'lumen-framework';
- * import Post from 'app/models/posts';
- *
- * class PostsController extends Controller {
- *   drafts() {
- *     return Post.where({
- *       isPublic: false
- *     });
- *   }
+ *   params = ['title', 'body', 'user'];
+ *   sort = ['title', 'createdAt'];
+ *   maxPerPage = 50;
  * }
  *
  * export default PostsController;
  * ```
  *
- * While the example above works, we would have to implement all the custom
- * logic that we get for free with built-in actions. Since we aren't getting too
- * crazy with our custom action we can likely just call the `index` action and
- * chain a `.where()` to it.
+ * Override a built-in action, or add a custom one, with a method that takes
+ * `(request, response)`. `index` and `show` return a {@link Query}, so an
+ * override can narrow it and keep everything else:
  *
  * ```javascript
- * // app/controllers/posts.js
- * import { Controller } from 'lumen-framework';
- *
  * class PostsController extends Controller {
- *   drafts(request, response) {
- *     return this.index(request, response).where({
- *       isPublic: false
- *     });
+ *   index(request, response) {
+ *     return super.index(request, response).where({ isPublic: true });
  *   }
  * }
- *
- * export default PostsController;
  * ```
  *
- * Now we can sort, filter, and paginate our custom `drafts` route!
- *
- * #### Middleware
- *
- * Middleware can be a very powerful tool in many Node.js server frameworks. Lumen
- * is no exception. Middleware can be used to execute logic before or after a
- * Controller action is executed.
- *
- * There are two hooks where you can execute middleware functions,
- * `beforeAction` and `afterAction`. Functions added to the `beforeAction` hook
- * will execute before the Controller action and functions added to the
- * `afterAction` hook will be executed after the `Controller` action.
- *
- * **Context**
- *
- * Middleware functions will be bound to the Controller they are added to upon
- * the start of an Application.
- *
- * Due to the lexical binding of arrow functions, if you need to use the `this`
- * keyword within a middleware function, declare the middleware function using
- * the `function` keyword and not as an arrow function.
- *
- * **Scoping Middleware**
- *
- * Middleware is scoped by Controller and includes a parent Controller's
- * middleware recursively until the parent Controller is the root
- * `ApplicationController`. This allows you to implement custom logic that can
- * be executed for resources, namespaces, or an entire Application.
- *
- * Let's say we want to require authentication for every route in our
- * Application. All we have to do is move our authentication middleware function
- * from the example above to the `ApplicationController`.
- *
- * ```javascript
- * // app/controllers/application.js
- * import { Controller } from 'lumen-framework';
- *
- * class ApplicationController extends Controller {
- *   beforeAction = [
- *     async function authenticate(request) {
- *       if (!request.currentUser) {
- *         // 401 Unauthorized
- *         return false;
- *       }
- *     }
- *   ];
- * }
- *
- * export default ApplicationController;
- * ```
- *
- * **Execuation Order**
- *
- * Understanding the execution order of middleware functions and a `Controller`
- * action is essential to productivity with Lumen. Depending on what you use case
- * is, you may want your function to execute at different times in the
- * `request` / `response` cycle.
- *
- * 1. Parent `Controller` `beforeAction` hooks
- * 2. `Controller` `beforeAction` hooks
- * 3. `Controller` Action
- * 4. `Controller` `afterAction` hooks
- * 5. Parent `Controller` `afterAction` hooks
- *
- * **Modules**
- *
- * It is considered a best practice to define your middleware functions in
- * separate file and export them for use throughout an Application. Typically
- * this is done within an `app/middleware` directory.
- *
- * ```javascript
- * // app/middleware/authenticate.js
- * export default async function authenticate(request) {
- *   if (!request.currentUser) {
- *     // 401 Unauthorized
- *     return false;
- *   }
- * }
- * ```
- *
- * This keeps the Controller code clean, easier to read, and easier to modify.
- *
- * ```javascript
- * // app/controllers/application.js
- * import { Controller } from 'lumen-framework';
- * import authenticate from 'app/middleware/authenticate';
- *
- * class ApplicationController extends Controller {
- *   beforeAction = [
- *     authenticate
- *   ];
- * }
- *
- * export default ApplicationController;
- * ```
- *
- * @class Controller
- * @public
+ * What an action returns becomes the response: a query, record or array of
+ * records is serialized as a JSON:API document; another object or array is
+ * sent as JSON, a string as the body; a number is that status, `true` a
+ * `204 No Content`, `false` a `401 Unauthorized`, and `undefined` a
+ * `404 Not Found`.
+ *
+ * A namespace's `ApplicationController` (`app/controllers/application.js`,
+ * `app/controllers/admin/application.js`) holds what applies to the whole
+ * namespace: its hooks run around every action in it, and it declares the
+ * {@link Controller.visibility} rules and the settings
+ * `rejectUnlistedAttributes`, `rejectUnlistedRelationships` and
+ * `maxIncludeDepth` for every controller in it. See the
+ * [controllers guide](https://github.com/nickschot/lux/blob/main/docs/guides/controllers.md).
  */
 declare class Controller {
     /**
-     * An array of custom query parameter keys that are allowed to reach a
-     * Controller instance from an incoming `HTTP` request.
-     *
-     * For security reasons, query parameters passed to Controller actions from an
-     * incoming request other than sort, filter, and page must have their key
-     * whitelisted.
+     * Query parameters an action may read beyond the JSON:API ones (`sort`,
+     * `filter`, `page`, `include`, `fields`). Any other query parameter is a
+     * `400 Bad Request`. A listed one arrives in `request.params`:
      *
      * ```javascript
-     * class UsersController extends Controller {
-     *   // Allow the following custom query parameters to be used for this
-     *   // Controller's actions.
-     *   query = [
-     *     'cache'
-     *   ];
+     * class PostsController extends Controller {
+     *   query = ['search'];
+     *
+     *   index(request, response) {
+     *     const { search } = request.params;
+     *     const posts = super.index(request, response);
+     *
+     *     return search ? posts.where({ body: search }) : posts;
+     *   }
      * }
      * ```
      *
-     * @property query
-     * @type {Array}
-     * @default []
-     * @public
+     * Name them with a character other than a–z (`search-term`, `searchTerm`):
+     * JSON:API reserves all-lowercase names for itself, and Lumen warns about
+     * them at boot.
      */
     query: Array<string>;
     /**
-     * An array of sort query parameter values that are allowed to reach a
-     * Controller instance from an incoming `HTTP` request.
-     *
-     * If you do not override this property all of the attributes specified in the
-     * Serializer that represents a Controller's resource. If the Serializer
-     * cannot be resolved, this property will default to an empty array.
-     *
-     * @property sort
-     * @type {Array}
-     * @default []
-     * @public
+     * The attributes `?sort=` accepts, each also with `-` for descending.
+     * Defaults to every attribute the controller's serializer outputs; anything
+     * else is a `400 Bad Request`. Each must be a column of the model's table,
+     * or the app refuses to boot.
      */
     sort: Array<string>;
     /**
-     * An array of filter query parameter keys that are allowed to reach a
-     * Controller instance from an incoming `HTTP` request.
-     *
-     * If you do not override this property all of the attributes specified in the
-     * Serializer that represents a Controller's resource. If the Serializer
-     * cannot be resolved, this property will default to an empty array.
-     *
-     * @property filter
-     * @type {Array}
-     * @default []
-     * @public
+     * The attributes `?filter[…]=` accepts. Defaults to every attribute the
+     * controller's serializer outputs; anything else is a `400 Bad Request`.
+     * Each must be a column of the model's table, or the app refuses to boot.
      */
     filter: Array<string>;
     /**
-     * An array of parameter keys that are allowed to reach a Controller instance
-     * from an incoming `POST` or `PATCH` request body.
+     * The attributes and relationships a `POST` or `PATCH` body may set.
      *
-     * If you do not override this property all of the attributes specified in the
-     * Serializer that represents a Controller's resource. If the Serializer
-     * cannot be resolved, this property will default to an empty array.
+     * ```javascript
+     * class PostsController extends Controller {
+     *   params = ['title', 'body', 'user'];
+     * }
+     * ```
      *
-     * @property params
-     * @type {Array}
-     * @default []
-     * @public
+     * An attribute the model has but this list doesn't name is ignored (dropped
+     * from `request.params`), so clients may send read-only attributes back; a
+     * relationship like that is answered with `403 Forbidden`.
+     * {@link Controller.rejectUnlistedAttributes} and
+     * {@link Controller.rejectUnlistedRelationships} change either. A member the
+     * model doesn't have at all is a `400 Bad Request`.
      */
     params: Array<string>;
     /**
-     * Functions to execute on each request handled by a `Controller` before the
-     * `Controller` action is executed.
-     *
-     * Functions added to the `beforeAction` hook behave similarly to `Controller`
-     * actions, however, they are expected to return `undefined`. If a middleware
-     * function returns a value other than `undefined` the `request` / `response`
-     * cycle will end before remaining middleware and/or Controller actions are
-     * executed. This makes the `beforeAction` hook a very powerful tool for
-     * dealing with many common tasks, such as authentication.
-     *
-     * Functions called from the `beforeAction` hook will have `request` and
-     * `response` objects passed as arguments.
-     *
-     * **Example:**
+     * Hooks that run before each action, called with `(request, response)`.
+     * Returning nothing lets the request continue; returning anything else ends
+     * it, with that value as the response (`false` → `401 Unauthorized`, a
+     * number → that status):
      *
      * ```javascript
-     * import { Controller } from 'lumen-framework';
-     *
-     * const UNSAFE_METHODS = /(?:POST|PATCH|DELETE)/i;
-     *
-     * function isAdmin(user) {
-     *   if (user) {
-     *     return user.isAdmin;
-     *   }
-     *
-     *   return false;
-     * }
-     *
-     * async function authentication(request) {
-     *   const { method, currentUser } = request;
-     *   const isUnsafe = UNSAFE_METHODS.test(method);
-     *
-     *   if (isUnsafe && !isAdmin(currentUser)) {
-     *     return false; // 401 Unauthorized if the current user is not an admin.
+     * async function requireUser(request) {
+     *   if (!request.currentUser) {
+     *     return false;
      *   }
      * }
      *
      * class PostsController extends Controller {
-     *   beforeAction = [
-     *     authentication
-     *   ];
+     *   beforeAction = [requireUser];
      * }
-     *
-     * export default PostsController;
      * ```
      *
-     * @property beforeAction
-     * @type {Array}
-     * @default []
-     * @public
+     * The hooks of a namespace's `ApplicationController` run around every action
+     * in the namespace, before the controller's own. Hooks run after the
+     * request's parameters are validated, and are called with `this` as the
+     * controller that declares them (use `function`, not an arrow function, to
+     * read it).
      */
-    beforeAction: Array<Controller$beforeAction>;
+    beforeAction: Array<BeforeAction>;
     /**
-     * Functions to execute on each request handled by a `Controller` after the
-     * `Controller` action is executed.
-     *
-     * Functions called from the `afterAction` hook will have `request` and
-     * `response` objects passed as arguments as well as a third `payload`
-     * argument. The `payload` argument is a reference to the resolved data of
-     * the Controller action that was called within the current `request` /
-     * `response` cycle. You need to explicitly return this `payload` in order for
-     * the afterAction to resolve with it's data. If you return a modified value
-     * from a function added to the `afterAction` hook, that value will be used
-     * instead of the resolved data from the preceding Controller action.
-     * Subsequent hooks called from an `afterAction` hook will will use the value
-     * returned or resolved from the preceding hook. This makes `afterAction` a
-     * great place to modify the data you are sending back to the client.
-     *
-     * **Example:**
+     * Hooks that run after each action, called with
+     * `(request, response, payload)`. `payload` is the action's result — for a
+     * resource, the JSON:API document about to be sent. What a hook returns is
+     * sent instead, and passed to the next hook, so return `payload` when
+     * leaving it as it is:
      *
      * ```javascript
-     * import { Controller } from 'lumen-framework';
-     *
-     * async function addCopyright(request, response, payload) {
-     *   const { action } = request;
-     *
-     *   if (payload && action !== preflight) {
-     *     return {
-     *       ...payload,
-     *       meta: {
-     *         copyright: '2016 (c) Postlight'
-     *       }
-     *     };
+     * async function addVersion(request, response, payload) {
+     *   if (payload && payload.jsonapi) {
+     *     return { ...payload, meta: { ...payload.meta, apiVersion: '2' } };
      *   }
      *
      *   return payload;
      * }
      *
      * class ApplicationController extends Controller {
-     *   afterAction = [
-     *     addCopyright
-     *   ];
+     *   afterAction = [addVersion];
      * }
-     *
-     * export default ApplicationController;
      * ```
      *
-     * @property afterAction
-     * @type {Array}
-     * @default []
-     * @public
+     * A namespace `ApplicationController`'s `afterAction` hooks run after the
+     * controller's own.
      */
-    afterAction: Array<Controller$afterAction>;
+    afterAction: Array<AfterAction>;
     /**
-     * The default amount of items to include per each response of the index
-     * action if a `?page[size]` query parameter is not specified.
-     *
-     * @property defaultPerPage
-     * @type {Number}
-     * @default 25
-     * @public
+     * The page size of `index` when the request gives no `?page[size]=`.
      */
     defaultPerPage: number;
+    /**
+     * The largest `?page[size]=` `index` accepts. A larger one is a
+     * `400 Bad Request`, as is a `page[size]` or `page[number]` below 1.
+     */
+    maxPerPage: number;
+    /**
+     * Answer an attribute the model has but `params` does not list with
+     * `403 Forbidden` (an unsupported update, per JSON:API) instead of ignoring
+     * it. Off by default: clients like ember-data send every attribute back on
+     * save, read-only ones (`createdAt`) included.
+     *
+     * Set on a namespace's `ApplicationController`, it applies to every
+     * controller in the namespace (and in namespaces nested in it) that does not
+     * set it itself — whatever class those controllers extend.
+     *
+     * @default false
+     */
+    rejectUnlistedAttributes: boolean;
+    /**
+     * Answer a relationship the model has but `params` does not list with
+     * `403 Forbidden` (an unsupported update, per JSON:API). Turn it off to
+     * ignore such relationships instead, for clients that send every
+     * `belongsTo` back on save (ember-data). Like `rejectUnlistedAttributes`,
+     * setting it on a namespace's `ApplicationController` sets it for the whole
+     * namespace:
+     *
+     * ```javascript
+     * class ApplicationController extends Controller {
+     *   rejectUnlistedRelationships = false;
+     * }
+     * ```
+     *
+     * @default true
+     */
+    rejectUnlistedRelationships: boolean;
     /**
      * How many relationships deep an `?include` path may go on this
      * controller's routes. `comments.reactions.user` is 3 levels deep; with `1`
      * only direct relationships (`comments`) can be included. Paths deeper than
-     * this are rejected with `400 Bad Request`.
+     * this are rejected with `400 Bad Request`; `0` turns `?include` off.
      *
-     * Set it on `ApplicationController` to change it for the whole app, or on a
-     * single controller to override it there.
+     * Set on a namespace's `ApplicationController`, it applies to every
+     * controller in the namespace (and in namespaces nested in it) that does not
+     * set it itself — whatever class those controllers extend.
      *
      * ```javascript
      * class ApplicationController extends Controller {
@@ -461,10 +212,10 @@ declare class Controller {
      * relationships, and each nested level costs its own queries per request, so
      * keep this small.
      *
-     * @property maxIncludeDepth
-     * @type {Number}
+     * In a namespace without {@link Controller.visibility} rules it defaults to
+     * `0`: nothing there scopes the included records.
+     *
      * @default 3
-     * @public
      */
     maxIncludeDepth: number;
     /**
@@ -489,168 +240,308 @@ declare class Controller {
      * serialize or `include` (down to each controller's `maxIncludeDepth`) has
      * no Serializer in that namespace, listing each missing one.
      *
-     * @property serializerFallback
-     * @type {Boolean}
      * @default true
-     * @public
      */
     serializerFallback: boolean;
     /**
-     * The Serializer to serialize (and validate, and load) related resources of
-     * this Controller's responses with: the related model's Serializer in this
-     * Controller's namespace, falling back to the root one.
+     * Which rows of each type a request may see, declared once per namespace on
+     * its `ApplicationController`. Each rule receives a query of its type and
+     * the request, and returns the query narrowed:
+     *
+     * ```javascript
+     * // app/controllers/application.js
+     * class ApplicationController extends Controller {
+     *   static visibility = {
+     *     posts: query => query.isPublic(),
+     *     comments: (query, { currentUser }) =>
+     *       query.where({ userId: currentUser.id })
+     *   };
+     * }
+     * ```
+     *
+     * Lumen applies the rule wherever it loads rows of that type for a request
+     * in the namespace: `index` and its page links, `show`, `update` and
+     * `destroy` (a hidden record is `404 Not Found`, like a missing one), every
+     * relationship's resource linkage, `included` resources at any depth, and
+     * the related records referenced by a `create` or `update` (a hidden one is
+     * reported as not found). A to-one relationship to a hidden record is
+     * serialized as `null`; a to-many one leaves it out.
+     *
+     * Rules must be synchronous and may only add conditions (`where`, `not`,
+     * `whereBetween`, `whereRaw`, or model scopes built from them). Load what
+     * a rule needs in a `beforeAction` hook and read it from the request.
+     *
+     * A nested namespace follows its parent namespace's rules unless its
+     * `ApplicationController` declares its own — whether that class extends
+     * `Controller` or the parent's `ApplicationController`, and also when the
+     * namespace has no `ApplicationController`. Replace them, or build on them
+     * through `super` in a class that extends the parent's:
+     *
+     * ```javascript
+     * // app/controllers/admin/application.js
+     * class AdminApplicationController extends Controller {
+     *   static visibility = {}; // admins see everything
+     * }
+     *
+     * // app/controllers/members/application.js
+     * class MembersApplicationController extends ApplicationController {
+     *   static visibility = { ...super.visibility, drafts: … };
+     * }
+     * ```
+     *
+     * Declaring `visibility` on any other controller is a boot error: types are
+     * included across controllers, so a rule must hold for the whole
+     * namespace.
+     *
+     * Rules do not apply to queries an application builds itself, such as a
+     * custom action's `Post.where(...)` or a relationship read from a model
+     * (`await post.comments`). Narrow those with `visible()`.
+     *
+     * **Visibility rules and model scopes**
+     *
+     * A model scope (`static scopes` on a Model, e.g. `Post.isPublic()`) is a
+     * reusable piece of a query: it narrows the one query it is called on, and
+     * only when application code calls it. A visibility rule is an access
+     * policy: Lumen applies it to every query it issues for a request. The two
+     * compose — a rule is usually written with a scope.
+     *
+     * |                   | Model scope          | Visibility rule         |
+     * |-------------------|----------------------|-------------------------|
+     * | Declared on       | the Model            | a namespace's           |
+     * |                   |                      | `ApplicationController` |
+     * | Applied           | where code calls it  | to every query Lumen    |
+     * |                   |                      | issues for the request  |
+     * | Sees the request  | no                   | yes                     |
+     * | Per namespace     | no                   | yes                     |
+     * | May use           | any query method     | conditions only         |
+     * | `unscope()`       | removes it           | cannot remove it        |
+     *
+     * Scoping a built-in action is not the same as hiding records. With
+     *
+     * ```javascript
+     * class PostsController extends Controller {
+     *   index(request) {
+     *     return super.index(request).isPublic();
+     *   }
+     * }
+     * ```
+     *
+     * private posts are left out of `GET /posts`, but are still served by
+     * `GET /posts/:id`, listed in the `posts` linkage of a user and in
+     * `included` for `/users?include=posts`, linked from a comment's `post`,
+     * and accepted as the `post` of a new comment. `posts: query =>
+     * query.isPublic()` as a visibility rule closes every one of those paths.
+     *
+     * A namespace without rules, its own or a parent's, gets conservative
+     * defaults: `maxIncludeDepth` is `0` (no includes), resources serve no
+     * relationship or related endpoints unless they ask for them, and the app
+     * warns at boot. `static visibility = {}` declares that a namespace may see
+     * everything, and lifts them.
+     */
+    static visibility: Visibility;
+    /**
+     * Narrow `query` with the visibility rule for its type that applies to
+     * `request`'s namespace, as the built-in actions do.
+     *
+     * ```javascript
+     * class PostsController extends Controller {
+     *   drafts(request) {
+     *     return this.visible(Post.where({ isPublic: false }), request);
+     *   }
+     * }
+     * ```
+     *
+     * @param query - A query of any type.
+     * @param request - The request object.
+     * @returns The same query, narrowed.
+     */
+    visible<Q extends Query<unknown>>(query: Q, request: Request): Q;
+    /**
+     * The Serializer to serialize (and validate the `fields` of) related
+     * resources of this Controller's responses with: the related model's
+     * Serializer in this Controller's namespace, falling back to the root one.
      *
      * Always this Controller's namespace — not its Serializer's, which is the
      * root one when the namespace has no Serializer for this resource.
      *
-     * @method serializerFor
-     * @private
+     * @internal
      */
     serializerFor(model: ModelClass): Serializer<Model>;
     /**
      * The resolved Model for a Controller instance.
      *
-     * @property model
-     * @type {Model}
-     * @private
+     * @internal
      */
     model: ModelClass<Model>;
     /**
      * A reference to the root Controller for the namespace that a Controller
      * instance is a member of.
      *
-     * @property parent
-     * @type {?Controller}
-     * @private
+     * @internal
      */
     parent: Controller | null;
     /**
      * The namespace that a Controller instance is a member of.
      *
-     * @property namespace
-     * @type {String}
-     * @private
+     * @internal
      */
     namespace: string;
     /**
      * The resolved Serializer for a Controller instance.
      *
-     * @property serializer
-     * @type {Serializer}
-     * @private
+     * @internal
      */
     serializer: Serializer<Model>;
     /**
      * A Map instance containing a reference to all the Controller within an
      * Application instance.
      *
-     * @property controllers
-     * @type {Map}
-     * @private
+     * @internal
      */
     controllers: Map<string, Controller>;
+    /**
+     * The visibility rules of this Controller's namespace, resolved at boot
+     * from the `static visibility` of the closest `ApplicationController`, from
+     * its own namespace's up, that declares rules.
+     *
+     * @internal
+     */
+    visibility: Visibility;
+    /**
+     * Whether this Controller's namespace, or one it is nested in, declares
+     * visibility rules — `static visibility = {}` included. Without any, the
+     * namespace gets conservative defaults (see `restrictOpenNamespaces()`).
+     * Resolved at boot.
+     *
+     * @internal
+     */
+    hasVisibilityRules: boolean;
     /**
      * A boolean value representing whether or not a Controller instance has a
      * Model.
      *
-     * @property hasModel
-     * @type {Boolean}
-     * @private
+     * @internal
      */
     hasModel: boolean;
     /**
      * A boolean value representing whether or not a Controller instance is within
      * a namespace.
      *
-     * @property hasNamespace
-     * @type {Boolean}
-     * @private
+     * @internal
      */
     hasNamespace: boolean;
     /**
      * A boolean value representing whether or not a Controller instance has a
      * Serializer.
      *
-     * @property hasSerializer
-     * @type {Boolean}
-     * @private
+     * @internal
      */
     hasSerializer: boolean;
-    constructor({ model, namespace, serializer }: Controller$opts);
+    constructor({ model, namespace, serializer }: ControllerOptions);
     /**
-     * This method supports filtering, sorting, pagination, including
-     * relationships, and sparse fieldsets via query parameters. For more
-     * information, see the [fetching resources](https://goo.gl/q7FVgZ) section of
-     * the JSON API specification.
+     * `GET /posts`: the records, sorted, filtered and paged by the request's
+     * query parameters, with its `include` and `fields`. Visibility rules apply.
      *
-     * @method index
-     * @param {Request} request - The request object.
-     * @param {Response} response - The response object.
-     * @return {Promise} Resolves with an array of Model instances.
-     * @public
+     * @param request - The request.
+     * @param response - The response. Unused by the built-in action, but every
+     * action is called with it, so an override can take it.
+     * @returns A query of the page of records; narrow it in an override.
      */
-    index(req: Request): Query<Array<Model>>;
+    index(request: Request, response?: Response): Query<Array<Model>>;
     /**
-     * This method supports including relationships, and sparse fieldsets via
-     * query parameters. For more information, see the [fetching resources](
-     * https://goo.gl/q7FVgZ) section of the JSON API specification.
-     *
-     * @method show
-     * @param {Request} request - The request object.
-     * @param {Response} response - The response object.
-     * @return {Promise} Resolves with a Model instance with the id equal to the
-     * id url parameter.
-     * @public
+     * `GET /posts/1`: the record with the route's id, with the request's
+     * `include` and `fields`. Visibility rules apply; a record the request may
+     * not see, like a missing one, is a `404 Not Found`.
+     *
+     * @param request - The request.
+     * @param response - The response. Unused by the built-in action, but every
+     * action is called with it, so an override can take it.
+     * @returns A query of the record; narrow it in an override.
      */
-    show(req: Request): Query<Model>;
+    show(request: Request, response?: Response): Query<Model>;
     /**
-     * Create and return a single Model instance that the Controller instance
-     * represents. For more information, see the [creating resources](
-     * https://goo.gl/4Obc9t) section of the JSON API specification.
-     *
-     * @method create
-     * @param {Request} request - The request object.
-     * @param {Response} response - The response object.
-     * @return {Promise} Resolves with the newly created Model instance.
-     * @public
+     * `GET /posts/1/relationships/comments`, a relationship endpoint: resolves
+     * the resource that owns the relationship (`request.route.relationship`),
+     * whose resource linkage is the response.
+     *
+     * The resource is resolved through this controller's `show`, asking for its
+     * primary key only, so whatever `show` enforces holds here too: an override
+     * that narrows its query or rejects the request applies, and a resource the
+     * request may not see is a `404 Not Found`. Hooks see the action
+     * `showRelationship` (`request.route.type` is `relationship`).
+     *
+     * @param request - The request.
+     * @param response - The response. Unused by the built-in action, but every
+     * action is called with it, so an override can take it.
+     * @returns A query of the owning record.
      */
-    create(req: Request, res: Response): Promise<Model>;
+    showRelationship(request: Request, response?: Response): Query<Model>;
     /**
-     * Update and return a single Model instance that the Controller instance
-     * represents. For more information, see the [updating resources](
-     * https://goo.gl/o2ZdOR)section of the JSON API specification.
-     *
-     * @method update
-     * @param {Request} request - The request object.
-     * @param {Response} response - The response object.
-     * @return {Promise} Resolves with the updated Model if changes occur.
-     * Resolves with the number `204` if no changes occur.
-     * @public
+     * `GET /posts/1/comments`, a related endpoint: the resources the
+     * relationship `request.route.relationship` of the record with the route's id
+     * points to.
+     *
+     * The query parameters are those of the related type's controller: for a
+     * to-many relationship they page, sort and filter like its `index`, for a
+     * to-one one they include and select like its `show`. Visibility rules apply
+     * to the related resources; the owning record is resolved with
+     * {@link Controller.showRelationship} first, so one the request may not see
+     * is a `404 Not Found`. Hooks see the action `showRelated`
+     * (`request.route.type` is `related`).
+     *
+     * @param request - The request.
+     * @param response - The response. Unused by the built-in action, but every
+     * action is called with it, so an override can take it.
+     * @returns A query of the related records (to-many), or of the related record
+     * (to-one, resolving with `undefined` when there is none).
+     */
+    showRelated(request: Request, response?: Response): Query<Array<Model>> | Query<Model>;
+    /**
+     * `POST /posts`: creates a record from the request body's attributes and
+     * relationships, after checking that every related record exists and is
+     * visible (a `404 Not Found` otherwise). Answers `201 Created` with a
+     * `Location` header.
+     *
+     * @param request - The request.
+     * @param response - The response, for the status and `Location` header.
+     * @returns Resolves with the new record.
+     */
+    create(request: Request, response: Response): Promise<Model>;
+    /**
+     * `PATCH /posts/1`: updates the record with the route's id from the request
+     * body, after checking that every related record exists and is visible.
+     * A record the request may not see is a `404 Not Found`.
+     *
+     * @param request - The request.
+     * @param response - The response. Unused by the built-in action, but every
+     * action is called with it, so an override can take it.
+     * @returns Resolves with the updated record, or with `204` (`204 No Content`)
+     * when nothing changed.
      */
-    update(req: Request): Promise<number | Model>;
+    update(request: Request, response?: Response): Promise<number | Model>;
     /**
-     * Destroy a single Model instance that the Controller instance represents.
-     * For more information, see the [deleting resources](https://goo.gl/nUZn8t)
-     * section of the JSON API specification.
+     * `DELETE /posts/1`: deletes the record with the route's id. A record the
+     * request may not see is a `404 Not Found`.
      *
-     * @method destroy
-     * @param {Request} request - The request object.
-     * @param {Response} response - The response object.
-     * @return {Promise} Resolves with the number `204`.
-     * @public
+     * @param request - The request.
+     * @param response - The response. Unused by the built-in action, but every
+     * action is called with it, so an override can take it.
+     * @returns Resolves with `204` (`204 No Content`).
      */
-    destroy(req: Request): Promise<number>;
+    destroy(request: Request, response?: Response): Promise<number>;
     /**
-     * Respond to HEAD or OPTIONS requests.
+     * Answers `OPTIONS` requests: `204 No Content`, with the path's methods in
+     * `Allow`.
      *
-     * @method preflight
-     * @param {Request} request - The request object.
-     * @param {Response} response - The response object.
-     * @return {Promise} Resolves with the number `204`.
-     * @public
+     * @param request - The request. Unused.
+     * @param response - The response. Unused by the built-in action, but every
+     * action is called with it, so an override can take it.
+     * @returns Resolves with `204`.
      */
-    preflight(): Promise<number>;
+    preflight(request?: Request, response?: Response): Promise<number>;
 }
 export default Controller;
-export { BUILT_IN_ACTIONS } from './constants';
-export type { Controller$opts, Controller$builtIn, Controller$beforeAction, Controller$afterAction } from './interfaces';
+export { BUILT_IN_ACTIONS, NAMESPACE_SETTINGS } from './constants';
+export { Scope } from './visibility';
+export type { Visibility } from './visibility';
+export type { ControllerOptions, BuiltInAction, BeforeAction, AfterAction } from './interfaces';