@centralping/ergo 0.1.0-beta.1

package/http/send.js

@@ -0,0 +1,399 @@
+/**
+ * @fileoverview HTTP response serialization (v2: two-accumulator model).
+ *
+ * Called directly by auto-wrap / handler after the pipeline completes.
+ * Reads from two accumulators:
+ * - **responseAcc**: `statusCode`, `body`, `headers`, `detail`, `retryAfter`,
+ *   `instance`, `location`, `lastModified`, `type` (explicit body type override)
+ * - **domainAcc**: `cookies` (cookie jar), `prefer` (parsed Prefer header)
+ *
+ * For error responses (`statusCode >= 400`), builds an RFC 9457 Problem Details
+ * body automatically from `statusCode`, `detail`, `retryAfter`, `instance`, and
+ * any extension members on the response accumulator.
+ *
+ * For success responses (`statusCode < 400`), handles multiple body types:
+ * - `null`/`undefined` — default text from STATUS_CODES (enforced empty for 204/304)
+ * - `string` — written as-is; detects HTML vs plain text content type
+ * - `Uint8Array` (non-Buffer) — written as `application/octet-stream`
+ * - `Stream` (readable) — piped to the response
+ * - `Object` — JSON-serialized; respects `prettify` option
+ *
+ * Also handles:
+ * - ETag generation and conditional request evaluation (`If-None-Match`, `If-Match`)
+ * - `Last-Modified` and date-based conditionals (`If-Modified-Since`, `If-Unmodified-Since`)
+ * - `Location` header for 201 Created and 3xx redirect responses
+ * - `Vary` header injection
+ * - `Retry-After` header from `retryAfter` on the response accumulator
+ * - `Set-Cookie` from `domainAcc.cookies.toHeader()`
+ * - RFC 7240 Prefer handling (`return=minimal`, `return=representation`)
+ * - Optional response envelope for 2xx Object bodies
+ *
+ * @module http/send
+ * @version 0.2.0
+ * @since 0.1.0
+ * @requires node:stream
+ * @requires node:http
+ * @requires etag
+ * @requires ../utils/http-errors.js
+ * @requires ../lib/vary.js
+ *
+ * @example
+ * import {send, createResponseAcc} from 'ergo';
+ *
+ * const writer = send({etag: true});
+ * // After pipeline completes:
+ * writer(req, res, responseAcc, domainAcc);
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9110 RFC 9110 - HTTP Semantics}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9457 RFC 9457 - Problem Details for HTTP APIs}
+ */
+import {Stream, pipeline} from 'node:stream';
+import {STATUS_CODES} from 'node:http';
+import generateETag from 'etag';
+import httpErrors from '../utils/http-errors.js';
+import appendVary from '../lib/vary.js';
+
+const isHTML = /<[a-z][^>]*>/i;
+
+const NO_BODY_STATUSES = new Set([204, 304]);
+const ETAG_UNSAFE_METHODS = new Set(['PUT', 'PATCH', 'DELETE']);
+
+const SEND_RESERVED = new Set([
+  'statusCode',
+  'body',
+  'headers',
+  'detail',
+  'retryAfter',
+  'instance',
+  'type',
+  'lastModified',
+  'location'
+]);
+
+/**
+ * Built-in response envelope format.
+ *
+ * @param {object} body - Original response body
+ * @param {{requestId: string, statusCode: number}} ctx - Request context
+ * @returns {object} - Enveloped body
+ */
+function defaultEnvelope(body, {requestId, statusCode}) {
+  const result = {id: requestId, status: statusCode, data: body};
+  if (Array.isArray(body)) result.count = body.length;
+  return result;
+}
+
+/**
+ * Inline body type detection.
+ *
+ * @param {*} body - Response body value to classify
+ * @returns {string} - Type label: 'Null', 'String', 'Uint8Array', 'Stream', or 'Object'
+ */
+function bodyType(body) {
+  if (body === null || body === undefined) return 'Null';
+  if (typeof body === 'string') return 'String';
+  if (body instanceof Uint8Array && !Buffer.isBuffer(body)) return 'Uint8Array';
+  if (body instanceof Stream) return 'Stream';
+  return 'Object';
+}
+
+/**
+ * Creates a response serialization function.
+ *
+ * @param {object} [options] - Send configuration
+ * @param {boolean} [options.prettify=false] - Pretty-print JSON output
+ * @param {string[]} [options.vary=['Accept']] - Vary header values to append
+ * @param {boolean} [options.etag=true] - Generate and evaluate ETags for conditional responses
+ * @param {boolean} [options.prefer=false] - When true, read `domainAcc.prefer` for RFC 7240
+ *   handling. Adds `Prefer` to the Vary header.
+ * @param {boolean|function} [options.envelope=false] - Wrap 2xx Object bodies in a response
+ *   envelope. `false` (default) — no envelope. `true` — built-in format `{id, status, data,
+ *   count?}`. `function(body, ctx)` — custom envelope.
+ * @returns {function} - `(req, res, responseAcc, domainAcc) => void`
+ */
+export default ({
+  prettify = false,
+  vary = ['Accept'],
+  etag = true,
+  prefer = false,
+  envelope = false
+} = {}) => {
+  const effectiveVary = prefer ? [...(vary || []), 'Prefer'] : vary;
+  const varyValue = effectiveVary?.length ? effectiveVary.join(', ') : undefined;
+
+  return (req, res, responseAcc, domainAcc = {}) => {
+    if (res.writableEnded || !res.writable) return;
+
+    let {
+      statusCode = res.statusCode,
+      body,
+      type: explicitType,
+      headers = [],
+      lastModified,
+      location,
+      detail,
+      retryAfter,
+      instance
+    } = responseAcc;
+
+    // RFC 9457: build error body for 4xx/5xx
+    if (statusCode >= 400) {
+      const opts = {};
+      if (detail) opts.message = detail;
+      if (retryAfter != null) opts.retryAfter = retryAfter;
+      if (instance) opts.instance = instance;
+
+      for (const key of Object.keys(responseAcc)) {
+        if (!SEND_RESERVED.has(key) && opts[key] === undefined) {
+          opts[key] = responseAcc[key];
+        }
+      }
+
+      body = httpErrors(statusCode, opts);
+    } else if (body === undefined) {
+      body = STATUS_CODES[statusCode] ?? String(statusCode);
+    }
+
+    if (
+      envelope &&
+      statusCode >= 200 &&
+      statusCode < 300 &&
+      bodyType(body) === 'Object' &&
+      !(body instanceof Error)
+    ) {
+      const requestId = res.getHeader('x-request-id');
+      body =
+        typeof envelope === 'function'
+          ? envelope(body, {requestId, statusCode, method: req.method})
+          : defaultEnvelope(body, {requestId, statusCode});
+    }
+
+    const resolvedType = explicitType ?? bodyType(body);
+
+    res.statusCode = statusCode;
+
+    // Middleware-contributed headers (from responseAcc.headers)
+    for (const [header, value] of headers) {
+      if (header !== undefined) {
+        if (value === undefined) {
+          res.clearHeader(header);
+        } else {
+          res.setHeader(header, value);
+        }
+      }
+    }
+
+    // Cookies from domain accumulator
+    if (domainAcc.cookies) {
+      res.setHeader('Set-Cookie', domainAcc.cookies.toHeader());
+    }
+
+    if (retryAfter != null) {
+      res.setHeader('Retry-After', String(retryAfter));
+    }
+
+    if (varyValue) {
+      appendVary(res, varyValue);
+    }
+
+    // RFC 9110 §10.2.2: Location header for 201 Created and 3xx redirects
+    if (location && statusCode >= 200 && statusCode < 400) {
+      res.setHeader('Location', location);
+    }
+
+    // RFC 7240: Prefer header handling
+    if (prefer) {
+      const preferData = domainAcc.prefer;
+      if (preferData?.return === 'minimal' && statusCode >= 200 && statusCode < 300) {
+        res.setHeader('Preference-Applied', 'return=minimal');
+        if (statusCode === 200) res.statusCode = 204;
+        endNoBody(res);
+        return;
+      }
+      if (preferData?.return === 'representation' && statusCode >= 200 && statusCode < 300) {
+        res.setHeader('Preference-Applied', 'return=representation');
+      }
+    }
+
+    // RFC 7231: 204 No Content and 304 Not Modified MUST NOT contain a body
+    if (NO_BODY_STATUSES.has(statusCode)) {
+      endNoBody(res);
+      return;
+    }
+
+    if (res.getHeader('Content-Type') === undefined) {
+      if (resolvedType === 'Stream') {
+        res.setHeader('Content-Type', 'application/octet-stream');
+        pipeline(body, res, err => {
+          if (err && res.listenerCount('error') > 0) {
+            res.emit('error', err);
+          }
+        });
+        return;
+      }
+
+      switch (resolvedType) {
+        case 'String':
+          res.setHeader(
+            'Content-Type',
+            isHTML.test(body) ? 'text/html; charset=utf-8' : 'text/plain; charset=utf-8'
+          );
+          break;
+        case 'Uint8Array':
+          res.setHeader('Content-Type', 'application/octet-stream');
+          break;
+        default:
+          res.setHeader(
+            'Content-Type',
+            body instanceof Error
+              ? 'application/problem+json; charset=utf-8'
+              : 'application/json; charset=utf-8'
+          );
+          break;
+      }
+    }
+
+    const contentType = res.getHeader('Content-Type');
+    if (contentType.includes('/json') || contentType.includes('+json')) {
+      body = JSON.stringify(body, null, prettify ? 2 : 0);
+    }
+
+    const len = typeof body === 'string' ? Buffer.byteLength(body) : body.length;
+
+    if (len !== undefined) {
+      res.setHeader('Content-Length', len);
+    }
+
+    // Last-Modified header (set before conditionals so it's present in 304/412 responses)
+    let lastModifiedDate;
+    if (lastModified != null && statusCode >= 200 && statusCode < 300) {
+      lastModifiedDate = lastModified instanceof Date ? lastModified : new Date(lastModified);
+      if (!Number.isNaN(lastModifiedDate.getTime())) {
+        res.setHeader('Last-Modified', lastModifiedDate.toUTCString());
+      } else {
+        lastModifiedDate = undefined;
+      }
+    }
+
+    const ifNoneMatch = req.headers?.['if-none-match'];
+    const ifMatch = req.headers?.['if-match'];
+
+    // ETag: conditional responses
+    if (etag && statusCode >= 200 && statusCode < 300) {
+      const entityBody =
+        typeof body === 'string' ? body : Buffer.isBuffer(body) ? body : Buffer.from(String(body));
+      const tag = generateETag(entityBody);
+      res.setHeader('ETag', tag);
+
+      // If-None-Match -> 304 (weak comparison per RFC 9110 §8.8.3.2)
+      if (ifNoneMatch && weakMatchesETag(ifNoneMatch, tag)) {
+        res.statusCode = 304;
+        endNoBody(res);
+        return;
+      }
+
+      // If-Match -> 412 (strong comparison per RFC 9110 §8.8.3.2)
+      if (ifMatch && ETAG_UNSAFE_METHODS.has(req.method)) {
+        if (!strongMatchesETag(ifMatch, tag)) {
+          endWithProblem(res, 412);
+          return;
+        }
+      }
+    }
+
+    // Date-based conditional responses (RFC 9110 §8.8.2)
+    if (lastModifiedDate && statusCode >= 200 && statusCode < 300) {
+      // If-Modified-Since → 304 (skip when If-None-Match is present per RFC 9110 §13.1.3)
+      if (!ifNoneMatch) {
+        const ifModifiedSince = req.headers?.['if-modified-since'];
+        if (ifModifiedSince && !isModifiedSince(lastModifiedDate, ifModifiedSince)) {
+          res.statusCode = 304;
+          endNoBody(res);
+          return;
+        }
+      }
+
+      // If-Unmodified-Since → 412 (skip when If-Match is present per RFC 9110 §13.1.4)
+      if (!ifMatch && ETAG_UNSAFE_METHODS.has(req.method)) {
+        const ifUnmodifiedSince = req.headers?.['if-unmodified-since'];
+        if (ifUnmodifiedSince && isModifiedSince(lastModifiedDate, ifUnmodifiedSince)) {
+          endWithProblem(res, 412);
+          return;
+        }
+      }
+    }
+
+    res.end(body);
+  };
+};
+
+/**
+ * Weak comparison: two ETags match if their opaque-tags are identical after
+ * stripping any `W/` prefix (RFC 9110 §8.8.3.2).
+ *
+ * @param {string} header - The header value (e.g., '"abc", W/"def"')
+ * @param {string} tag - The generated ETag
+ * @returns {boolean} - True if any ETag in the header weakly matches the tag
+ */
+function weakMatchesETag(header, tag) {
+  if (header === '*') return true;
+  const normalized = tag.replace(/^W\//, '');
+  return header.split(',').some(t => t.trim().replace(/^W\//, '') === normalized);
+}
+
+/**
+ * Strong comparison: two ETags match only if both are strong (no `W/` prefix)
+ * and their opaque-tags are identical (RFC 9110 §8.8.3.2).
+ *
+ * @param {string} header - The header value (e.g., '"abc", "def"')
+ * @param {string} tag - The generated ETag
+ * @returns {boolean} - True if any strong ETag in the header matches the tag
+ */
+function strongMatchesETag(header, tag) {
+  if (header === '*') return true;
+  if (tag.startsWith('W/')) return false;
+  return header.split(',').some(t => {
+    const trimmed = t.trim();
+    return !trimmed.startsWith('W/') && trimmed === tag;
+  });
+}
+
+/**
+ * Determines whether a resource has been modified after the given date.
+ *
+ * @param {Date} lastModified - The resource's last modification date
+ * @param {string} headerValue - The If-Modified-Since or If-Unmodified-Since header value
+ * @returns {boolean} - True if the resource was modified after the header date
+ */
+function isModifiedSince(lastModified, headerValue) {
+  const since = new Date(headerValue);
+  if (Number.isNaN(since.getTime())) return true;
+  return Math.floor(lastModified.getTime() / 1000) > Math.floor(since.getTime() / 1000);
+}
+
+/**
+ * End the response with no body for 304 Not Modified (or 204 No Content).
+ *
+ * @param {import('node:http').ServerResponse} res - HTTP response object
+ */
+function endNoBody(res) {
+  res.removeHeader('Content-Type');
+  res.removeHeader('Content-Length');
+  res.removeHeader('Transfer-Encoding');
+  res.end();
+}
+
+/**
+ * End the response with an RFC 9457 Problem Details body for conditional
+ * request failures (412 Precondition Failed).
+ *
+ * @param {import('node:http').ServerResponse} res - HTTP response object
+ * @param {number} statusCode - HTTP status code for the error
+ */
+function endWithProblem(res, statusCode) {
+  res.statusCode = statusCode;
+  res.setHeader('Content-Type', 'application/problem+json; charset=utf-8');
+  const body = JSON.stringify(httpErrors(statusCode));
+  res.setHeader('Content-Length', Buffer.byteLength(body));
+  res.end(body);
+}

package/http/timeout.js

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview HTTP middleware factory for request timeouts (v2).
+ *
+ * Races the downstream pipeline against a configurable deadline.
+ * When the deadline fires, sets `responseAcc.statusCode` and `responseAcc.detail`
+ * via closure access, then destroys the request (without an error argument).
+ * The pipeline's catch block detects the pre-set statusCode and skips error
+ * formatting.
+ *
+ * Uses a cancellable setTimeout + res 'close' listener. When the response
+ * completes normally, the timer is cleared immediately so the req/res closure
+ * can be GC'd.
+ *
+ * @module http/timeout
+ * @version 0.2.0
+ * @since 0.1.0
+ *
+ * @example
+ * import {compose, timeout} from 'ergo';
+ *
+ * const pipeline = compose(
+ *   [timeout({ms: 10000, statusCode: 504}), 'timeout'],
+ *   (req, res, acc) => ({response: {body: await slowCall(), statusCode: 200}})
+ * );
+ */
+
+/**
+ * Creates a request timeout middleware.
+ *
+ * @param {object} [options] - Timeout configuration
+ * @param {number} [options.ms=30000] - Timeout in milliseconds
+ * @param {number} [options.statusCode=408] - HTTP status code on timeout (408 or 504)
+ * @returns {function} - Ergo middleware `(req, res, domainAcc, responseAcc) => void`
+ */
+export default ({ms = 30000, statusCode = 408} = {}) => {
+  return (req, res, domainAcc, responseAcc) => {
+    const timer = setTimeout(() => {
+      if (!req.destroyed) {
+        responseAcc.statusCode = statusCode;
+        responseAcc.detail = `Request timed out after ${ms}ms`;
+        req.destroy();
+      }
+    }, ms);
+
+    res.on('close', () => clearTimeout(timer));
+  };
+};

package/http/url.js

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview HTTP middleware factory for URL parsing.
+ *
+ * Parses the request URL into pathname, query parameters, and raw search string
+ * using a fast single-pass parser (no `URL` construction overhead).
+ * Multi-value parameters are returned as arrays.
+ *
+ * Returns `{query, pathname, search}` where:
+ * - `query` is the parsed key-value object (multi-value keys become arrays)
+ * - `pathname` is the URL path component (before `?`)
+ * - `search` is the raw query string including the `?` prefix, or `undefined`
+ *
+ * @module http/url
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../lib/query.js
+ *
+ * @example
+ * import {compose, url} from 'ergo';
+ *
+ * const pipeline = compose(
+ *   [url(), 'url'],
+ *   // acc.url => {query: {page: '1', filter: ['a','b']}, pathname: '/users', search: '?page=1&filter=a&filter=b'}
+ * );
+ */
+import queryParse from '../lib/query.js';
+
+/**
+ * Creates a URL parsing middleware.
+ *
+ * @returns {function} - Ergo middleware `({url}) => {query, pathname, search}`
+ */
+export default () =>
+  ({url} = {}) => {
+    const raw = url ?? '/';
+    const qIdx = raw.indexOf('?');
+
+    if (qIdx === -1) {
+      return {query: Object.create(null), pathname: raw || undefined, search: undefined};
+    }
+
+    return {
+      query: queryParse(raw.slice(qIdx + 1)),
+      pathname: raw.slice(0, qIdx) || undefined,
+      search: raw.slice(qIdx)
+    };
+  };

package/http/validate.js

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview HTTP middleware factory for JSON Schema validation.
+ *
+ * Validates properties from the accumulator (body, url, params) against provided JSON
+ * Schemas using AJV. Schemas are compiled once at middleware creation time for performance.
+ *
+ * Returns `{response: {statusCode: 422, detail: ...}}` with structured error details on validation failure.
+ * Must be placed after `body()` and/or `url()` in the pipeline so accumulator values
+ * are populated before validation runs.
+ *
+ * @module http/validate
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../lib/validate.js
+ *
+ * @example
+ * import {compose, body, url, validate} from 'ergo';
+ *
+ * const pipeline = compose(
+ *   [body(), 'body'],
+ *   [url(), 'url'],
+ *   [validate({
+ *     body: {
+ *       type: 'object',
+ *       properties: {name: {type: 'string'}},
+ *       required: ['name']
+ *     },
+ *     query: {
+ *       type: 'object',
+ *       properties: {page: {type: 'string', pattern: '^[0-9]+$'}}
+ *     }
+ *   }), 'validation'],
+ * );
+ */
+import createValidator from '../lib/validate.js';
+
+/**
+ * Creates a JSON Schema validation middleware.
+ *
+ * @param {object} [schemas] - Schema map; each key corresponds to an accumulator property
+ * @param {object} [schemas.body] - JSON Schema for the parsed request body
+ * @param {object} [schemas.query] - JSON Schema for parsed query parameters
+ * @param {object} [schemas.params] - JSON Schema for route path parameters
+ * @param {object} [options] - AJV options forwarded to each compiled validator
+ * @returns {function} - Ergo middleware `(req, res, acc) => void` that returns `{response: {statusCode: 422}}`
+ *   (with `detail` and `details` from AJV) on validation failure
+ */
+export default (schemas = {}, options = {}) => {
+  const validators = {};
+
+  if (schemas.body) {
+    validators.body = createValidator(schemas.body, options);
+  }
+  if (schemas.query) {
+    validators.query = createValidator(schemas.query, options);
+  }
+  if (schemas.params) {
+    validators.params = createValidator(schemas.params, options);
+  }
+
+  return (req, res, acc) => {
+    try {
+      if (validators.body && acc.body && acc.body.parsed !== undefined) {
+        validators.body(acc.body.parsed);
+      }
+
+      if (validators.query && acc.url?.query) {
+        validators.query(acc.url.query);
+      }
+
+      if (validators.params && acc.params) {
+        validators.params(acc.params);
+      }
+    } catch (err) {
+      return {
+        response: {
+          statusCode: err.statusCode ?? 422,
+          detail: err.message,
+          details: err.details
+        }
+      };
+    }
+  };
+};

package/lib/accepts.js

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Core content negotiation logic using the `negotiator` library.
+ *
+ * Provides a configurable negotiation factory that matches request `Accept*` headers
+ * against allowed types, languages, charsets, and encodings. Used by `http/accepts.js`
+ * as the pure-logic backing implementation.
+ *
+ * @module lib/accepts
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires negotiator
+ * @requires ../utils/flat-array.js
+ *
+ * @example
+ * import accepts from 'ergo/lib/accepts';
+ *
+ * const negotiate = accepts({types: ['application/json', 'text/html']});
+ * const result = negotiate({'accept': 'text/html,application/json;q=0.9'});
+ * // result.type => 'text/html'
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9110#section-12.5 RFC 9110 Section 12.5 - Content Negotiation}
+ */
+import Negotiator from 'negotiator';
+
+import flatArray from '../utils/flat-array.js';
+
+/**
+ * Creates a content negotiation function for the given preference lists.
+ *
+ * @param {object} [options] - Negotiation preferences
+ * @param {string|string[]} [options.types] - Acceptable media types
+ * @param {string|string[]} [options.languages] - Acceptable languages
+ * @param {string|string[]} [options.charsets] - Acceptable charsets
+ * @param {string|string[]} [options.encodings] - Acceptable encodings
+ * @returns {function} - `(headers) => {type, language, charset, encoding}`
+ */
+export default ({types, languages, charsets, encodings} = {}) =>
+  (headers = {}) => {
+    const negotiator = new Negotiator({headers: {...headers}});
+
+    const toArr = v => (v ? flatArray(v) : undefined);
+
+    return {
+      type: negotiator.mediaType(toArr(types)),
+      language: negotiator.language(toArr(languages)),
+      charset: negotiator.charset(toArr(charsets)),
+      encoding: negotiator.encoding(toArr(encodings))
+    };
+  };

package/lib/attach-instance.js

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Shared RFC 9457 instance injection helper.
+ *
+ * Auto-populates the `instance` property on an error from the response's
+ * `x-request-id` header, formatted as a `urn:uuid:` URI.
+ *
+ * @module lib/attach-instance
+ * @version 0.1.0
+ * @since 0.1.0
+ */
+
+/**
+ * Set `err.instance` from the response's `x-request-id` header if not already set.
+ *
+ * @param {Error & {instance?: string}} err - Error to annotate
+ * @param {import('node:http').ServerResponse} res - HTTP response
+ */
+export default function attachInstance(err, res) {
+  if (err.instance === undefined) {
+    const requestId = res.getHeader?.('x-request-id');
+    if (requestId) err.instance = `urn:uuid:${requestId}`;
+  }
+}