lumen-framework 3.1.1 → 4.0.0

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

@@ -1,182 +1,105 @@
-import type { Logger$RequestLogger } from './request-logger/interfaces';
-import type { Logger$config, Logger$format, Logger$level, Logger$logFn, Logger$filter } from './interfaces';
+import type { RequestLoggerFn } from './request-logger/interfaces';
+import type { LoggerConfig, LogFormat, LogLevel, LogFunction, LogFilter } from './interfaces';
 /**
- * @class Logger
- * @public
+ * The application's logger, configured by the `logging` section of
+ * `config/environments/<environment>.js` ({@link LoggerConfig}). Actions and
+ * hooks reach it as `request.logger`, models as `Model.logger`.
+ *
+ * It logs every request, server errors, and — with the database's `debug` on —
+ * SQL, and has a method per level for the app's own messages. See the
+ * [logging guide](https://github.com/nickschot/lux/blob/main/docs/guides/logging.md).
  */
 declare class Logger {
+    /** The least severe level written: `DEBUG`, `INFO`, `WARN` or `ERROR`. */
+    level: LogLevel;
+    /** `text`, lines for people, or `json`, one object per line. */
+    format: LogFormat;
     /**
-     * The level your application should log (DEBUG, INFO, WARN, or ERROR).
-     *
-     * @property level
-     * @type {String}
-     * @public
-     */
-    level: Logger$level;
-    /**
-     * The output format of log data (text or json).
-     *
-     * @property format
-     * @type {String}
-     * @public
-     */
-    format: Logger$format;
-    /**
-     * Hackers love logs. It's easy to get sensitive user information from log
-     * data if your server has been breached. To prevent leaking sensitive
-     * information in a potential attack, blacklist certain keys that should be
-     * filtered out of the logs.
+     * Parameters to keep out of the logs. A parameter whose name contains
+     * `password`, `secret` or `token`, or a name listed in `filter.params`,
+     * ignoring case, is logged as `[FILTERED]` — in the body, the query string
+     * and inside arrays:
      *
      * ```javascript
-     * // config/environments/development.js
+     * // config/environments/production.js
      * export default {
      *   logging: {
-     *     level: 'DEBUG',
-     *     format: 'text',
-     *     enabled: true,
-     *     filter: {
-     *       params: ['password']
-     *     }
+     *     // …
+     *     filter: { params: ['email'] } // also filters `recoveryEmail`
      *   }
      * };
      * ```
-     *
-     * Now that we've added password to the array of parameters we want to filter
-     * out of the logs, let's try to create a new user.
-     *
-     * ```http
-     * POST /users HTTP/1.1
-     * Content-Type: application/vnd.api+json
-     * Host: 127.0.0.1:4000
-     * Connection: close
-     * User-Agent: Paw/3.0.14 (Macintosh; OS X/10.12.1) GCDHTTPRequest
-     * Content-Length: 188
-     *
-     * {
-     *   "data": {
-     *   "type": "users",
-     *     "attributes": {
-     *       "name": "Zachary Golba",
-     *       "email": "zachary.golba@postlight.com",
-     *       "password": "vcZxniFYyfnFDcLn%nhe8Vrt"
-     *     }
-     *   }
-     * }
-     * ```
-     *
-     * The request above will yield the following log message.
-     *
-     * ```text
-     * [2016-12-10T18:28:04.610Z] Processed POST "/users" from ::ffff:127.0.0.1
-     * with 201 Created by UsersController#create
-     *
-     * Params
-     *
-     * {
-     *   "data": {
-     *     "type": "users",
-     *     "attributes": {
-     *       "name": "Zachary Golba",
-     *       "email": "zachary.golba@postlight.com",
-     *       "password": "[FILTERED]"
-     *     }
-     *   }
-     * }
-     * ```
-     *
-     * It worked! The password value did not leak into the log message.
-     *
-     * @property filter
-     * @type {Object}
-     * @public
      */
-    filter: Logger$filter;
+    filter: LogFilter;
+    /** Whether anything is logged; off in the test environment. */
+    enabled: boolean;
     /**
-     * A boolean flag that determines whether or not the logger is enabled.
-     *
-     * @property enabled
-     * @type {Boolean}
-     * @public
+     * Whether the request log includes the request body — the JSON:API document
+     * of a `POST` or `PATCH`. Off unless enabled, and off by default in
+     * production: a body is large and full of user data. Query and route params
+     * are always logged (filtered).
      */
-    enabled: boolean;
+    requestBody: boolean;
     /**
-     * Log a message at the DEBUG level.
-     *
-     * ```javascript
-     * logger.debug('Hello World!');
-     * // => [6/4/16 5:46:53 PM] Hello World!
-     * ```
-     *
-     * @method debug
-     * @param {any} data - The data you wish to log.
-     * @return {void}
-     * @public
+     * Whether the text format stamps each line with the time. Turn it off where
+     * the platform already does — Heroku prefixes every line with its own — to
+     * avoid two timestamps per line. The JSON format always includes it.
      */
-    debug: Logger$logFn;
+    timestamps: boolean;
     /**
-     * Log a message at the INFO level.
+     * Log a message at `DEBUG`.
+     *
+     * `context` adds fields to the line: top-level fields in JSON, left out of
+     * text. Pass the request's id to tie the message to its request:
      *
      * ```javascript
-     * logger.info('Hello World!');
-     * // => [6/4/16 5:46:53 PM] Hello World!
+     * request.logger.debug('Cache miss', { requestId: request.id });
      * ```
-     *
-     * @method info
-     * @param {any} data - The data you wish to log.
-     * @return {void}
-     * @public
      */
-    info: Logger$logFn;
+    debug: LogFunction;
     /**
-     * Log a message at the WARN level.
+     * Log a message at `INFO`.
+     *
+     * `context` adds fields to the line: top-level fields in JSON, left out of
+     * text. Pass the request's id to tie the message to its request:
      *
      * ```javascript
-     * logger.warn('Good Bye World!');
-     * // => [6/4/16 5:46:53 PM] Good Bye World!
+     * request.logger.info('Synced posts', { requestId: request.id });
      * ```
-     *
-     * @method warn
-     * @param {any} data - The data you wish to log.
-     * @return {void}
-     * @public
      */
-    warn: Logger$logFn;
+    info: LogFunction;
     /**
-     * Log a message at the ERROR level.
+     * Log a message at `WARN`.
+     *
+     * `context` adds fields to the line: top-level fields in JSON, left out of
+     * text. Pass the request's id to tie the message to its request:
      *
      * ```javascript
-     * logger.warn('HELP!');
-     * // => [6/4/16 5:46:53 PM] HELP!
+     * request.logger.warn('Slow upstream', { requestId: request.id });
      * ```
-     *
-     * @method error
-     * @param {any} data - The data you wish to log.
-     * @return {void}
-     * @public
      */
-    error: Logger$logFn;
+    warn: LogFunction;
     /**
-     * Internal method used for logging requests.
+     * Log a message, or an error with its stack, at `ERROR`.
+     *
+     * `context` adds fields to the line: top-level fields in JSON, left out of
+     * text. Pass the request's id to tie the message to its request:
      *
-     * @method request
-     * @param {Request} request
-     * @param {Response} response
-     * @param {Object} opts - An options object.
-     * @param {Number} opts.startTime - The timestamp from when the request was
-     * received.
-     * @return {void}
-     * @private
+     * ```javascript
+     * request.logger.error('Sync failed', { requestId: request.id });
+     * ```
      */
-    request: Logger$RequestLogger;
-    constructor({ level, format, filter, enabled }: Logger$config);
+    error: LogFunction;
+    /** @internal */
+    request: RequestLoggerFn;
+    constructor({ level, format, filter, enabled, requestBody, timestamps }: LoggerConfig);
     /**
-     * @method getTimestamp
-     * @return {String} The current time as an ISO8601 string.
-     * @private
+     * @returns The current time as an ISO8601 string.
+     * @internal
      */
     getTimestamp(): string;
 }
 export default Logger;
 export { default as line } from './utils/line';
