@centralping/ergo 0.1.0-beta.1

package/http/logger.js

@@ -0,0 +1,167 @@
+/**
+ * @fileoverview HTTP middleware factory for structured request/response logging.
+ *
+ * Logs request completion events as structured objects to the configured log function.
+ * Each log entry includes operationally essential fields:
+ * - Request: method, URL, headers, client IP, HTTP version, request ID
+ * - Response: status code, duration (ms), headers, and status message
+ * - Host: static machine identity (hostname, arch, platform, pid)
+ *
+ * The request ID is resolved using a three-step chain:
+ * 1. `res.getHeader(headerRequestIdName)` — set by ergo-router's transport layer (primary path)
+ * 2. `req.headers[headerRequestIdName]` — set by an upstream proxy (standalone fallback)
+ * 3. `uuid()` — generates a new UUID when no upstream ID is available
+ *
+ * The response header is only set when not already present, so a transport-layer ID
+ * is never overwritten.
+ *
+ * System metrics (CPU, memory, load average) are intentionally excluded — OTel treats
+ * logs and metrics as distinct observability signals. Collect system metrics via a
+ * dedicated metrics pipeline at periodic intervals, not per-request.
+ *
+ * Environment variables (`process.env`) are intentionally excluded from logs to prevent
+ * accidental secret leakage.
+ *
+ * @module http/logger
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires node:os
+ * @requires node:crypto
+ *
+ * @example
+ * import {compose, logger} from 'ergo';
+ *
+ * const pipeline = compose(
+ *   [logger(), 'log'],
+ *   // On finish logs: {"requestId":"...","method":"GET","url":"/users","statusCode":200,"duration":12,...}
+ * );
+ */
+import {hostname} from 'node:os';
+import {randomUUID} from 'node:crypto';
+
+const DEFAULT_REDACTED = new Set(['authorization', 'proxy-authorization', 'cookie', 'set-cookie']);
+
+/**
+ * @param {object} headers - Header object to redact
+ * @param {Set<string>} redactSet - Header names to replace with '[REDACTED]'
+ * @returns {object} - Copy with sensitive values replaced
+ */
+function redact(headers, redactSet) {
+  if (!redactSet?.size) return headers;
+  const safe = {};
+  for (const [k, v] of Object.entries(headers)) {
+    safe[k] = redactSet.has(k) ? '[REDACTED]' : v;
+  }
+  return safe;
+}
+
+const host = Object.freeze({
+  hostname: hostname(),
+  arch: process.arch,
+  platform: process.platform,
+  pid: process.pid
+});
+
+/**
+ * Creates a structured request/response logging middleware.
+ *
+ * @param {object} [options] - Logger configuration
+ * @param {function} [options.log] - Log function for completed requests (default: console.log)
+ * @param {function} [options.error] - Log function for errors (default: console.error)
+ * @param {function} [options.uuid] - Fallback UUID generator used only when no upstream request ID
+ *   is found on the response or request headers (default: crypto.randomUUID)
+ * @param {string} [options.headerRequestIdName] - Request ID header name (default: 'x-request-id')
+ * @param {string} [options.headerRequestIpName] - Client IP header name (default: 'x-real-ip')
+ * @param {Set<string>} [options.redactHeaders] - Header names to replace with '[REDACTED]' in logs
+ *   (default: authorization, proxy-authorization, cookie, set-cookie)
+ * @returns {object} - Log entry with request metadata and host info (statusCode/duration added on finish)
+ */
+export default ({
+    /* eslint-disable-next-line no-console */
+    log = console.log,
+    /* eslint-disable-next-line no-console */
+    error: logError = console.error,
+    uuid = randomUUID,
+    headerRequestIdName = 'x-request-id',
+    headerRequestIpName = 'x-real-ip',
+    redactHeaders = DEFAULT_REDACTED
+  } = {}) =>
+  (req, res) => {
+    const time = performance.now();
+    const timestamp = Date.now();
+    const requestId =
+      res.getHeader(headerRequestIdName) || req.headers[headerRequestIdName] || uuid();
+    const ip = req.headers[headerRequestIpName];
+
+    if (!res.getHeader(headerRequestIdName)) {
+      res.setHeader(headerRequestIdName, requestId);
+    }
+
+    const info = {
+      requestId,
+      timestamp,
+      ip,
+      method: req.method,
+      url: req.url,
+      httpVersion: req.httpVersion,
+      host,
+      request: {
+        headers: redact(req.headers, redactHeaders),
+        encrypted: req.socket?.encrypted,
+        remoteAddress: req.socket?.remoteAddress,
+        remotePort: req.socket?.remotePort
+      }
+    };
+
+    res.on('finish', finish);
+    res.on('close', abort);
+    res.on('error', error);
+
+    return {...info};
+
+    /** Removes all response event listeners. */
+    function cleanup() {
+      res.removeListener('finish', finish);
+      res.removeListener('close', abort);
+      res.removeListener('error', error);
+    }
+
+    /**
+     * @param {boolean} aborted - Whether the connection was aborted before completion
+     */
+    function finish(aborted) {
+      cleanup();
+
+      info[aborted ? 'inprogressTime' : 'duration'] = performance.now() - time;
+      info.statusCode = res.statusCode;
+
+      info.response = {
+        headers: redact(res.getHeaders(), redactHeaders),
+        statusMessage: res.statusMessage,
+        writableFinished: res.writableFinished
+      };
+
+      log(info);
+    }
+
+    /** Handles connection close before response completes. */
+    function abort() {
+      finish(true);
+    }
+
+    /**
+     * @param {*} err - The error emitted by the response stream
+     */
+    function error(err) {
+      logError({
+        requestId,
+        timestamp,
+        name: err?.name,
+        message: err?.message,
+        status: err?.status,
+        statusCode: err?.statusCode,
+        originalError: err?.originalError,
+        stack: err?.stack
+      });
+    }
+  };

