@setu-ts/exceptions 0.0.0-stage → 0.10.0

package/src/middleware/error-handler.ts

@@ -0,0 +1,357 @@
+/**
+ * Global error-handler middleware factory.
+ *
+ * Returns a {@linkcode MiddlewareFunction} that wraps `next()` in a try/catch,
+ * so any error thrown by downstream middleware or the route handler is caught,
+ * logged (when a logger is registered), formatted, and sent as a JSON error
+ * response. Register it as the **outermost** middleware (lowest priority number)
+ * so it wraps the entire pipeline.
+ *
+ * @example
+ * ```typescript
+ * import { errorHandler } from '@setu-ts/exceptions';
+ *
+ * app.middleware.add(errorHandler({
+ *   format: 'rfc9457',
+ *   includeStackTrace: config.get('NODE_ENV') === 'development',
+ *   logErrors: true,
+ * }), { priority: 0, name: 'error-handler' });
+ * ```
+ *
+ * @module
+ */
+import type {
+  HandlerResult,
+  ILogger,
+  IRequestContext,
+  IRuntimeServices,
+  MiddlewareFunction,
+} from '@setu-ts/common';
+import {
+  brandErrorResponder,
+  CAPABILITIES,
+  ERROR_RESPONDER_STATE_KEY,
+  httpStatusHintOf,
+  resolveResponseStatus,
+  serializeError,
+} from '@setu-ts/common';
+
+import { HttpError } from '../errors/http-error.ts';
+import { internalServerError, statusTitle } from '../errors/exceptions.ts';
+import {
+  buildErrorFromInit,
+  createErrorResponder,
+  thrownErrorStatus,
+} from './error-responder-impl.ts';
+import {
+  type ErrorFormat,
+  type ErrorHandlerFormatter,
+  selectFormatter,
+} from '../formatters/error-formatter.ts';
+import { rfc9457Formatter } from '../formatters/rfc9457-formatter.ts';
+import { rfc7807Formatter } from '../formatters/rfc7807-formatter.ts';
+
+/**
+ * Options for the {@linkcode errorHandler} middleware factory.
+ *
+ * @since 0.1.0
+ */
+export interface ErrorHandlerOptions {
+  /**
+   * The error body format: `'default'`, `'rfc9457'`, the deprecated
+   * `'rfc7807'`, or a custom formatter function. Defaults to `'default'`.
+   */
+  readonly format?: ErrorFormat | ErrorHandlerFormatter;
+  /**
+   * When `true`, the error `stack` trace is included in the response body.
+   * **Never** enable this in production — pass a config-derived boolean (e.g.
+   * `config.get('NODE_ENV') === 'development'`), never read `process.env`
+   * directly (AI_GUIDELINES §4.1). Defaults to `false`.
+   *
+   * Note the stack is the _secondary_ disclosure: the primary one is the
+   * error **message**, which for a failed query carries the SQL and its bound
+   * parameter values. Masking that is `maskInternalErrors`' job.
+   *
+   * The two compose safely, and masking wins: an error masked by
+   * {@linkcode ErrorHandlerOptions.maskInternalErrors} carries **no** stack in
+   * the body even when this option is `true`, because a stack begins with the
+   * very message that was masked. Set `maskInternalErrors: false` to see the
+   * stack of an internal error.
+   */
+  readonly includeStackTrace?: boolean;
+  /**
+   * When `true` (the default), a caught value that was **not** an
+   * {@linkcode HttpError} and resolves to a status `>= 500` is masked in the
+   * response: its `detail`/`message` becomes the status title
+   * (`'Internal Server Error'`) and the raw message — which for a failed
+   * query carries the SQL and its bound parameter values — is dropped from the
+   * body. The log is unaffected: `logErrors` still records the unmasked error
+   * and its cause chain, so an operator loses nothing unless `logErrors` is
+   * _also_ `false`, the configuration that already logs nothing.
+   *
+   * A deliberately thrown `HttpError` is never masked — `instanceof HttpError`
+   * is the line between "the developer wrote this for a caller" and "this
+   * escaped from a driver". `false` restores the previous behaviour verbatim.
+   */
+  readonly maskInternalErrors?: boolean;
+  /**
+   * When `true` (the default), logs once at `warn` below 500 and `error`
+   * otherwise. Without a logger, only 5xx reaches runtime.reportError.
+   */
+  readonly logErrors?: boolean;
+  /**
+   * Lets the application write its own response for a caught error. The hook
+   * receives the normalized error after status hints, internal-error masking,
+   * and status resolution, so `error.statusCode` is safe to serve. Return a
+   * {@linkcode HandlerResult} produced by `ctx.response` to use that response;
+   * it may resolve that result asynchronously. Return or resolve to `undefined`
+   * to fall through to the configured formatter unchanged.
+   *
+   * The hook owns its returned response's status, headers, and body. It is
+   * called only for errors caught by this middleware, not responder-based
+   * terminals such as an unmatched-path `404`.
+   */
+  readonly respond?: (
+    error: HttpError,
+    ctx: IRequestContext,
+  ) => HandlerResult | undefined | Promise<HandlerResult | undefined>;
+}
+
+/** The `application/problem+json` content type for Problem Details responses. */
+const PROBLEM_JSON = 'application/problem+json';
+/** The default JSON content type. */
+const JSON_CONTENT_TYPE = 'application/json; charset=utf-8';
+
+/**
+ * The formatters whose bodies are Problem Details and therefore require the
+ * `application/problem+json` media type (RFC 9457 §3).
+ *
+ * Membership is keyed on the RESOLVED formatter rather than on the format
+ * string, because both formatters are exported: `format: rfc9457Formatter`
+ * passes a reference and must carry the same media type as `format: 'rfc9457'`.
+ * A body served as `application/json` is ignored by generic problem-details
+ * clients, so a formatter missing from this set is a silent interoperability
+ * defect rather than a visible failure.
+ */
+const PROBLEM_DETAILS_FORMATTERS: ReadonlySet<ErrorHandlerFormatter> = new Set([
+  rfc9457Formatter,
+  rfc7807Formatter,
+]);
+
+/**
+ * Creates a global error-handler middleware.
+ *
+ * Behavior:
+ * 1. Calls `next()` inside a try/catch.
+ * 2. If `next()` throws an `HttpError`, its `statusCode` is used as-is.
+ * 3. If `next()` throws any other `Error`, it is wrapped in a `500`
+ *    `internalServerError` carrying the original as `cause`.
+ * 4. When configured, lets the application write its own response. A returned
+ *    or resolved `HandlerResult` short-circuits formatting; `undefined` falls
+ *    through.
+ * 5. When `logErrors` is on and a logger is registered, the unmasked error is
+ *    logged with the status the selected response serves.
+ * 6. Otherwise, formats the error via {@linkcode selectFormatter}, optionally
+ *    enriches it with a `stack` trace, and sends it with the right status and
+ *    content type. The middleware **returns a `HandlerResult`** (short-circuit)
+ *    and never re-invokes `next()`.
+ *
+ * @param options - Error handler configuration
+ * @returns A middleware function
+ * @since 0.1.0
+ */
+export function errorHandler(options?: ErrorHandlerOptions): MiddlewareFunction {
+  const format = options?.format ?? 'default';
+  const includeStackTrace = options?.includeStackTrace ?? false;
+  const maskInternalErrors = options?.maskInternalErrors ?? true;
+  const logErrors = options?.logErrors ?? true;
+  const respond = options?.respond;
+  const formatter = selectFormatter(format);
+  const contentType = PROBLEM_DETAILS_FORMATTERS.has(formatter) ? PROBLEM_JSON : JSON_CONTENT_TYPE;
+  // The responder is built ONCE at factory time from the formatter and content
+  // type already resolved above, and published per request below: one
+  // `Map.set` of a pre-built object, not a re-resolution (AI_GUIDELINES §14).
+  const responder = createErrorResponder(formatter, contentType);
+
+  const handleError = async (
+    ctx: IRequestContext,
+    next: () => Promise<void>,
+  ): Promise<void | HandlerResult> => {
+    // Publish the responder BEFORE `next()` so every site inside the pipeline
+    // — the kernel's own terminals and every short-circuiting middleware —
+    // answers in this application's configured format (M70f).
+    ctx.state.set(ERROR_RESPONDER_STATE_KEY, responder);
+    try {
+      await next();
+      return;
+    } catch (rawError) {
+      // Normalize: HttpError passes through, anything else becomes a 500.
+      const isHttpError = rawError instanceof HttpError;
+      const error: HttpError = isHttpError
+        ? rawError
+        : internalServerError(
+            rawError instanceof Error ? rawError.message : 'Internal Server Error',
+            rawError instanceof Error ? rawError : undefined,
+          );
+
+      // A thrower that cannot import this package states the status its own
+      // error means by branding it with an `HttpStatusHint` (M89b) — the seam
+      // `@setu-ts/database-plugin` uses for its query-shape refusals, which
+      // are caller errors and were answered as masked 500s. The hint carries
+      // its own caller-safe `detail`, so the response is built from THAT and
+      // never from the error's message, and `buildErrorFromInit` is the same
+      // constructor `respondWithError` reaches: one mapping, one body shape.
+      //
+      // Read only for a non-`HttpError`. A deliberately thrown `HttpError`
+      // already states its own status, and letting a brand override it would
+      // give one error two answers.
+      const hint = isHttpError ? undefined : httpStatusHintOf(rawError);
+
+      // Mask a driver-shaped 500 for the response: the raw message becomes the
+      // status title so the body carries neither the statement nor the values.
+      // A deliberately thrown HttpError is never masked, and a 4xx is left
+      // alone — only a non-HttpError with status >= 500 is rewritten.
+      //
+      // A hinted error is exempt, and the exemption is narrow by construction
+      // rather than by trust: what it serves is the hint's own `detail`, a
+      // fixed sentence the brand site wrote, never the `Error`'s message. So
+      // there is no driver diagnostic in the body for masking to remove. It is
+      // checked FIRST because a hinted 501 satisfies all three masking clauses
+      // and would otherwise be rewritten into the exact symptom this closes.
+      let responseError = error;
+      if (hint !== undefined) {
+        responseError = buildErrorFromInit(hint);
+      } else if (maskInternalErrors && !isHttpError && error.statusCode >= 500) {
+        // Preserve the log's cause chain without leaking the message. `cause`
+        // is `unknown` on `Error`; only an `Error` value is a valid
+        // `HttpError` cause, so narrow rather than cast.
+        const cause = error.cause instanceof Error ? error.cause : undefined;
+        responseError = new HttpError(
+          error.statusCode,
+          statusTitle(error.statusCode),
+          undefined,
+          cause,
+        );
+      }
+
+      // An `HttpError` carries whatever status its thrower passed: the
+      // constructor validates nothing, and its own JSDoc says the factory
+      // functions are what "guarantee a correct status code". So
+      // `throw new HttpError(4004, ...)` — a typo for `404` — reached
+      // `response.status()` and threw `RangeError` out of the one `catch` that
+      // exists to contain throws. The status is clamped BEFORE the log and the
+      // body are built, so the logged status, the body's own status member and
+      // the written status are one number. Rebuilding rather than clamping at
+      // the write also makes `responseError === error` false, which suppresses
+      // the stack — correct by that check's own stated invariant, since the
+      // error being SERVED is no longer the error that was LOGGED.
+      const servedStatus = resolveResponseStatus(thrownErrorStatus(rawError).requested, ctx);
+      if (servedStatus !== responseError.statusCode) {
+        responseError = new HttpError(
+          servedStatus,
+          responseError.message,
+          responseError.details,
+          responseError.cause instanceof Error ? responseError.cause : undefined,
+        );
+      }
+
+      // The hook sees the same safe error and served status that the formatter
+      // would receive. It can perform asynchronous view rendering; only
+      // `undefined` means "use the framework formatter". A hook failure stays
+      // an application failure, but records the original caught diagnostic
+      // before it propagates to the surrounding pipeline.
+      let result: HandlerResult | undefined;
+      try {
+        result = await respond?.(responseError, ctx);
+      } catch (hookError) {
+        if (logErrors) {
+          logError(ctx, error, responseError.statusCode);
+        }
+        throw hookError;
+      }
+      if (result !== undefined) {
+        // The application-owned result can choose a status different from the
+        // normalized error (for example a 418 HTML page for a caught 500), so
+        // inspect the completed writer rather than reporting the fallback.
+        if (logErrors) {
+          logError(ctx, error, ctx.response.snapshot().status);
+        }
+        return result;
+      }
+
+      // Log the unmasked diagnostic and cause chain, with the status the
+      // formatter below will actually serve. A hint may change a normalized
+      // `500` to `501`, so logging the pre-hint status would mislead operators.
+      if (logErrors) {
+        logError(ctx, error, responseError.statusCode);
+      }
+
+      const body = formatter(responseError, ctx);
+      // Masking wins over `includeStackTrace`. A stack's first line is
+      // `<name>: <message>`, so attaching the unmasked error's stack would put
+      // the SQL and its bound parameter values straight back into the body that
+      // was just masked — defeating the mask through the one option documented
+      // as unsafe in production. A masked error therefore carries no stack at
+      // all; the unmasked one is in the log, where `logErrors` already sent it.
+      //
+      // The condition is `responseError === error` rather than `!masked`
+      // because a hinted response is the second case with the same property:
+      // its body deliberately carries the brand site's sentence and not the
+      // error's own text, and a stack's first line is `<name>: <message>`. So
+      // the stack is attached exactly when the error being SERVED is the error
+      // that was LOGGED, which is the invariant both exclusions want.
+      if (includeStackTrace && responseError === error && error.stack !== undefined) {
+        body.stack = error.stack;
+      }
+
+      // Serialize and send via `.send(bytes)` rather than `.json(body)` so
+      // the content-type header we set is not overwritten by json()'s own
+      // `application/json` default — RFC 9457 requires `application/problem+json`.
+      const bytes = new TextEncoder().encode(JSON.stringify(body));
+      return ctx.response
+        .status(responseError.statusCode)
+        .header('content-type', contentType)
+        .send(bytes);
+    }
+  };
+
+  // Brand the middleware with the SAME responder it publishes into `ctx.state`
+  // below, so the kernel can seed it into the state of the pre-pipeline sites
+  // — the drain `503`, the malformed-request `400`, and the request-lifecycle
+  // hooks — which run before this middleware and would otherwise always take
+  // the fallback shape (M70f re-review, findings 1 & 2).
+  brandErrorResponder(handleError, responder);
+  return handleError;
+}
+
+/**
+ * Logs once through the registered logger, or the runtime sink for 5xx when
+ * no logger is registered. Handled 4xx without a logger stays silent.
+ *
+ * @param ctx - The request context
+ * @param error - The error to log, carrying the unmasked message and cause
+ * @param statusCode - The status actually served, which a hint may have changed
+ */
+function logError(ctx: IRequestContext, error: HttpError, statusCode: number): void {
+  if (!ctx.services.has(CAPABILITIES.LOGGER)) {
+    if (statusCode >= 500 && ctx.services.has(CAPABILITIES.RUNTIME)) {
+      ctx.services.get<IRuntimeServices>(CAPABILITIES.RUNTIME).reportError?.({
+        level: 'error',
+        ...serializeError(error),
+        statusCode,
+        requestId: ctx.id,
+        method: ctx.request.method,
+        path: ctx.request.path,
+      });
+    }
+    return;
+  }
+  const logger = ctx.services.get<ILogger>(CAPABILITIES.LOGGER);
+  // Serialize the cause (X2-5): a raw `Error` in log metadata renders as `{}`
+  // under `JSON.stringify` because `message`/`stack` are non-enumerable.
+  logger[statusCode < 500 ? 'warn' : 'error'](error.message, {
+    statusCode,
+    requestId: ctx.id,
+    ...(error.cause !== undefined && { cause: serializeError(error.cause) }),
+  });
+}

