docs: Server-side hook documentation improvements

doc/api/hooks_server-side.md

@@ -58,24 +58,34 @@ Run during startup after the named plugin is initialized.
 
 Context properties: None
 
-## expressConfigure
+## `expressConfigure`
-Called from: src/node/hooks/express.js
 
-Things in context:
+Called from: `src/node/hooks/express.js`
 
-1. app - the main application object
+Called during server startup just after the
+[`express-session`](https://www.npmjs.com/package/express-session) middleware is
+added to the Express Application object. Use this hook to add route handlers or
+middleware that executes after `express-session` state is created and
+authentication is performed.
 
-This is a helpful hook for changing the behavior and configuration of the application. It's called right after the application gets configured.
+Context properties:
 
-## expressCreateServer
+* `app`: The Express [Application](https://expressjs.com/en/4x/api.html#app)
-Called from: src/node/hooks/express.js
+  object.
 
-Things in context:
+## `expressCreateServer`
 
-1. app - the main express application object (helpful for adding new paths and such)
+Called from: `src/node/hooks/express.js`
-2. server - the http server object
 
-This hook gets called after the application object has been created, but before it starts listening. This is similar to the expressConfigure hook, but it's not guaranteed that the application object will have all relevant configuration variables.
+Identical to the `expressConfigure` hook (the two run in parallel with each
+other) except this hook's context includes the HTTP Server object.
+
+Context properties:
+
+* `app`: The Express [Application](https://expressjs.com/en/4x/api.html#app)
+  object.
+* `server`: The [http.Server](https://nodejs.org/api/http.html#class-httpserver)
+  or [https.Server](https://nodejs.org/api/https.html#class-httpsserver) object.
 
 ## expressCloseServer
 
@@ -235,47 +245,52 @@ Things in context:
 
 I have no idea what this is useful for, someone else will have to add this description.
 
-## preAuthorize
+## `preAuthorize`
-Called from: src/node/hooks/express/webaccess.js
 
-Things in context:
+Called from: `src/node/hooks/express/webaccess.js`
 
-1. req - the request object
+Called for each HTTP request before any authentication checks are performed. The
-2. res - the response object
+registered `preAuthorize` hook functions are called one at a time until one
-3. next - bypass callback. If this is called instead of the normal callback then
+explicitly grants or denies the request by returning `true` or `false`,
-   all remaining access checks are skipped.
+respectively. If none of the hook functions return anything, the access decision
+is deferred to the normal authentication and authorization checks.
 
-This hook is called for each HTTP request before any authentication checks are
+Example uses:
-performed. Example uses:
 
 * Always grant access to static content.
 * Process an OAuth callback.
 * Drop requests from IP addresses that have failed N authentication checks
   within the past X minutes.
 
-A preAuthorize function is always called for each request unless a preAuthorize
+Return values:
-function from another plugin (if any) has already explicitly granted or denied
-the request.
 
-You can pass the following values to the provided callback:
+* `undefined` (or `[]`) defers the access decision to the next registered
+  `preAuthorize` hook function, or to the normal authentication and
+  authorization checks if no more `preAuthorize` hook functions remain.
+* `true` (or `[true]`) immediately grants access to the requested resource,
+  unless the request is for an `/admin` page in which case it is treated the
+  same as returning `undefined`. (This prevents buggy plugins from accidentally
+  granting admin access to the general public.)
+* `false` (or `[false]`) immediately denies the request. The `preAuthnFailure`
+  hook will be called to handle the failure.
 
-* `[]` defers the access decision to the normal authentication and authorization
+Context properties:
-  checks (or to a preAuthorize function from another plugin, if one exists).
+
-* `[true]` immediately grants access to the requested resource, unless the
+* `req`: The Express [Request](https://expressjs.com/en/4x/api.html#req) object.
-  request is for an `/admin` page in which case it is treated the same as `[]`.
+* `res`: The Express [Response](https://expressjs.com/en/4x/api.html#res)
-  (This prevents buggy plugins from accidentally granting admin access to the
+  object.
-  general public.)
+* `next`: Callback to immediately hand off handling to the next Express
-* `[false]` immediately denies the request. The preAuthnFailure hook will be
+  middleware/handler, or to the next matching route if `'route'` is passed as
-  called to handle the failure.
+  the first argument. Do not call this unless you understand the consequences.
 
 Example:
 
-```
+```javascript
-exports.preAuthorize = (hookName, context, cb) => {
+exports.preAuthorize = async (hookName, {req}) => {
-  if (ipAddressIsFirewalled(context.req)) return cb([false]);
+  if (await ipAddressIsFirewalled(req)) return false;
-  if (requestIsForStaticContent(context.req)) return cb([true]);
+  if (requestIsForStaticContent(req)) return true;
-  if (requestIsForOAuthCallback(context.req)) return cb([true]);
+  if (requestIsForOAuthCallback(req)) return true;
-  return cb([]);
+  // Defer the decision to the next step by returning undefined.
 };
 ```