@centralping/ergo 0.1.0-beta.1

package/http/cache-control.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview HTTP middleware factory for Cache-Control header defaults.
+ *
+ * Returns header tuples that set the `Cache-Control` response header. The directive
+ * string is pre-computed at factory time for zero per-request cost. Accepts either
+ * a raw directive string or structured options that are assembled into a directive.
+ *
+ * @module http/cache-control
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import {compose, cacheControl} from 'ergo';
+ *
+ * // String shorthand
+ * const pipeline = compose(
+ *   [cacheControl({directives: 'public, max-age=3600'}), 'cache'],
+ *   // ...
+ * );
+ *
+ * // Structured options
+ * const pipeline = compose(
+ *   [cacheControl({private: true, maxAge: 0, mustRevalidate: true}), 'cache'],
+ *   // ...
+ * );
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9111 RFC 9111 - HTTP Caching}
+ */
+
+/**
+ * Creates a Cache-Control middleware that returns a pre-computed header tuple.
+ *
+ * @param {object} [options] - Cache-Control configuration
+ * @param {string} [options.directives] - Raw directive string (takes precedence over structured options)
+ * @param {boolean} [options.public=false] - Add `public` directive
+ * @param {boolean} [options.private=false] - Add `private` directive
+ * @param {boolean} [options.noCache=false] - Add `no-cache` directive
+ * @param {boolean} [options.noStore=false] - Add `no-store` directive
+ * @param {boolean} [options.noTransform=false] - Add `no-transform` directive
+ * @param {boolean} [options.mustRevalidate=false] - Add `must-revalidate` directive
+ * @param {boolean} [options.proxyRevalidate=false] - Add `proxy-revalidate` directive
+ * @param {boolean} [options.immutable=false] - Add `immutable` directive
+ * @param {number} [options.maxAge] - `max-age` value in seconds
+ * @param {number} [options.sMaxAge] - `s-maxage` value in seconds
+ * @param {number} [options.staleWhileRevalidate] - `stale-while-revalidate` value in seconds
+ * @param {number} [options.staleIfError] - `stale-if-error` value in seconds
+ * @returns {function} - Ergo middleware `() => Array<[string, string]>`
+ */
+export default ({
+  directives,
+  public: isPublic = false,
+  private: isPrivate = false,
+  noCache = false,
+  noStore = false,
+  noTransform = false,
+  mustRevalidate = false,
+  proxyRevalidate = false,
+  immutable = false,
+  maxAge,
+  sMaxAge,
+  staleWhileRevalidate,
+  staleIfError
+} = {}) => {
+  const value =
+    directives ??
+    buildDirectives({
+      isPublic,
+      isPrivate,
+      noCache,
+      noStore,
+      noTransform,
+      mustRevalidate,
+      proxyRevalidate,
+      immutable,
+      maxAge,
+      sMaxAge,
+      staleWhileRevalidate,
+      staleIfError
+    });
+
+  const headerTuples = [['Cache-Control', value]];
+  const response = {response: {headers: headerTuples}};
+
+  return () => response;
+};
+
+/**
+ * Assembles a Cache-Control directive string from structured options.
+ *
+ * @param {object} opts - Structured directive options
+ * @returns {string} - Assembled directive string (e.g. "private, no-cache, max-age=0")
+ */
+function buildDirectives({
+  isPublic,
+  isPrivate,
+  noCache,
+  noStore,
+  noTransform,
+  mustRevalidate,
+  proxyRevalidate,
+  immutable,
+  maxAge,
+  sMaxAge,
+  staleWhileRevalidate,
+  staleIfError
+}) {
+  const parts = [];
+
+  if (isPublic) parts.push('public');
+  if (isPrivate) parts.push('private');
+  if (noCache) parts.push('no-cache');
+  if (noStore) parts.push('no-store');
+  if (noTransform) parts.push('no-transform');
+  if (mustRevalidate) parts.push('must-revalidate');
+  if (proxyRevalidate) parts.push('proxy-revalidate');
+  if (immutable) parts.push('immutable');
+  if (maxAge != null) parts.push(`max-age=${maxAge}`);
+  if (sMaxAge != null) parts.push(`s-maxage=${sMaxAge}`);
+  if (staleWhileRevalidate != null) parts.push(`stale-while-revalidate=${staleWhileRevalidate}`);
+  if (staleIfError != null) parts.push(`stale-if-error=${staleIfError}`);
+
+  return parts.join(', ') || 'private, no-cache';
+}