package/http/main.js

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview Ergo Fast Fail REST API toolkit - main module export.
+ *
+ * Provides composable middleware for the four-stage Fast Fail request processing pipeline:
+ * 1. Negotiation     - Parse/inspect request headers and URL (logger, cors, accepts, cookie, url)
+ * 2. Authorization   - Authenticate user and verify request integrity (authorization, csrf)
+ * 3. Validation      - Parse and validate request body (body, jsonApiQuery, validate)
+ * 4. Execution       - Run the route handler and send the response (handler, send)
+ *
+ * Middleware is composed via the two-accumulator pattern using `compose`:
+ *   compose([fn, setPath], ...)
+ *
+ * Each middleware factory returns `{value?, response?}`. Domain values are
+ * accumulated under named keys in `domainAcc`; response properties merge
+ * into `responseAcc`. `send()` is called post-pipeline by `handler()`.
+ *
+ * @module ergo
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ./handler.js
+ * @requires ./accepts.js
+ * @requires ./authorization.js
+ * @requires ./body.js
+ * @requires ./cache-control.js
+ * @requires ./compress.js
+ * @requires ./cookie.js
+ * @requires ./cors.js
+ * @requires ./csrf.js
+ * @requires ./json-api-query.js
+ * @requires ./logger.js
+ * @requires ./prefer.js
+ * @requires ./precondition.js
+ * @requires ./rate-limit.js
+ * @requires ./url.js
+ * @requires ./security-headers.js
+ * @requires ./send.js
+ * @requires ./timeout.js
+ * @requires ./validate.js
+ * @requires ../utils/compose-with.js
+ * @requires ../utils/http-errors.js
+ * @requires ../lib/from-connect.js
+ *
+ * @example
+ * import {compose, handler, logger, cors, authorization, accepts,
+ *         cookie, url, body} from 'ergo';
+ *
+ * const pipeline = compose(
+ *   // Stage 1: Negotiation
+ *   [logger(), 'log'],
+ *   [cors(), 'cors'],
+ *   [accepts({types: ['application/json']}), 'accepts'],
+ *   [cookie(), 'cookies'],
+ *   [url(), 'url'],
+ *   // Stage 2: Authorization
+ *   [authorization({strategies: [...]}), 'auth'],
+ *   // Stage 3: Validation
+ *   [body(), 'body'],
+ *   // Stage 4: Execution
+ *   (req, res, acc) => ({response: {body: acc.body.parsed}}),
+ * );
+ *
+ * export default handler(pipeline);
+ */
+
+import compose, {createResponseAcc, mergeResponse} from '../utils/compose-with.js';
+import handler from './handler.js';
+import accepts from './accepts.js';
+import authorization from './authorization.js';
+import body from './body.js';
+import cacheControl from './cache-control.js';
+import compress from './compress.js';
+import cookie from './cookie.js';
+import cors from './cors.js';
+import csrf from './csrf.js';
+import jsonApiQuery from './json-api-query.js';
+import logger from './logger.js';
+import url from './url.js';
+import prefer from './prefer.js';
+import precondition from './precondition.js';
+import rateLimit from './rate-limit.js';
+import securityHeaders from './security-headers.js';
+import send from './send.js';
+import timeout from './timeout.js';
+import validate from './validate.js';
+import httpErrors from '../utils/http-errors.js';
+import fromConnect from '../lib/from-connect.js';
+
+export {
+  compose,
+  createResponseAcc,
+  mergeResponse,
+  handler,
+  accepts,
+  authorization,
+  body,
+  cacheControl,
+  compress,
+  cookie,
+  cors,
+  csrf,
+  fromConnect,
+  httpErrors,
+  jsonApiQuery,
+  logger,
+  prefer,
+  precondition,
+  rateLimit,
+  securityHeaders,
+  url,
+  send,
+  timeout,
+  validate
+};
+
+// Default export mirrors the named exports above — keep both in sync.
+/** @type {object} */
+export default {
+  compose,
+  handler,
+  accepts,
+  authorization,
+  body,
+  cacheControl,
+  compress,
+  cookie,
+  cors,
+  csrf,
+  fromConnect,
+  httpErrors,
+  jsonApiQuery,
+  logger,
+  prefer,
+  precondition,
+  rateLimit,
+  securityHeaders,
+  url,
+  send,
+  timeout,
+  validate
+};

