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

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/main.js

@@ -80,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';
@@ -99,6 +100,7 @@ export {
   csrf,
   fromConnect,
   httpErrors,
+  idempotency,
   jsonApiQuery,
   logger,
   prefer,
@@ -126,6 +128,7 @@ export default {
   csrf,
   fromConnect,
   httpErrors,
+  idempotency,
   jsonApiQuery,
   logger,
   prefer,

package/lib/idempotency.js

@@ -0,0 +1,139 @@
+/**
+ * @fileoverview Idempotency-Key shared primitives.
+ *
+ * Provides the core building blocks for idempotent request handling per
+ * draft-ietf-httpapi-idempotency-key-header-07. The `IdempotencyStore`
+ * manages key lifecycle (storage, expiry, replay). `parseIdempotencyKey`
+ * extracts the key value from the RFC 8941 structured field header.
+ * `generateFingerprint` creates a SHA-256 hash of the request body for
+ * detecting key reuse with different payloads.
+ *
+ * Used by:
+ * - `http/idempotency.js` (ergo pipeline middleware)
+ *
+ * @module lib/idempotency
+ * @since 0.1.0-beta.2
+ *
+ * @example
+ * import {IdempotencyStore, parseIdempotencyKey, generateFingerprint}
+ *   from '@centralping/ergo/lib/idempotency';
+ *
+ * const store = new IdempotencyStore();
+ * const key = parseIdempotencyKey(req.headers['idempotency-key']);
+ * const fingerprint = generateFingerprint(body);
+ *
+ * @see {@link https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/ Idempotency-Key Header (IETF Draft)}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8941 RFC 8941 - Structured Field Values}
+ */
+import {createHash} from 'node:crypto';
+
+const SF_STRING_RE = /^"([^"\\]*(?:\\.[^"\\]*)*)"$/;
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+/**
+ * In-memory idempotency key store with TTL-based expiry.
+ *
+ * Entries transition through states: `processing` -> `complete`.
+ * Expired entries are pruned lazily on `get()` calls.
+ */
+export class IdempotencyStore {
+  constructor({maxKeys = 10_000, ttlMs = DEFAULT_TTL_MS} = {}) {
+    this._entries = new Map();
+    this._maxKeys = maxKeys;
+    this._ttlMs = ttlMs;
+  }
+
+  /**
+   * Retrieve a stored entry by key. Returns `undefined` if not found or expired.
+   * @param {string} key - Idempotency key
+   * @returns {{fingerprint: string, response: object, status: string, expiresAt: number} | undefined}
+   */
+  get(key) {
+    const entry = this._entries.get(key);
+    if (!entry) return undefined;
+
+    if (Date.now() > entry.expiresAt) {
+      this._entries.delete(key);
+      return undefined;
+    }
+
+    return entry;
+  }
+
+  /**
+   * Store a new idempotency entry in `processing` state.
+   * @param {string} key - Idempotency key
+   * @param {string} fingerprint - Request body fingerprint
+   */
+  set(key, fingerprint) {
+    if (this._entries.size >= this._maxKeys) {
+      const oldest = this._entries.keys().next().value;
+      this._entries.delete(oldest);
+    }
+
+    const entry = Object.create(null);
+    entry.fingerprint = fingerprint;
+    entry.response = undefined;
+    entry.status = 'processing';
+    entry.expiresAt = Date.now() + this._ttlMs;
+    this._entries.set(key, entry);
+  }
+
+  /**
+   * Mark an entry as complete with the response to replay.
+   * @param {string} key - Idempotency key
+   * @param {object} response - Response accumulator snapshot to replay
+   */
+  complete(key, response) {
+    const entry = this._entries.get(key);
+    if (entry) {
+      entry.status = 'complete';
+      entry.response = response;
+    }
+  }
+
+  /**
+   * Remove an entry (e.g. on request failure where replay is not desired).
+   * @param {string} key - Idempotency key
+   */
+  delete(key) {
+    this._entries.delete(key);
+  }
+}
+
+/**
+ * Parse an `Idempotency-Key` header value as an RFC 8941 sf-string.
+ *
+ * The draft specifies the header is an Item Structured Header whose value
+ * is a String. This means the wire format is `"value"` (double-quoted).
+ * Returns `undefined` for missing, empty, or malformed values.
+ *
+ * @param {string | undefined} header - Raw header value
+ * @returns {string | undefined} - Parsed key value, or undefined
+ */
+export function parseIdempotencyKey(header) {
+  if (!header) return undefined;
+
+  const trimmed = header.trim();
+  const match = SF_STRING_RE.exec(trimmed);
+  if (!match) return undefined;
+
+  const inner = match[1];
+  if (inner.replace(/\\["\\]/g, '').includes('\\')) return undefined;
+  return inner.replace(/\\(["\\])/g, '$1');
+}
+
+/**
+ * Generate a SHA-256 fingerprint of the request body.
+ *
+ * Used to detect key reuse with different payloads (which should return 409).
+ * Accepts strings or Buffers. Returns the hex digest.
+ *
+ * @param {string | Buffer} body - Serialized request body
+ * @returns {string} - Hex-encoded SHA-256 hash
+ */
+export function generateFingerprint(body) {
+  return createHash('sha256')
+    .update(body ?? '')
+    .digest('hex');
+}

package/lib/link.js

@@ -2,9 +2,9 @@
  * @fileoverview RFC 8288 Web Linking utilities.
  *
  * Provides functions for formatting `Link` response headers per RFC 8288.
- * `formatLinkHeader` is the low-level formatter; `paginationLinks` is a
- * convenience helper that generates `first`, `prev`, `next`, `last` link
- * objects from pagination parameters.
+ * `formatLinkHeader` is the low-level formatter; `paginationLinks` and
+ * `cursorPaginationLinks` are convenience helpers that generate link objects
+ * for offset-based and cursor-based pagination respectively.
  *
  * These are pure utility functions (not middleware). Consumers wire the
  * formatted header value into the accumulator's `headers` array for `send()`.
@@ -15,8 +15,10 @@
  * @see {@link https://www.rfc-editor.org/rfc/rfc8288 RFC 8288 - Web Linking}
  *
  * @example
- * import {formatLinkHeader, paginationLinks} from '@centralping/ergo/lib/link';
+ * import {formatLinkHeader, paginationLinks, cursorPaginationLinks}
+ *   from '@centralping/ergo/lib/link';
  *
+ * // Offset-based pagination
  * const links = paginationLinks({
  *   baseUrl: '/articles',
  *   searchParams: 'sort=date',
@@ -26,6 +28,15 @@
  * });
  * const header = formatLinkHeader(links);
  * // '</articles?sort=date&page=1&per_page=25>; rel="first", ...'
+ *
+ * // Cursor-based pagination
+ * const cursorLinks = cursorPaginationLinks({
+ *   baseUrl: '/articles',
+ *   searchParams: 'sort=date',
+ *   nextCursor: 'eyJpZCI6NDJ9.abc123'
+ * });
+ * const cursorHeader = formatLinkHeader(cursorLinks);
+ * // '</articles?sort=date>; rel="first", </articles?sort=date&cursor=eyJpZCI6NDJ9.abc123>; rel="next"'
  */
 import sanitizeQuotedString from './sanitize-quoted-string.js';
 
@@ -93,3 +104,45 @@ export function paginationLinks({baseUrl, page, perPage, total, searchParams = '
 
   return links;
 }
+
+/**
+ * Generates cursor-based pagination link objects for first, prev, and next pages.
+ *
+ * Unlike offset pagination, cursor-based pagination uses opaque continuation
+ * tokens instead of page numbers. There is no `last` link because the total
+ * number of pages is unknown in cursor-based schemes.
+ *
+ * The `first` link is always present and points to the base URL without any
+ * cursor parameter (requesting the first page). `prev` and `next` are
+ * included only when the corresponding cursor token is provided.
+ *
+ * @param {object} options - Cursor pagination parameters
+ * @param {string} options.baseUrl - Base URL path (e.g. '/articles')
+ * @param {string} [options.searchParams=''] - Additional query parameters to preserve
+ *   (e.g. 'sort=date&filter=active'). Appended before the cursor parameter.
+ * @param {string} [options.nextCursor] - Opaque cursor token for the next page
+ * @param {string} [options.prevCursor] - Opaque cursor token for the previous page
+ * @returns {Array<{href: string, rel: string}>} - Array of link objects
+ */
+export function cursorPaginationLinks({baseUrl, searchParams = '', nextCursor, prevCursor}) {
+  const base = searchParams ? `${baseUrl}?${searchParams}` : baseUrl;
+  const sep = searchParams ? '&' : '?';
+
+  const links = [{href: base, rel: 'first'}];
+
+  if (prevCursor !== undefined) {
+    links.push({
+      href: `${base}${sep}cursor=${encodeURIComponent(prevCursor)}`,
+      rel: 'prev'
+    });
+  }
+
+  if (nextCursor !== undefined) {
+    links.push({
+      href: `${base}${sep}cursor=${encodeURIComponent(nextCursor)}`,
+      rel: 'next'
+    });
+  }
+
+  return links;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centralping/ergo",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.3",
   "description": "A Fast Fail REST API toolkit for Node.js -- composable middleware with structured Negotiation, Authorization, Validation, and Execution stages.",
   "main": "http/index.js",
   "type": "module",

package/types/http/idempotency.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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, methods }?: {
+    store?: object | undefined;
+    ttlMs?: number | undefined;
+    required?: boolean | undefined;
+    methods?: string[] | Set<string> | undefined;
+}): Function;

package/types/http/main.d.ts

@@ -75,6 +75,7 @@ declare const _default: {
     }) => object;
     fromConnect: typeof fromConnect;
     httpErrors: typeof httpErrors;
+    idempotency: typeof idempotency;
     jsonApiQuery: (...options: any[]) => Function;
     logger: ({ log, error: logError, uuid, headerRequestIdName, headerRequestIpName, redactHeaders }?: {
         log?: Function | undefined;
@@ -129,6 +130,7 @@ import cors from './cors.js';
 import csrf from './csrf.js';
 import fromConnect from '../lib/from-connect.js';
 import httpErrors from '../utils/http-errors.js';
+import idempotency from './idempotency.js';
 import jsonApiQuery from './json-api-query.js';
 import logger from './logger.js';
 import prefer from './prefer.js';
@@ -139,4 +141,4 @@ import url from './url.js';
 import send from './send.js';
 import timeout from './timeout.js';
 import validate from './validate.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 };
+export { compose, createResponseAcc, mergeResponse, handler, accepts, authorization, body, cacheControl, compress, cookie, cors, csrf, fromConnect, httpErrors, idempotency, jsonApiQuery, logger, prefer, precondition, rateLimit, securityHeaders, url, send, timeout, validate };

package/types/lib/idempotency.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Parse an `Idempotency-Key` header value as an RFC 8941 sf-string.
+ *
+ * The draft specifies the header is an Item Structured Header whose value
+ * is a String. This means the wire format is `"value"` (double-quoted).
+ * Returns `undefined` for missing, empty, or malformed values.
+ *
+ * @param {string | undefined} header - Raw header value
+ * @returns {string | undefined} - Parsed key value, or undefined
+ */
+export function parseIdempotencyKey(header: string | undefined): string | undefined;
+/**
+ * Generate a SHA-256 fingerprint of the request body.
+ *
+ * Used to detect key reuse with different payloads (which should return 409).
+ * Accepts strings or Buffers. Returns the hex digest.
+ *
+ * @param {string | Buffer} body - Serialized request body
+ * @returns {string} - Hex-encoded SHA-256 hash
+ */
+export function generateFingerprint(body: string | Buffer): string;
+/**
+ * In-memory idempotency key store with TTL-based expiry.
+ *
+ * Entries transition through states: `processing` -> `complete`.
+ * Expired entries are pruned lazily on `get()` calls.
+ */
+export class IdempotencyStore {
+    constructor({ maxKeys, ttlMs }?: {
+        maxKeys?: number | undefined;
+        ttlMs?: number | undefined;
+    });
+    _entries: Map<any, any>;
+    _maxKeys: number;
+    _ttlMs: number;
+    /**
+     * Retrieve a stored entry by key. Returns `undefined` if not found or expired.
+     * @param {string} key - Idempotency key
+     * @returns {{fingerprint: string, response: object, status: string, expiresAt: number} | undefined}
+     */
+    get(key: string): {
+        fingerprint: string;
+        response: object;
+        status: string;
+        expiresAt: number;
+    } | undefined;
+    /**
+     * Store a new idempotency entry in `processing` state.
+     * @param {string} key - Idempotency key
+     * @param {string} fingerprint - Request body fingerprint
+     */
+    set(key: string, fingerprint: string): void;
+    /**
+     * Mark an entry as complete with the response to replay.
+     * @param {string} key - Idempotency key
+     * @param {object} response - Response accumulator snapshot to replay
+     */
+    complete(key: string, response: object): void;
+    /**
+     * Remove an entry (e.g. on request failure where replay is not desired).
+     * @param {string} key - Idempotency key
+     */
+    delete(key: string): void;
+}

package/types/lib/link.d.ts

@@ -35,3 +35,31 @@ export function paginationLinks({ baseUrl, page, perPage, total, searchParams }:
     href: string;
     rel: string;
 }>;
+/**
+ * Generates cursor-based pagination link objects for first, prev, and next pages.
+ *
+ * Unlike offset pagination, cursor-based pagination uses opaque continuation
+ * tokens instead of page numbers. There is no `last` link because the total
+ * number of pages is unknown in cursor-based schemes.
+ *
+ * The `first` link is always present and points to the base URL without any
+ * cursor parameter (requesting the first page). `prev` and `next` are
+ * included only when the corresponding cursor token is provided.
+ *
+ * @param {object} options - Cursor pagination parameters
+ * @param {string} options.baseUrl - Base URL path (e.g. '/articles')
+ * @param {string} [options.searchParams=''] - Additional query parameters to preserve
+ *   (e.g. 'sort=date&filter=active'). Appended before the cursor parameter.
+ * @param {string} [options.nextCursor] - Opaque cursor token for the next page
+ * @param {string} [options.prevCursor] - Opaque cursor token for the previous page
+ * @returns {Array<{href: string, rel: string}>} - Array of link objects
+ */
+export function cursorPaginationLinks({ baseUrl, searchParams, nextCursor, prevCursor }: {
+    baseUrl: string;
+    searchParams?: string | undefined;
+    nextCursor?: string | undefined;
+    prevCursor?: string | undefined;
+}): Array<{
+    href: string;
+    rel: string;
+}>;