package/http/compress.js

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview HTTP middleware factory for outbound response compression.
+ *
+ * Negotiates Accept-Encoding and wraps the response stream through
+ * the appropriate zlib compressor (gzip, br, deflate).
+ *
+ * Should be placed early in the pipeline (before send) so it can
+ * intercept the response before headers are sent.
+ *
+ * Compression is skipped for:
+ * - Responses with status 204 or 304
+ * - Non-compressible content types (binary, images, etc.)
+ * - Bodies below the configurable `threshold` byte count (default 1 KiB)
+ *
+ * @module http/compress
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires node:zlib
+ * @requires negotiator
+ *
+ * @example
+ * import {compose, compress} from 'ergo';
+ *
+ * const pipeline = compose(
+ *   compress({threshold: 1024, encodings: ['br', 'gzip', 'deflate']}),
+ *   (req, res, acc) => ({response: {body: largePayload}})
+ * );
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9110#section-12.5.3 RFC 9110 Section 12.5.3 - Accept-Encoding}
+ */
+import zlib from 'node:zlib';
+import Negotiator from 'negotiator';
+import appendVary from '../lib/vary.js';
+
+const NO_COMPRESS_STATUSES = new Set([204, 304]);
+const COMPRESSIBLE_RE = /^(text\/|application\/(json|javascript|xml|x-www-form-urlencoded))/;
+
+/**
+ * Creates a response compression middleware.
+ *
+ * @param {object} [options] - Compression configuration
+ * @param {number} [options.threshold=1024] - Minimum byte size before compression is applied
+ * @param {string[]} [options.encodings=['br','gzip','deflate']] - Supported encodings in priority order
+ * @returns {function} - Ergo middleware `(req, res) => void` that wraps `res.write`/`res.end`
+ */
+export default ({threshold = 1024, encodings = ['br', 'gzip', 'deflate']} = {}) => {
+  return (req, res) => {
+    const acceptEncoding = req.headers['accept-encoding'] ?? '';
+    const encoding = negotiate(acceptEncoding, encodings);
+
+    if (!encoding) {
+      return;
+    }
+
+    const origEnd = res.end.bind(res);
+    const origWrite = res.write.bind(res);
+    const origSetHeader = res.setHeader.bind(res);
+
+    let headersSent = false;
+    let compressor;
+
+    function setupCompressor() {
+      if (headersSent) {
+        return;
+      }
+
+      const contentType = res.getHeader('content-type') ?? '';
+      if (!COMPRESSIBLE_RE.test(contentType)) {
+        return;
+      }
+
+      if (NO_COMPRESS_STATUSES.has(res.statusCode)) {
+        return;
+      }
+
+      compressor = createCompressor(encoding);
+      if (!compressor) {
+        return;
+      }
+
+      origSetHeader('Content-Encoding', encoding);
+      res.removeHeader('Content-Length');
+
+      appendVary(res, 'Accept-Encoding');
+
+      headersSent = true;
+
+      compressor.on('data', chunk => origWrite(chunk));
+      compressor.on('end', () => origEnd());
+      compressor.on('error', () => origEnd());
+    }
+
+    res.write = function compressedWrite(chunk, encodingArg, cb) {
+      if (!compressor) {
+        setupCompressor();
+      }
+      if (compressor) {
+        return compressor.write(chunk, encodingArg, cb);
+      }
+      return origWrite(chunk, encodingArg, cb);
+    };
+
+    res.end = function compressedEnd(chunk, encodingArg, cb) {
+      if (!compressor && chunk) {
+        const size = typeof chunk === 'string' ? Buffer.byteLength(chunk) : chunk.length;
+        if (size < threshold) {
+          return origEnd(chunk, encodingArg, cb);
+        }
+        setupCompressor();
+      }
+      if (compressor) {
+        if (chunk) {
+          compressor.end(chunk, encodingArg);
+        } else {
+          compressor.end();
+        }
+      } else {
+        origEnd(chunk, encodingArg, cb);
+      }
+    };
+  };
+};
+
+/**
+ * Negotiate the best encoding from Accept-Encoding, respecting quality values.
+ * Uses the `negotiator` package for RFC 7231 §5.3.4-compliant parsing.
+ * Excludes `identity` since we are selecting a compression encoding.
+ *
+ * @param {string} acceptEncoding - Value of the Accept-Encoding request header
+ * @param {string[]} supported - Supported compression encodings in priority order
+ * @returns {string|undefined} - The best matched encoding name, or undefined if none matched
+ */
+function negotiate(acceptEncoding, supported) {
+  if (!acceptEncoding) return;
+  const negotiator = new Negotiator({headers: {'accept-encoding': acceptEncoding}});
+  const preferred = negotiator.encodings(supported);
+  return preferred.find(e => e !== 'identity');
+}
+
+/**
+ * Create a zlib compressor Transform stream for the given encoding.
+ *
+ * @param {string} encoding - One of 'gzip', 'deflate', 'br'
+ * @returns {import('node:zlib').Gzip|import('node:zlib').Deflate|import('node:zlib').BrotliCompress|undefined} - Compressor stream, or undefined for unsupported encodings
+ */
+function createCompressor(encoding) {
+  switch (encoding) {
+    case 'gzip':
+      return zlib.createGzip();
+    case 'deflate':
+      return zlib.createDeflate();
+    case 'br':
+      return zlib.createBrotliCompress();
+    default:
+      return;
+  }
+}