package/http/precondition.js

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Precondition Required middleware (RFC 6585 §3).
+ *
+ * Enforces that unsafe requests include a conditional header (`If-Match` or
+ * `If-Unmodified-Since`) before the pipeline proceeds. This prevents "lost update"
+ * problems where a client overwrites changes made by another client without first
+ * fetching the current resource state.
+ *
+ * Placed in Stage 1 (Negotiation) for Fast Fail — the check is a cheap header
+ * inspection that short-circuits before authorization, body parsing, or execution.
+ *
+ * @module http/precondition
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import {compose, precondition} from 'ergo';
+ *
+ * // Enforce on all requests (method scoping handled by pipeline builder)
+ * const pipeline = compose(
+ *   [precondition(), 'precondition'],
+ *   (req, res, acc) => ({response: {statusCode: 200, body: {updated: true}}})
+ * );
+ *
+ * // Enforce only on specific methods (standalone usage)
+ * const pipeline = compose(
+ *   [precondition({methods: ['PUT', 'PATCH']}), 'precondition'],
+ *   (req, res, acc) => ({response: {statusCode: 200, body: {updated: true}}})
+ * );
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc6585#section-3 RFC 6585 Section 3 - 428 Precondition Required}
+ */
+
+/**
+ * Create a precondition enforcement middleware.
+ *
+ * @param {object} [options]
+ * @param {string[]|Set<string>} [options.methods] - HTTP methods to enforce on.
+ *   When omitted, enforces unconditionally (the pipeline builder handles method scoping).
+ *   When provided, only activates for the specified methods.
+ * @returns {function} - Middleware `(req) => void` that returns `{response: {statusCode: 428}}` if no conditional header is present
+ */
+export default function precondition({methods} = {}) {
+  const methodSet = methods ? (methods instanceof Set ? methods : new Set(methods)) : undefined;
+
+  return req => {
+    if (methodSet && !methodSet.has(req.method)) return;
+
+    if (!req.headers['if-match'] && !req.headers['if-unmodified-since']) {
+      return {response: {statusCode: 428}};
+    }
+  };
+}

package/http/prefer.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview HTTP middleware factory for Prefer header parsing (RFC 7240).
+ *
+ * Parses the `Prefer` request header and returns a preferences object for the
+ * accumulator. Combined with `send()`'s `preferKey` option, enables automatic
+ * `return=minimal` / `return=representation` response handling.
+ *
+ * Placed in Stage 1 (Negotiation) — cheap header parse with no I/O.
+ *
+ * @module http/prefer
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../lib/prefer.js
+ *
+ * @example
+ * import {compose, prefer} from 'ergo';
+ *
+ * const pipeline = compose(
+ *   [prefer(), 'prefer'],
+ *   (req, res, acc) => ({response: {body: {id: 1, name: 'item'}}}),
+ * );
+ * // Client sends: Prefer: return=minimal
+ * // Response: 204 No Content + Preference-Applied: return=minimal
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc7240 RFC 7240 - Prefer Header for HTTP}
+ */
+import parsePrefer from '../lib/prefer.js';
+
+/**
+ * Creates a Prefer header parsing middleware.
+ *
+ * @returns {function} - Middleware `(req) => object` returning parsed preferences
+ */
+export default () => {
+  return req => parsePrefer(req.headers?.prefer);
+};