package/src/middleware/error-responder-impl.ts

@@ -0,0 +1,192 @@
+/**
+ * The `exceptions` implementation of the request-scoped error responder seam
+ * (M70f).
+ *
+ * This module is **internal**: it is not exported from `src/index.ts`. The
+ * interface it satisfies (`IErrorResponder`), the state key, the init type, and
+ * the `respondWithError` free function all live in `@setu-ts/common`; exporting
+ * the implementation as well would give one concept two public names. A
+ * `barrel-exports.test.ts` assertion pins that it stays out of the barrel.
+ *
+ * @module
+ */
+import type {
+  ErrorResponderTarget,
+  ErrorResponseInit,
+  IErrorResponder,
+  IRequestContext,
+} from '@setu-ts/common';
+import { httpStatusHintOf, resolveResponseStatus } from '@setu-ts/common';
+
+import { HttpError } from '../errors/http-error.ts';
+import { RESPONDER_DETAIL } from '../formatters/problem-details.ts';
+import type { ErrorHandlerFormatter } from '../formatters/error-formatter.ts';
+
+/**
+ * The `application/problem+json` content type for Problem Details responses.
+ *
+ * Mirrors the constant `errorHandler` uses to decide the media type: a
+ * formatter answers Problem Details (and so derives `instance` from the
+ * request path) exactly when its resolved content type is this one.
+ */
+const PROBLEM_JSON = 'application/problem+json';
+
+/** The pure thrown-value rule, shared by serving and request-log prediction. */
+export function thrownErrorStatus(error: unknown): { requested: number; status: number } {
+  const requested =
+    error instanceof HttpError ? error.statusCode : (httpStatusHintOf(error)?.status ?? 500);
+  // Fetch refuses informational responses and bodies on 204, 205 and 304.
+  const status =
+    Number.isInteger(requested) &&
+    requested >= 200 &&
+    requested <= 599 &&
+    requested !== 204 &&
+    requested !== 205 &&
+    requested !== 304
+      ? requested
+      : 500;
+  return { requested, status };
+}
+
+/**
+ * Narrows an {@linkcode ErrorResponderTarget} to a full {@linkcode
+ * IRequestContext} when it genuinely is one.
+ *
+ * The responder is reached two ways. In-pipeline sites — the kernel's terminals
+ * and every short-circuiting middleware — pass the live `IRequestContext`,
+ * which carries `id`, `services`, and `startTime`. The kernel's PRE-pipeline
+ * sites — the shutdown-drain `503` and the malformed-request `400` — pass a
+ * bare target of just `state`, `response`, and an optional safe `request`
+ * path, because no request context exists yet. The three members checked here
+ * are present on every real context and absent from every bare target, so the
+ * test distinguishes the two without a lie.
+ *
+ * @param target - The responder target to test
+ * @returns `true` when the target is a full request context
+ */
+function isFullRequestContext(target: ErrorResponderTarget): target is IRequestContext {
+  const ctx = target as IRequestContext;
+  return (
+    typeof ctx.id === 'string' &&
+    typeof ctx.services === 'object' &&
+    ctx.services !== null &&
+    typeof ctx.startTime === 'number'
+  );
+}
+
+/**
+ * Builds the {@linkcode HttpError} that carries one error response's status,
+ * title and disclosure.
+ *
+ * This is the single owner of that mapping, and it has **two** callers: the
+ * responder below, and `errorHandler`'s status-hint path (M89b), which answers
+ * a thrown error branded with an `HttpStatusHint` — a type that IS an
+ * `ErrorResponseInit`. Sharing it is what makes the two agree: a hinted throw
+ * and a `respondWithError` call carrying the same values produce byte-identical
+ * bodies under `default`, `rfc9457`, `rfc7807` and any custom formatter. A
+ * second hand-rolled construction would silently diverge — the `default`
+ * formatter reads `details.detail` while the Problem Details formatters read
+ * the {@linkcode RESPONDER_DETAIL} symbol, so getting either half wrong loses
+ * the disclosure in exactly one format.
+ *
+ * @param init - The status, title, disclosure and optional structured details
+ * @returns An `HttpError` every formatter renders with the disclosure intact
+ */
+export function buildErrorFromInit(init: ErrorResponseInit): HttpError {
+  // The title is the framework-default `error` member — the `message` of the
+  // `default` format and the `detail` fallback of the Problem Details
+  // formatters — so it stays `error.message`. The disclosure (`init.detail`)
+  // is kept verbatim by every format (the `ErrorResponseInit` contract in
+  // `@setu-ts/common`): it is carried in the error's structured `details`
+  // under a `detail` key, so the `default` format emits it as `details.detail`
+  // beside `message`, and `buildProblemDetails` promotes it to the Problem
+  // Details `detail` member (falling back to the title when a site supplies no
+  // disclosure). `init.details` (e.g. a validation `errors` array) is merged
+  // through unchanged. Carrying it this way — rather than in `error.message` —
+  // keeps the title verbatim, which a site's (non-)disclosure decision depends
+  // on.
+  const details =
+    init.detail !== undefined ? { ...init.details, detail: init.detail } : init.details;
+  const error = new HttpError(init.status, init.title, details);
+  // Mark the error as responder-built and carry the disclosure on a
+  // module-private symbol, which is what `buildProblemDetails` promotes to the
+  // Problem Details `detail` member. The `details.detail` key above is what the
+  // `default` formatter emits (it serializes `details` verbatim); the Problem
+  // Details formatters read the symbol instead, so a THROWN error that happens
+  // to carry a `details.detail` key of its own keeps `detail: <message>` (M70f
+  // code review, finding 4). Non-enumerable so it never reaches a serialized
+  // body.
+  if (init.detail !== undefined) {
+    Object.defineProperty(error, RESPONDER_DETAIL, {
+      value: init.detail,
+      enumerable: false,
+      writable: false,
+      configurable: true,
+    });
+  }
+  return error;
+}
+
+/**
+ * Builds an {@linkcode IErrorResponder} from the formatter and content type
+ * that `errorHandler` has **already** resolved at factory time.
+ *
+ * The responder keeps the `HttpError` construction inside the only package that
+ * owns it: it builds an `HttpError` from the init (so `buildProblemDetails` sees
+ * a real `statusCode` and the validation `errors` extension, and
+ * `maskInternalErrors` would never mask a deliberately 4xx), runs the resolved
+ * formatter over it, and writes status, `content-type` and the serialized body
+ * — the same three-step tail `errorHandler`'s catch path performs.
+ *
+ * @param formatter - The resolved error formatter
+ * @param contentType - The resolved response content type
+ * @returns A responder publishing the application's error format
+ * @since 0.1.0
+ */
+export function createErrorResponder(
+  formatter: ErrorHandlerFormatter,
+  contentType: string,
+): IErrorResponder {
+  return {
+    statusFor: (error: unknown): number => thrownErrorStatus(error).status,
+    respond(target: ErrorResponderTarget, init: ErrorResponseInit): void {
+      // Sanitized before the error is built, not just before the status is
+      // written, so the formatted body's `status` member agrees with the status
+      // actually written. Idempotent, so the common path through
+      // `respondWithError` — which already sanitized — reports nothing twice.
+      const status = resolveResponseStatus(init.status, target);
+      const error = buildErrorFromInit(status === init.status ? init : { ...init, status });
+      // The formatter's `ctx` parameter is a FULL `IRequestContext` by its
+      // contract (M70f re-review round 2, finding 2). The target is a full
+      // context only at the in-pipeline sites; the kernel's pre-pipeline sites
+      // hand over a bare target whose `services`, `id`, `params`, `query`,
+      // `signal` and `startTime` do not exist. Passing that partial object
+      // would let a custom formatter read a documented member and throw
+      // `TypeError: Cannot read properties of undefined` — replacing the
+      // configured 503/400 with an unhandled exception. So the formatter
+      // receives the context only when it genuinely is one, and `undefined`
+      // otherwise — the value its optional `ctx` parameter already declares.
+      const fullContext = isFullRequestContext(target) ? target : undefined;
+      let body = formatter(error, fullContext);
+      // The Problem Details `instance` member comes from the request path. At
+      // the in-pipeline sites the formatter read it off the full context; at
+      // the pre-pipeline sites there is no context, so the responder supplies
+      // the safe path the kernel captured separately — a separate internal
+      // mechanism, since the formatter's optional `ctx` parameter is the only
+      // public channel and it must stay honest (M70f re-review round 2,
+      // finding 2). A malformed request carries no path, in which case the
+      // member is simply absent. A fresh object is composed rather than
+      // mutating the formatter's return value, which a custom formatter may
+      // share or freeze.
+      if (
+        fullContext === undefined &&
+        contentType === PROBLEM_JSON &&
+        target.request !== undefined
+      ) {
+        body = { ...body, instance: target.request.path };
+      }
+      const bytes = new TextEncoder().encode(JSON.stringify(body));
+      target.response.status(status).header('content-type', contentType).send(bytes);
+    },
+  };
+}