package/http/cookie.js

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview HTTP middleware factory for cookie parsing.
+ *
+ * Parses the `Cookie` request header into a cookie jar using the RFC 6265 compliant
+ * `lib/cookie` module.
+ *
+ * The jar uses dual storage: incoming cookies from the header are available as own
+ * properties (`acc.cookies.session`), while outgoing cookies created via `set()` are
+ * stored in an internal Map and serialized by `toHeader()` into `Set-Cookie` headers.
+ *
+ * Cookie values are available on the accumulator for CSRF verification, session handling,
+ * and other cookie-based workflows.
+ *
+ * @module http/cookie
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../lib/cookie/index.js
+ *
+ * @example
+ * import {compose, cookie} from 'ergo';
+ *
+ * const pipeline = compose(
+ *   [cookie(), 'cookies'],
+ *   // acc.cookies.session => 'abc123' (incoming cookie, own property)
+ * );
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc6265 RFC 6265 - HTTP State Management Mechanism}
+ */
+import {parse, jar} from '../lib/cookie/index.js';
+
+/**
+ * Creates a cookie parsing middleware.
+ *
+ * @param {object} [options] - Options forwarded to the RFC 6265 cookie parser
+ * @returns {function} - Ergo middleware `({headers}) => CookieJar`
+ */
+export default options =>
+  ({headers: {cookie} = {}} = {}) =>
+    jar(parse(cookie, options));

