@centralping/ergo 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -1,8 +1,8 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-wordmark-dark.svg">
-    <source media="(prefers-color-scheme: light)" srcset="assets/logo-wordmark-light.svg">
-    <img alt="ergo" src="assets/logo-wordmark-light.svg" width="240">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/CentralPing/ergo/main/assets/logo-wordmark-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/CentralPing/ergo/main/assets/logo-wordmark-light.svg">
+    <img alt="ergo" src="https://raw.githubusercontent.com/CentralPing/ergo/main/assets/logo-wordmark-light.svg" width="240">
   </picture>
 </p>
 
@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/@centralping/ergo.svg)](https://www.npmjs.com/package/@centralping/ergo)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/CentralPing/ergo/badge)](https://scorecard.dev/viewer/?uri=github.com/CentralPing/ergo)
 [![Node.js >=22](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/CentralPing/ergo/blob/main/LICENSE)
 
 A **Fast Fail** REST API toolkit for Node.js. _ergo_ (error or go) provides composable, stream-native middleware organized around the principle that a server should fail as early as possible -- before doing any expensive work -- through four ordered stages: **Negotiation, Authorization, Validation, and Execution**. Every behavior is backed by an IETF RFC or industry standard, not invented conventions.
 
@@ -57,20 +57,19 @@ Requires **Node.js >= 22**.
 
 ```js
 import {createServer} from 'node:http';
-import {compose, handler, logger, cors, authorization, body, send} from '@centralping/ergo';
+import {compose, handler, logger, cors, authorization, body} from '@centralping/ergo';
 
 const pipeline = compose(
-  [logger(), [], 'log'],
-  [cors(), [], 'cors'],
+  [logger(), 'log'],
+  [cors(), 'cors'],
   [authorization({strategies: [{type: 'Bearer', authorizer: (_, token) =>
     token === 'my-token' ? {authorized: true, info: {uid: 1}} : {}
-  }]}), [], 'auth'],
-  [body(), [], 'body'],
-  (req, res, {auth, body}) => ({body: {user: auth, data: body.parsed}}),
-  send()
+  }]}), 'auth'],
+  [body(), 'body'],
+  (req, res, acc) => ({response: {body: {user: acc.auth, data: acc.body.parsed}}})
 );
 
-createServer(handler(pipeline, send())).listen(3000);
+createServer(handler(pipeline)).listen(3000);
 ```
 
 ## Middleware Overview
@@ -96,7 +95,7 @@ createServer(handler(pipeline, send())).listen(3000);
 | `cacheControl()` | Cache-Control header management | [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111) |
 | `jsonApiQuery()` | JSON:API query parameter validation | [JSON:API](https://jsonapi.org/) |
 
-See the [full API reference](https://centralping.github.io/api/ergo/) for detailed options and examples.
+See the [full API reference](https://centralping.github.io/packages/ergo/) for detailed options and examples.
 
 ## Standards Compliance
 
@@ -120,8 +119,8 @@ See the [full API reference](https://centralping.github.io/api/ergo/) for detail
 ## Documentation
 
 - [Getting Started](https://centralping.github.io/getting-started/)
-- [API Reference](https://centralping.github.io/api/ergo/)
-- [Architecture & Design](https://centralping.github.io/architecture/)
+- [API Reference](https://centralping.github.io/packages/ergo/)
+- [Fast Fail Pipeline](https://centralping.github.io/concepts/fast-fail/)
 - [Benchmarks](https://centralping.github.io/benchmarks/)
 
 ## Development

package/http/accepts.js

@@ -10,13 +10,12 @@
  * Fast Fail pipeline.
  *
  * @module http/accepts
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../lib/accepts.js
  * @requires ../utils/http-errors.js
  *
  * @example
- * import {compose, accepts} from 'ergo';
+ * import {compose, accepts} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [accepts({types: ['application/json']}), 'accepts'],

package/http/authorization.js

@@ -10,13 +10,12 @@
  * response header (RFC 7235).
  *
  * @module http/authorization
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../lib/authorization.js
  * @requires ../utils/http-errors.js
  *
  * @example
- * import {compose, authorization} from 'ergo';
+ * import {compose, authorization} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [authorization({

package/http/body.js

@@ -17,7 +17,6 @@
  * 3-stream pipeline for reduced per-request overhead.
  *
  * @module http/body
- * @version 0.1.0
  * @since 0.1.0
  * @requires node:stream
  * @requires node:zlib
@@ -29,7 +28,7 @@
  * @requires ../utils/http-errors.js
  *
  * @example
- * import {compose, body} from 'ergo';
+ * import {compose, body} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [body({limit: 2 * 1024 * 1024}), 'body'],

package/http/cache-control.js

@@ -6,11 +6,10 @@
  * 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';
+ * import {compose, cacheControl} from '@centralping/ergo';
  *
  * // String shorthand
  * const pipeline = compose(

package/http/compress.js

@@ -13,13 +13,12 @@
  * - 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';
+ * import {compose, compress} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   compress({threshold: 1024, encodings: ['br', 'gzip', 'deflate']}),

package/http/cookie.js

@@ -12,12 +12,11 @@
  * 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';
+ * import {compose, cookie} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [cookie(), 'cookies'],

package/http/cors.js

@@ -10,13 +10,12 @@
  * 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';
+ * import {compose, cors} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [cors({

package/http/csrf.js

@@ -11,13 +11,12 @@
  * 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';
+ * import {compose, cookie, csrf} from '@centralping/ergo';
  *
  * const csrfMiddleware = csrf({secret: process.env.CSRF_SECRET});
  *

package/http/handler.js

@@ -13,11 +13,10 @@
  * 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';
+ * import {handler, compose, logger, authorization, body} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [logger(), 'log'],

package/http/idempotency.js

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Idempotency-Key pipeline middleware.
+ *
+ * Detects duplicate requests by `Idempotency-Key` header value per
+ * draft-ietf-httpapi-idempotency-key-header-07. When a matching key with
+ * the same request fingerprint is found, the stored response is replayed.
+ * When a key matches but the fingerprint differs, a 409 Conflict is returned.
+ *
+ * Placed in Stage 3 (Validation) after body parsing so the request body
+ * fingerprint can be computed from the parsed body.
+ *
+ * @module http/idempotency
+ * @since 0.1.0-beta.2
+ * @requires ../lib/idempotency.js
+ *
+ * @example
+ * import {compose, body, idempotency} from '@centralping/ergo';
+ *
+ * const pipeline = compose(
+ *   [body(), 'body'],
+ *   [idempotency({required: true}), 'idempotency'],
+ *   (req, res, acc) => ({response: {statusCode: 201, body: {created: true}}})
+ * );
+ *
+ * @see {@link https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/ Idempotency-Key Header (IETF Draft)}
+ */
+import {IdempotencyStore, parseIdempotencyKey, generateFingerprint} from '../lib/idempotency.js';
+
+const DEFAULT_METHODS = new Set(['POST', 'PATCH']);
+
+/**
+ * Create an idempotency middleware.
+ *
+ * @param {object} [options]
+ * @param {object} [options.store] - Pluggable store (must implement get/set/complete/delete).
+ *   Defaults to an in-memory store with 24h TTL.
+ * @param {number} [options.ttlMs=86400000] - TTL for stored entries in milliseconds (default: 24h).
+ *   Only used when creating the default in-memory store.
+ * @param {boolean} [options.required=false] - When true, returns 400 if the header is missing
+ *   on applicable methods
+ * @param {Set<string>|string[]} [options.methods] - HTTP methods to apply idempotency to
+ *   (default: POST, PATCH)
+ * @returns {function} - Middleware `(req, res, domainAcc) => {value?, response?}`
+ */
+export default function idempotency({store, ttlMs, required = false, methods} = {}) {
+  const _store = store ?? new IdempotencyStore(ttlMs ? {ttlMs} : undefined);
+  const _methods = methods instanceof Set ? methods : new Set(methods ?? DEFAULT_METHODS);
+
+  return (req, _res, domainAcc) => {
+    if (!_methods.has(req.method)) return {};
+
+    const key = parseIdempotencyKey(req.headers?.['idempotency-key']);
+
+    if (!key) {
+      if (required) {
+        return {
+          response: {
+            statusCode: 400,
+            detail: 'Idempotency-Key header is required'
+          }
+        };
+      }
+      return {};
+    }
+
+    const rawBody = domainAcc?.body?.raw ?? domainAcc?.body?.parsed ?? '';
+    const fingerprint = generateFingerprint(
+      typeof rawBody === 'string' ? rawBody : JSON.stringify(rawBody)
+    );
+
+    const existing = _store.get(key);
+
+    if (existing) {
+      if (existing.fingerprint !== fingerprint) {
+        return {
+          response: {
+            statusCode: 409,
+            detail: 'Idempotency key already used with a different request'
+          }
+        };
+      }
+
+      if (existing.status === 'complete' && existing.response) {
+        return {
+          value: {replayed: true},
+          response: existing.response
+        };
+      }
+
+      // Still processing — concurrent duplicate
+      return {
+        response: {
+          statusCode: 409,
+          detail: 'A request with this idempotency key is already being processed'
+        }
+      };
+    }
+
+    _store.set(key, fingerprint);
+
+    return {
+      value: {
+        key,
+        fingerprint,
+        complete: response => _store.complete(key, response),
+        discard: () => _store.delete(key)
+      }
+    };
+  };
+}

package/http/index.js

@@ -1,13 +1,46 @@
 /**
- * @fileoverview Entry point for the @centralping/ergo package.
+ * @fileoverview Fast Fail REST API toolkit for Node.js.
  *
- * Re-exports the main module for ESM consumers:
- * `import { handler, send } from '@centralping/ergo'`
+ * Composable middleware organized into four ordered pipeline stages — a failure
+ * at any stage immediately returns a standards-compliant error response so no
+ * downstream work is wasted:
+ *
+ * | Stage | Middleware | Purpose |
+ * | --- | --- | --- |
+ * | **Negotiation** | {@link logger}, {@link cors}, {@link accepts}, {@link cookie}, {@link url} | Parse/inspect request headers and URL |
+ * | **Authorization** | {@link authorization}, {@link csrf} | Authenticate and verify request integrity |
+ * | **Validation** | {@link body}, {@link jsonApiQuery}, {@link validate} | Parse and validate the request body |
+ * | **Execution** | {@link timeout}, {@link compress}, {@link handler}, {@link send} | Run the handler and serialize the response |
+ *
+ * Cross-cutting middleware available at any stage:
+ * {@link cacheControl}, {@link prefer}, {@link precondition},
+ * {@link rateLimit}, {@link securityHeaders}
+ *
+ * **Composition utilities:** {@link compose}, {@link createResponseAcc},
+ * {@link mergeResponse}, {@link httpErrors}, {@link fromConnect}
  *
  * @module @centralping/ergo
- * @version 0.1.0-beta.1
  * @since 0.1.0
  * @requires ./main.js
+ *
+ * @example
+ * import {compose, handler, logger, cors, accepts, authorization,
+ *         body, send} from '@centralping/ergo';
+ *
+ * const pipeline = compose(
+ *   [logger(), 'log'],
+ *   [cors(), 'cors'],
+ *   [accepts({types: ['application/json']}), 'accepts'],
+ *   [authorization({strategies: [...]}), 'auth'],
+ *   [body(), 'body'],
+ *   (req, res, acc) => ({response: {body: acc.body.parsed}}),
+ * );
+ *
+ * const server = http.createServer(handler(pipeline));
+ *
+ * @see {@link https://centralping.github.io/concepts/fast-fail/ Fast Fail Pipeline}
+ * @see {@link https://centralping.github.io/concepts/security/ Security}
+ * @see {@link https://centralping.github.io/concepts/standards/ Standards Compliance}
  */
 
 export * from './main.js';

package/http/json-api-query.js

@@ -11,13 +11,12 @@
  * 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';
+ * import {compose, url, jsonApiQuery} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [url(), 'url'],

package/http/logger.js

@@ -23,13 +23,12 @@
  * 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';
+ * import {compose, logger} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [logger(), 'log'],

package/http/main.js

@@ -14,8 +14,7 @@
  * accumulated under named keys in `domainAcc`; response properties merge
  * into `responseAcc`. `send()` is called post-pipeline by `handler()`.
  *
- * @module ergo
- * @version 0.1.0
+ * @module @centralping/ergo
  * @since 0.1.0
  * @requires ./handler.js
  * @requires ./accepts.js
@@ -42,7 +41,7 @@
  *
  * @example
  * import {compose, handler, logger, cors, authorization, accepts,
- *         cookie, url, body} from 'ergo';
+ *         cookie, url, body} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   // Stage 1: Negotiation
@@ -81,6 +80,7 @@ import rateLimit from './rate-limit.js';
 import securityHeaders from './security-headers.js';
 import send from './send.js';
 import timeout from './timeout.js';
+import idempotency from './idempotency.js';
 import validate from './validate.js';
 import httpErrors from '../utils/http-errors.js';
 import fromConnect from '../lib/from-connect.js';
@@ -100,6 +100,7 @@ export {
   csrf,
   fromConnect,
   httpErrors,
+  idempotency,
   jsonApiQuery,
   logger,
   prefer,
@@ -127,6 +128,7 @@ export default {
   csrf,
   fromConnect,
   httpErrors,
+  idempotency,
   jsonApiQuery,
   logger,
   prefer,

package/http/precondition.js

@@ -10,11 +10,10 @@
  * 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';
+ * import {compose, precondition} from '@centralping/ergo';
  *
  * // Enforce on all requests (method scoping handled by pipeline builder)
  * const pipeline = compose(

package/http/prefer.js

@@ -8,12 +8,11 @@
  * 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';
+ * import {compose, prefer} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [prefer(), 'prefer'],

package/http/rate-limit.js

@@ -10,12 +10,11 @@
  * 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';
+ * import {compose, rateLimit} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [rateLimit({max: 100, windowMs: 60000}), 'rateLimit'],

package/http/security-headers.js

@@ -8,12 +8,11 @@
  * 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';
+ * import {compose, securityHeaders} from '@centralping/ergo';
  *
  * // Use defaults
  * const pipeline = compose(

package/http/send.js

@@ -29,7 +29,6 @@
  * - Optional response envelope for 2xx Object bodies
  *
  * @module http/send
- * @version 0.2.0
  * @since 0.1.0
  * @requires node:stream
  * @requires node:http
@@ -38,7 +37,7 @@
  * @requires ../lib/vary.js
  *
  * @example
- * import {send, createResponseAcc} from 'ergo';
+ * import {send, createResponseAcc} from '@centralping/ergo';
  *
  * const writer = send({etag: true});
  * // After pipeline completes:

package/http/timeout.js

@@ -12,11 +12,10 @@
  * can be GC'd.
  *
  * @module http/timeout
- * @version 0.2.0
  * @since 0.1.0
  *
  * @example
- * import {compose, timeout} from 'ergo';
+ * import {compose, timeout} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [timeout({ms: 10000, statusCode: 504}), 'timeout'],

package/http/url.js

@@ -11,12 +11,11 @@
  * - `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';
+ * import {compose, url} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [url(), 'url'],

package/http/validate.js

@@ -9,12 +9,11 @@
  * 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';
+ * import {compose, body, url, validate} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [body(), 'body'],

package/lib/accepts.js

@@ -6,13 +6,12 @@
  * 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';
+ * import accepts from '@centralping/ergo/lib/accepts';
  *
  * const negotiate = accepts({types: ['application/json', 'text/html']});
  * const result = negotiate({'accept': 'text/html,application/json;q=0.9'});

package/lib/attach-instance.js

@@ -5,7 +5,6 @@
  * `x-request-id` header, formatted as a `urn:uuid:` URI.
  *
  * @module lib/attach-instance
- * @version 0.1.0
  * @since 0.1.0
  */
 

package/lib/authorization.js

@@ -11,11 +11,10 @@
  * 401 for known schemes (with a `WWW-Authenticate` challenge) or 403 for unrecognized schemes.
  *
  * @module lib/authorization
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import authorize from 'ergo/lib/authorization';
+ * import authorize from '@centralping/ergo/lib/authorization';
  *
  * const authorizer = authorize([{
  *   type: 'Bearer',

package/lib/body/multiparse.js

@@ -12,7 +12,6 @@
  * `Content-Disposition`, `Content-Type`, `Content-Transfer-Encoding`.
  *
  * @module lib/body/multiparse
- * @version 0.1.0
  * @since 0.1.0
  * @requires ./multipart/headers.js
  * @requires ../../utils/iterables/buffer-split.js
@@ -21,7 +20,7 @@
  * @see {@link https://www.rfc-editor.org/rfc/rfc7578}
  *
  * @example
- * import multiparse from 'ergo/lib/body/multiparse';
+ * import multiparse from '@centralping/ergo/lib/body/multiparse';
  *
  * const parts = multiparse(rawBodyBuffer, 'boundary-string');
  * // parts => [{headers: {...}, name: 'file', filename: 'upload.txt', body: Buffer}]

package/lib/body/multipart/headers.js

@@ -11,14 +11,13 @@
  * - `content-transfer-encoding` (deprecated but present in legacy clients)
  *
  * @module lib/body/multipart/headers
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../../../utils/iterables/exec-all.js
  *
  * @see {@link https://www.rfc-editor.org/rfc/rfc7578 RFC 7578 - Returning Values from Forms: multipart/form-data}
  *
  * @example
- * import parseHeaders from 'ergo/lib/body/multipart/headers';
+ * import parseHeaders from '@centralping/ergo/lib/body/multipart/headers';
  *
  * parseHeaders(['Content-Disposition: form-data; name="field1"']);
  * // => {'content-disposition': {type: 'form-data', parameters: {name: 'field1'}}}

package/lib/body/writer.js

@@ -8,13 +8,12 @@
  * `pipeline(req, meter, decompressor, writer())`
  *
  * @module lib/body/writer
- * @version 0.1.0
  * @since 0.1.0
  * @requires node:stream
  *
  * @example
  * import {pipeline} from 'node:stream';
- * import writer from 'ergo/lib/body/writer';
+ * import writer from '@centralping/ergo/lib/body/writer';
  *
  * const w = writer();
  * pipeline(readable, w, err => {