package/http/rate-limit.js

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Rate limiting pipeline middleware (RFC 6585 §4).
+ *
+ * Tracks request counts per client key within a configurable time window.
+ * Returns rate-limit header tuples for the response accumulator on allowed requests;
+ * returns `{response: {statusCode: 429, retryAfter}}` when the limit is exceeded.
+ *
+ * Placed in Stage 1 (Negotiation) for Fast Fail — the check is a cheap
+ * counter lookup that short-circuits before authorization, body parsing,
+ * or execution.
+ *
+ * @module http/rate-limit
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../lib/rate-limit.js
+ *
+ * @example
+ * import {compose, rateLimit} from 'ergo';
+ *
+ * const pipeline = compose(
+ *   [rateLimit({max: 100, windowMs: 60000}), 'rateLimit'],
+ *   (req, res, acc) => ({response: {statusCode: 200, body: {ok: true}}})
+ * );
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc6585#section-4 RFC 6585 Section 4 - 429 Too Many Requests}
+ */
+import {MemoryStore, checkRateLimit, defaultKeyGenerator} from '../lib/rate-limit.js';
+
+/**
+ * Create a rate limiting middleware.
+ *
+ * @param {object} [options]
+ * @param {number} [options.max=100] - Maximum requests per window
+ * @param {number} [options.windowMs=60000] - Window size in milliseconds (default: 1 minute)
+ * @param {object} [options.store] - Pluggable store (must implement `hit(key, windowMs)`)
+ * @param {function} [options.keyGenerator] - `(req) => string` client identifier (default: remote IP)
+ * @returns {function} - Middleware `(req) => {response}` that returns rate-limit header tuples on allowed
+ *   requests and `{response: {statusCode: 429, retryAfter}}` when the limit is exceeded
+ */
+export default function rateLimit({max = 100, windowMs = 60000, store, keyGenerator} = {}) {
+  const _store = store ?? new MemoryStore();
+  const _keyGen = keyGenerator ?? defaultKeyGenerator;
+
+  return req => {
+    const result = checkRateLimit(_store, _keyGen(req), max, windowMs);
+
+    if (result.limited) {
+      return {
+        response: {
+          statusCode: 429,
+          retryAfter: result.retryAfter
+        }
+      };
+    }
+
+    return {
+      response: {
+        headers: [
+          ['X-RateLimit-Limit', String(max)],
+          ['X-RateLimit-Remaining', String(result.remaining)],
+          ['X-RateLimit-Reset', String(result.reset)]
+        ]
+      }
+    };
+  };
+}

package/http/security-headers.js

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview HTTP middleware factory for security response headers.
+ *
+ * Returns pre-computed header tuples for common security headers recommended for
+ * REST APIs. Each header is individually configurable or disableable (pass `false`).
+ * Header tuples are built at factory time for zero per-request overhead.
+ *
+ * Delegates tuple construction to `lib/security-headers.js` (the shared primitive).
+ *
+ * @module http/security-headers
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../lib/security-headers.js
+ *
+ * @example
+ * import {compose, securityHeaders} from 'ergo';
+ *
+ * // Use defaults
+ * const pipeline = compose(
+ *   [securityHeaders(), 'security'],
+ *   // ...
+ * );
+ *
+ * // Customize or disable individual headers
+ * const pipeline = compose(
+ *   [securityHeaders({
+ *     xFrameOptions: 'SAMEORIGIN',
+ *     permissionsPolicy: 'camera=(), microphone=()',
+ *     xXssProtection: false  // disable
+ *   }), 'security'],
+ * );
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc6797 RFC 6797 - HTTP Strict Transport Security}
+ * @see {@link https://www.w3.org/TR/CSP3/ W3C Content Security Policy Level 3}
+ */
+import buildSecurityHeaderTuples from '../lib/security-headers.js';
+
+/**
+ * Creates a security headers middleware that returns pre-computed header tuples.
+ *
+ * Pass `false` for any header to omit it entirely. Pass a string to override
+ * the default value.
+ *
+ * @param {object} [options] - Security header configuration
+ * @param {string|false} [options.contentSecurityPolicy="default-src 'none'"] - Content-Security-Policy header
+ * @param {string|false} [options.strictTransportSecurity=false] - Strict-Transport-Security header.
+ *   Defaults to `false` because this middleware has no request context to verify the connection
+ *   is HTTPS, and HSTS MUST only be sent over secure transport (RFC 6797 §7.2). Enable explicitly
+ *   when the app is known to be behind HTTPS, or use ergo-router's transport layer which performs
+ *   the HTTPS check automatically.
+ * @param {string|false} [options.xContentTypeOptions='nosniff'] - X-Content-Type-Options header
+ * @param {string|false} [options.xFrameOptions='DENY'] - X-Frame-Options header
+ * @param {string|false} [options.referrerPolicy='no-referrer'] - Referrer-Policy header
+ * @param {string|false} [options.xXssProtection='0'] - X-XSS-Protection header (0 disables the browser filter)
+ * @param {string} [options.permissionsPolicy] - Permissions-Policy header (omitted by default)
+ * @returns {function} - Ergo middleware `() => Array<[string, string]>`
+ */
+export default (options = {}) => {
+  const headerTuples = buildSecurityHeaderTuples(options);
+  const response = {response: {headers: headerTuples}};
+  return () => response;
+};