package/http/cors.js

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview HTTP middleware factory for CORS header injection.
+ *
+ * Validates incoming CORS requests against configured allowed origins, methods, and headers.
+ * When the `Origin` request header is present, runs the CORS policy check and either:
+ * - Injects the appropriate CORS response headers (allowed), or
+ * - Returns `{response: {statusCode: 403}}` (denied)
+ *
+ * When no `Origin` header is present, the middleware is a no-op (non-CORS requests pass through).
+ * Pre-flight `OPTIONS` requests should be handled at the router level using `ergo-router`.
+ *
+ * @module http/cors
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../lib/cors.js
+ * @requires ../utils/http-errors.js
+ *
+ * @example
+ * import {compose, cors} from 'ergo';
+ *
+ * const pipeline = compose(
+ *   [cors({
+ *     origins: ['https://app.example.com'],
+ *     allowMethods: ['GET', 'POST'],
+ *     allowHeaders: ['Authorization', 'Content-Type']
+ *   }), 'cors'],
+ * );
+ *
+ * @see {@link https://fetch.spec.whatwg.org/#http-cors-protocol Fetch Standard - CORS Protocol}
+ */
+import cors from '../lib/cors.js';
+
+/**
+ * Creates a CORS validation middleware.
+ *
+ * @param {object} [options] - CORS policy options forwarded to `lib/cors`
+ * @param {string|string[]|RegExp|function} [options.origins='*'] - Allowed origins
+ * @param {string[]} [options.allowMethods] - Allowed HTTP methods
+ * @param {string|string[]|RegExp|function} [options.allowHeaders='*'] - Allowed request headers
+ * @param {string|string[]} [options.exposeHeaders] - Headers to expose to the client
+ * @param {boolean} [options.allowCredentials=false] - Whether to allow credentials
+ * @param {number} [options.maxAge] - Preflight cache duration in seconds
+ * @returns {function} - Ergo middleware that returns `undefined` for non-CORS requests,
+ *   `{response: {headers}}` when allowed, or `{response: {statusCode: 403}}` when denied
+ */
+export default options => {
+  const corsValidator = cors(options);
+
+  return ({
+    headers: {
+      origin,
+      'access-control-request-method': requestMethod,
+      'access-control-request-headers': requestHeadersRaw
+    } = {},
+    method
+  } = {}) => {
+    // Only if Origin is defined is it CORS
+    if (origin !== undefined) {
+      const requestHeaders = requestHeadersRaw
+        ? requestHeadersRaw.split(',').map(h => h.trim())
+        : undefined;
+
+      const {
+        allowed,
+        info: {headers}
+      } = corsValidator({origin, method, requestMethod, requestHeaders});
+
+      if (allowed === false) {
+        return {response: {statusCode: 403}};
+      }
+
+      return {
+        response: {
+          headers: headers.map(({h, v}) => [h, v])
+        }
+      };
+    }
+  };
+};

package/http/csrf.js

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview HTTP middleware factory for CSRF protection.
+ *
+ * Provides two methods on the returned object:
+ * - `issue(req, res, ...acc)` — generates a new CSRF token/UUID pair and sets them as cookies
+ * - `verify(req, res, ...acc)` — validates the `X-CSRF-TOKEN` header against the cookie value
+ *
+ * Tokens are HMAC-signed with a shared `secret` using `lib/csrf`. Verification uses
+ * `crypto.timingSafeEqual()` to prevent timing attacks.
+ *
+ * The CSRF UUID is stored in a separate cookie so the token can be regenerated independently.
+ *
+ * @module http/csrf
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../lib/csrf.js
+ * @requires ../utils/http-errors.js
+ *
+ * @example
+ * import {compose, cookie, csrf} from 'ergo';
+ *
+ * const csrfMiddleware = csrf({secret: process.env.CSRF_SECRET});
+ *
+ * // Issue a token on GET (e.g. page load)
+ * const issuePipeline = compose(
+ *   [cookie(), 'cookies'],
+ *   [csrfMiddleware.issue, 'csrf'],
+ * );
+ *
+ * // Verify on state-mutating requests
+ * const verifyPipeline = compose(
+ *   [cookie(), 'cookies'],
+ *   [csrfMiddleware.verify, 'csrf'],
+ * );
+ *
+ * @see {@link https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html OWASP CSRF Prevention Cheat Sheet}
+ */
+import {issue, verify} from '../lib/csrf.js';
+
+/**
+ * Creates a CSRF token issuance and verification middleware.
+ *
+ * @param {object} [options] - CSRF configuration
+ * @param {string} [options.cookieTokenName='CSRF-TOKEN'] - Cookie name for the CSRF token
+ * @param {string} [options.headerTokenName='X-CSRF-TOKEN'] - Request header name for the CSRF token
+ * @param {string} [options.cookieUuidName='CSRF-UUID'] - Cookie name for the CSRF UUID
+ * @param {string} options.secret - HMAC secret for token signing
+ * @param {string} [options.encoding] - Token encoding (default: base64)
+ * @param {object} [options.cookieOptions={}] - Cookie directives passed to the cookie factory
+ * @returns {object} - Object with `issue(req, res, ...rest)` and `verify(req, res, ...rest)` methods;
+ *   `verify` returns `{response: {statusCode: 403}}` when CSRF token verification fails
+ */
+export default ({
+  cookieTokenName = 'CSRF-TOKEN',
+  headerTokenName = 'X-CSRF-TOKEN',
+  cookieUuidName = 'CSRF-UUID',
+  secret,
+  encoding,
+  cookieOptions = {}
+} = {}) => ({
+  issue(req, res, acc) {
+    const {cookies} = acc;
+
+    const {token, uuid} = issue(secret, undefined, encoding);
+
+    cookies.set(cookieTokenName, token, {...cookieOptions, httpOnly: false, sameSite: 'Strict'});
+    cookies.set(cookieUuidName, uuid, {...cookieOptions, sameSite: 'Strict'});
+  },
+  verify({headers: {[headerTokenName.toLowerCase()]: headerToken} = {}} = {}, res, acc) {
+    const {cookies: {[cookieUuidName]: uuid} = {}} = acc;
+
+    if (headerToken === undefined || uuid === undefined || !verify(headerToken, {secret, uuid})) {
+      return {response: {statusCode: 403, detail: 'CSRF verification failed'}};
+    }
+  }
+});

package/http/handler.js

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview HTTP request handler factory (v2 two-accumulator model).
+ *
+ * Creates a request handler suitable for `http.createServer()` that:
+ * 1. Creates a fresh domain accumulator and response accumulator per request.
+ * 2. Runs the composed pipeline with both accumulators.
+ * 3. On unexpected errors, sets `responseAcc.statusCode = 500` (unless already set by
+ *    timeout or an earlier pipeline break), populates `instance` from the request-id
+ *    header, and emits the error on the response for any listeners.
+ * 4. Calls `send()` exactly once with both accumulators.
+ *
+ * This is the standalone equivalent of ergo-router's `auto-wrap.js` — for users who
+ * compose middleware directly without the router.
+ *
+ * @module http/handler
+ * @version 0.2.0
+ * @since 0.1.0
+ *
+ * @example
+ * import {handler, compose, send, logger, authorization, body} from 'ergo';
+ *
+ * const pipeline = compose(
+ *   [logger(), 'log'],
+ *   [authorization({strategies}), 'auth'],
+ *   [body(), 'body'],
+ *   (req, res, acc) => ({response: {body: processRequest(acc), statusCode: 200}})
+ * );
+ *
+ * const server = http.createServer(handler(pipeline));
+ */
+import {accumulator} from '../utils/compose.js';
+import {createResponseAcc} from '../utils/compose-with.js';
+import attachInstance from '../lib/attach-instance.js';
+import createSend from './send.js';
+
+/**
+ * Creates the outermost request handler.
+ *
+ * @param {function} pipeline - Composed middleware pipeline
+ * @param {object} [sendOptions] - Options forwarded to `send()`
+ * @returns {function} - Async handler `(req, res) => void` for `http.createServer()`
+ */
+export default (pipeline, sendOptions = {}) => {
+  const send = createSend(sendOptions);
+
+  return async (req, res) => {
+    const domainAcc = accumulator();
+    const responseAcc = createResponseAcc();
+
+    try {
+      await pipeline(req, res, responseAcc, domainAcc);
+    } catch (err) {
+      if (responseAcc.statusCode === undefined) {
+        responseAcc.statusCode = 500;
+        responseAcc.detail = 'Internal Server Error';
+      }
+
+      attachInstance(responseAcc, res);
+
+      if (res.listenerCount('error') > 0) {
+        res.emit('error', err);
+      }
+    }
+
+    try {
+      send(req, res, responseAcc, domainAcc);
+    } catch {
+      if (!res.writableEnded) {
+        res.statusCode = 500;
+        res.end();
+      }
+    }
+  };
+};

package/http/index.js

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Entry point for the @centralping/ergo package.
+ *
+ * Re-exports the main module for ESM consumers:
+ * `import { handler, send } from '@centralping/ergo'`
+ *
+ * @module @centralping/ergo
+ * @version 0.1.0-beta.1
+ * @since 0.1.0
+ * @requires ./main.js
+ */
+
+export * from './main.js';

package/http/json-api-query.js

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview HTTP middleware factory for JSON:API query parameter validation.
+ *
+ * Validates the parsed query accumulator against the JSON:API query parameter schema,
+ * enforcing correct use of `filter`, `sort`, `fields`, `include`, and `page` parameters.
+ *
+ * Delegates validation to the vendored `lib/json-api-query` module (AJV 8, JSON Schema 2020-12).
+ * On validation failure, returns `{response: {statusCode: 400, detail: ...}}` (RFC 9457 body
+ * formatted by `send()` after the pipeline).
+ *
+ * Must be placed after `url()` in the pipeline so that `acc.url` is populated.
+ *
+ * @module http/json-api-query
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../lib/json-api-query/index.js
+ * @requires ../utils/http-errors.js
+ *
+ * @example
+ * import {compose, url, jsonApiQuery} from 'ergo';
+ *
+ * const pipeline = compose(
+ *   [url(), 'url'],
+ *   [jsonApiQuery(), 'jsonApiQuery'],
+ *   // Returns 400 response if query params are not JSON:API compliant
+ * );
+ */
+import {validate} from '../lib/json-api-query/index.js';
+
+/**
+ * Creates a JSON:API query validation middleware.
+ *
+ * @param {...*} options - Options forwarded to the underlying JSON:API validator
+ * @returns {function} - Ergo middleware `(req, res, acc) => void`; returns
+ *   `{response: {statusCode: 400}}` when JSON:API query parameters fail validation
+ */
+export default (...options) => {
+  const validator = validate(...options);
+
+  return (req, res, acc) => {
+    const query = acc.url?.query;
+    const valid = validator(query);
+
+    if (!valid) {
+      return {
+        response: {
+          statusCode: 400,
+          detail: 'Invalid JSON API query'
+        }
+      };
+    }
+  };
+};