-export { default as sql } from './utils/sql';
-export type { Logger$config } from './interfaces';
+export { default as errorName } from './utils/error-name';
+export type { LoggerConfig, LogFilter, LogFormat, LogFunction, LogLevel } from './interfaces';

package/dist/types/packages/logger/interfaces.d.ts

@@ -1,17 +1,59 @@
-export type Logger$level = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
-export type Logger$logFn = (data: string | Record<string, unknown>) => void;
-export type Logger$format = 'text' | 'json';
-export type Logger$data = {
-    level: Logger$level;
+/** A log level, from most to least verbose. */
+export type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+/**
+ * `context` is written alongside the message as top-level fields in JSON
+ * format (e.g. a `requestId` tying an error to its request line); the text
+ * format leaves it out.
+ */
+export type LogFunction = (data: string | Error | Record<string, unknown>, context?: Record<string, unknown>) => void;
+/** Lines for people (`text`) or one JSON object per line (`json`). */
+export type LogFormat = 'text' | 'json';
+export type LogData = {
+    level: LogLevel;
     message?: unknown;
+    context?: Record<string, unknown>;
     timestamp: string;
 };
-export type Logger$filter = {
+/** Parameters to keep out of the logs. */
+export type LogFilter = {
+    /**
+     * Names of parameters to log as `[FILTERED]`, matched by containment and
+     * ignoring case, in addition to `password`, `secret` and `token`.
+     */
     params: string[];
 };
-export type Logger$config = {
-    level: Logger$level;
-    format: Logger$format;
-    filter: Logger$filter;
+/**
+ * The `logging` section of `config/environments/<environment>.js`.
+ *
+ * ```javascript
+ * logging: {
+ *   level: 'INFO',
+ *   format: 'json',
+ *   enabled: true,
+ *   requestBody: false,
+ *   filter: { params: ['email'] }
+ * }
+ * ```
+ *
+ * An unknown `level` or `format` fails the boot.
+ */
+export type LoggerConfig = {
+    /** The least severe level written: `DEBUG` (development), `INFO` (production). */
+    level: LogLevel;
+    /** `text` (development) or `json` (production). */
+    format: LogFormat;
+    /** Parameters to filter, beyond the built-in ones. */
+    filter: LogFilter;
+    /** Whether anything is logged; off in the test environment. */
     enabled: boolean;
+    /**
+     * Whether a request's logged parameters include its body. Defaults to on,
+     * except in production.
+     */
+    requestBody?: boolean;
+    /**
+     * Whether text lines start with the time. Defaults to on; turn it off where
+     * the platform stamps every line itself.
+     */
+    timestamps?: boolean;
 };

package/dist/types/packages/logger/request-logger/index.d.ts

@@ -1,6 +1,4 @@
 import type Logger from '../index';
-import type { Logger$RequestLogger } from './interfaces';
-/**
- * @private
- */
-export declare function createRequestLogger(logger: Logger): Logger$RequestLogger;
+import type { RequestLoggerFn } from './interfaces';
+/** @internal */
+export declare function createRequestLogger(logger: Logger): RequestLoggerFn;

package/dist/types/packages/logger/request-logger/interfaces.d.ts

@@ -1,17 +1,17 @@
 import type { Route } from '../../router';
 import type { Request, Response } from '../../server';
-export type Logger$RequestLogger = (req: Request, res: Response, opts: {
+export type RequestLoggerFn = (req: Request, res: Response, opts: {
     startTime: number;
 }) => void;
-type RequestLogger$stat = {
+type RequestLoggerStat = {
     type: string;
     name: string;
     duration: number;
     controller: string;
 };
-export type RequestLogger$templateData = {
+export type RequestLoggerTemplateData = {
     path: string;
-    stats: Array<RequestLogger$stat>;
+    stats: Array<RequestLoggerStat>;
     route?: Route;
     method: string;
     params: Record<string, unknown>;
@@ -19,7 +19,7 @@ export type RequestLogger$templateData = {
     endTime: number;
     statusCode: string;
     statusMessage: string;
-    remoteAddress: string;
+    remoteAddress?: string;
     colorStr(source: string): string;
 };
 export {};

package/dist/types/packages/logger/request-logger/templates.d.ts

@@ -1,9 +1,5 @@
-import type { RequestLogger$templateData } from './interfaces';
-/**
- * @private
- */
-export declare const debugTemplate: ({ path, stats, route, method, params, colorStr, startTime, endTime, statusCode, statusMessage, remoteAddress }: RequestLogger$templateData) => string;
-/**
- * @private
- */
-export declare const infoTemplate: ({ path, route, method, params, colorStr, startTime, endTime, statusCode, statusMessage, remoteAddress }: RequestLogger$templateData) => string;
+import type { RequestLoggerTemplateData } from './interfaces';
+/** @internal */
+export declare const debugTemplate: ({ path, stats, route, method, params, colorStr, startTime, endTime, statusCode, statusMessage, remoteAddress }: RequestLoggerTemplateData) => string;
+/** @internal */
+export declare const infoTemplate: ({ path, route, method, params, colorStr, startTime, endTime, statusCode, statusMessage, remoteAddress }: RequestLoggerTemplateData) => string;

package/dist/types/packages/logger/request-logger/utils/filter-params.d.ts

@@ -1,4 +1,9 @@
 /**
- * @private
+ * Always filtered, on top of the app's `logging.filter.params`, so a missing
+ * config never leaks credentials into the logs.
+ *
+ * @internal
  */
+export declare const FILTERED_PARAMS: readonly string[];
+/** @internal */
 export default function filterParams(params: Record<string, unknown>, ...filtered: string[]): Record<string, unknown>;

package/dist/types/packages/logger/request-logger/utils/log-json.d.ts

@@ -1,9 +1,7 @@
 import type Logger from '../../index';
 import type { Request, Response } from '../../../server';
-/**
- * @private
- */
-export default function logJSON(logger: Logger, { request: req, response: res }: {
+/** @internal */
+export default function logJSON(logger: Logger, { startTime, request: req, response: res }: {
     startTime: number;
     request: Request;
     response: Response;

package/dist/types/packages/logger/request-logger/utils/log-text.d.ts

@@ -1,8 +1,6 @@
 import type Logger from '../../index';
 import type { Request, Response } from '../../../server';
-/**
- * @private
- */
+/** @internal */
 export default function logText(logger: Logger, { startTime, request: req, response: res }: {
     request: Request;
     response: Response;

package/dist/types/packages/logger/request-logger/utils/params-for.d.ts

@@ -0,0 +1,9 @@
+import type Logger from '../../index';
+import type { Request } from '../../../server';
+/**
+ * The params a request is logged with: filtered, and without the body unless
+ * the logger's `requestBody` is on.
+ *
+ * @internal
+ */
+export default function paramsFor(logger: Logger, req: Request): Record<string, unknown>;

package/dist/types/packages/logger/utils/error-name.d.ts

@@ -0,0 +1,7 @@
+/**
+ * An error's name for the logs. Error subclasses rarely set `name`, so it is
+ * the generic `Error` for nearly all of them; their class name says more.
+ *
+ * @internal
+ */
+export default function errorName(err: unknown): string;

package/dist/types/packages/logger/utils/line.d.ts

@@ -1,4 +1,2 @@
-/**
- * @private
- */
+/** @internal */
 export default function line(strings: readonly string[], ...values: unknown[]): string;

package/dist/types/packages/logger/writer/constants.d.ts

@@ -1,3 +1,2 @@
-export declare const ANSI: RegExp;
 export declare const STDOUT: RegExp;
 export declare const STDERR: RegExp;

package/dist/types/packages/logger/writer/index.d.ts

@@ -1,6 +1,6 @@
-import type { Logger$format } from '../interfaces';
-import type { Logger$Writer } from './interfaces';
-/**
- * @private
- */
-export declare function createWriter(format: Logger$format): Logger$Writer;
+import type { LogFormat } from '../interfaces';
+import type { LogWriter } from './interfaces';
+/** @internal */
+export declare function createWriter(format: LogFormat, { timestamps }?: {
+    timestamps?: boolean;
+}): LogWriter;

package/dist/types/packages/logger/writer/interfaces.d.ts

@@ -1,2 +1,2 @@
-import type { Logger$data } from '../interfaces';
-export type Logger$Writer = (data: Logger$data) => void;
+import type { LogData } from '../interfaces';
+export type LogWriter = (data: LogData) => void;

package/dist/types/packages/logger/writer/utils/format-message.d.ts

@@ -1,4 +1,4 @@
-import type { Logger$format } from '../../interfaces';
+import type { LogFormat } from '../../interfaces';
 /**
  * Returns `string | undefined` because `Error#stack` is optional — the Flow
  * original had the same behaviour, it just did not say so.
@@ -6,4 +6,4 @@ import type { Logger$format } from '../../interfaces';
  * `data` is required here; Flow allowed it to be declared optional ahead of a
  * required parameter, which TypeScript does not (and every caller passes both).
  */
-export default function formatMessage(data: unknown, format: Logger$format): string | undefined;
+export default function formatMessage(data: unknown, format: LogFormat): string | undefined;

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

@@ -1,11 +1,26 @@
 import type { Action } from '../router';
 import type { Request, Response } from '../server';
 /**
- * Convert traditional node HTTP server middleware into a lumen compatible
- * function for use in Controller#beforeAction.
+ * Wrap Connect-style middleware — `(req, res, next)`, the Express
+ * convention — as a {@link Controller.beforeAction} hook.
  *
- * @module lumen-framework
- * @namespace Lumen
- * @function lumenify
+ * ```javascript
+ * import { Controller, lumenify } from 'lumen-framework';
+ *
+ * function poweredBy(req, res, next) {
+ *   res.setHeader('X-Powered-By', 'lumen');
+ *   next();
+ * }
+ *
+ * class ApplicationController extends Controller {
+ *   beforeAction = [lumenify(poweredBy)];
+ * }
+ * ```
+ *
+ * `next()` continues the request and `next(error)` ends it with that error;
+ * ending the response in the middleware ends the request too.
+ *
+ * @param middleware - The middleware to wrap.
+ * @returns A hook that resolves when the middleware calls `next`.
  */
 export default function lumenify(middleware: (req: Request, res: Response, next: (err?: Error) => void) => void): Action<unknown>;

package/dist/types/packages/lumenify/utils/create-response-proxy.d.ts

@@ -3,6 +3,6 @@ import type { Response } from '../../server';
  * Create a Proxy that will trap typical node middleware callback invocations
  * and route them to the appropriate Promise callback (resolve or reject).
  *
- * @private
+ * @internal
  */
 export default function createResponseProxy(res: Response, resolve: (result: unknown) => void): Response;

package/dist/types/packages/pm/cluster/index.d.ts

@@ -1,9 +1,24 @@
 import EventEmitter from 'events';
 import { type Worker } from 'cluster';
 import type Logger from '../../logger';
-import type { Cluster$opts } from './interfaces';
+import type { ClusterOptions } from './interfaces';
 /**
- * @private
+ * Why a worker never started listening.
+ *
+ * @internal
+ */
+export declare class WorkerBootError extends Error {
+    constructor(pid: number | undefined, reason: string);
+}
+/**
+ * Forks the application's worker processes, replaces one that crashes, and
+ * shuts them down gracefully.
+ *
+ * Emits `ready` once every worker of the initial fork is listening, and
+ * `error` (with a `WorkerBootError`) when one of them fails to start instead —
+ * an application that cannot boot should stop, not report it is listening.
+ *
+ * @internal
  */
 declare class Cluster extends EventEmitter {
     path: string;
@@ -11,11 +26,45 @@ declare class Cluster extends EventEmitter {
     logger: Logger;
     workers: Set<Worker>;
     maxWorkers: number;
-    constructor({ path, port, logger, maxWorkers }: Cluster$opts);
-    fork(retry?: boolean): Promise<Worker>;
+    shutdownTimeout: number;
+    /**
+     * Workers being shut down on purpose (a reload or `stop()`), whose exit is
+     * not a crash to replace.
+     */
+    retiring: WeakSet<Worker>;
+    /** Set by `stop()`: no worker is forked or replaced any more. */
+    stopping: boolean;
+    constructor({ path, port, logger, maxWorkers, shutdownTimeout }: ClusterOptions);
+    /**
+     * Fork a worker. Resolves with it once it is listening (or with `null`
+     * when the cluster is full or stopping); rejects with a `WorkerBootError`
+     * when it fails to start — it reports an error, exits, or does not listen
+     * within `BOOT_TIMEOUT` twice in a row.
+     */
+    fork(retry?: boolean): Promise<Worker | null>;
+    /**
+     * A replacement for a crashed worker did not start. With none left, the
+     * application is down: stop, so the platform can restart it.
+     */
+    replacementFailed(err: Error): void;
+    /**
+     * Shut `worker` down gracefully: it stops accepting connections, finishes
+     * the requests in flight, closes its database connections and exits. It is
+     * killed if it has not exited after `shutdownTimeout`.
+     */
     shutdown<T extends Worker>(worker: T): Promise<T>;
-    reload(): any;
-    forkAll(): Promise<Worker>;
+    /**
+     * Shut every worker down gracefully, booting ones included, and fork no
+     * more. Resolves once all have exited.
+     */
+    stop(): Promise<void>;
+    /**
+     * Replace every worker with one running the rebuilt application, two at a
+     * time. A replacement that fails to start is logged, and the cluster keeps
+     * watching: saving a fix reloads again.
+     */
+    reload(): Promise<void>;
+    forkAll(): Promise<Array<Worker | null>>;
 }
 export default Cluster;
-export type { Cluster$opts } from './interfaces';
+export type { ClusterOptions } from './interfaces';

package/dist/types/packages/pm/cluster/interfaces.d.ts

@@ -1,7 +1,8 @@
 import type Logger from '../../logger';
-export type Cluster$opts = {
+export type ClusterOptions = {
     path: string;
     port: number;
     logger: Logger;
     maxWorkers?: number;
+    shutdownTimeout?: number;
 };

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

@@ -1,6 +1,6 @@
 import Cluster from './cluster';
-import type { Cluster$opts } from './cluster';
+import type { ClusterOptions } from './cluster';
 /**
  * @private
  */
-export declare function createCluster({ path, port, logger, maxWorkers }: Cluster$opts): Cluster;
+export declare function createCluster({ path, port, logger, maxWorkers, shutdownTimeout }: ClusterOptions): Cluster;

package/dist/types/packages/router/definitions/context/index.d.ts

@@ -1,11 +1,9 @@
-import type { Router$Namespace } from '../../index';
-import type { Router$DefinitionBuilder } from '../interfaces';
+import type { RouterNamespace } from '../../index';
+import type { RouterDefinitionBuilder } from '../interfaces';
 export type DefinitionContext = {
     [key: string]: (...args: Array<any>) => unknown;
 };
-/**
- * @private
- */
-export declare function contextFor(build: Router$DefinitionBuilder<Router$Namespace>): {
-    create(namespace: Router$Namespace): DefinitionContext;
+/** @internal */
+export declare function contextFor(build: RouterDefinitionBuilder<RouterNamespace>): {
+    create(namespace: RouterNamespace): DefinitionContext;
 };

package/dist/types/packages/router/definitions/context/utils/create-definition-group.d.ts

@@ -1,7 +1,5 @@
-import type { Route$type, Router$Namespace } from '../../../index';
+import type { RouteType, RouterNamespace } from '../../../index';
 type DefinitionFn = (name: string, action?: string) => void;
-/**
- * @private
- */
-export default function createDefinitionGroup<T extends Router$Namespace>(type: Route$type, namespace: T): Record<string, DefinitionFn>;
+/** @internal */
+export default function createDefinitionGroup<T extends RouterNamespace>(type: RouteType, namespace: T): Record<string, DefinitionFn>;
 export {};