@zudojs/middleware 0.1.0 → 1.0.0

package/dist/middlewareUtils/middlewareUtils.builtins.js

@@ -3,26 +3,62 @@
  *
  * @module middlewareUtils/middlewareUtils
  */
+import { MiddlewareError, MiddlewareRateLimitError, MiddlewareTimeoutError, } from "../middlewareErrors/middlewareError.base.js";
+/** Longest field value written into a log line before truncation. */
+const MAX_LOG_FIELD_LENGTH = 256;
+/** Control characters, which are what let a value break out of its log line. */
+const CONTROL_CHARACTERS = /[\u0000-\u001F\u007F]/g;
+/**
+ * Make a caller-supplied value safe to write into a single-line log.
+ *
+ * CR and LF above all are what let a request path forge extra log lines, so
+ * control characters are escaped rather than dropped — the original stays
+ * visible without being able to break out of its line.
+ */
+export function sanitizeLogValue(value, maxLength = MAX_LOG_FIELD_LENGTH) {
+    const text = typeof value === "string" ? value : String(value);
+    const escaped = text.replace(CONTROL_CHARACTERS, (char) => {
+        if (char === "\n")
+            return "\\n";
+        if (char === "\r")
+            return "\\r";
+        if (char === "\t")
+            return "\\t";
+        return `\\x${char.charCodeAt(0).toString(16).padStart(2, "0")}`;
+    });
+    return escaped.length > maxLength
+        ? `${escaped.slice(0, maxLength)}…`
+        : escaped;
+}
 /**
  * Create a logging middleware.
  *
- * Logs request start, completion, and errors.
+ * Logs request start, completion, and errors. Every interpolated field is
+ * escaped, so a path containing newlines cannot forge log lines.
  */
-export function loggingMiddleware(logger) {
-    const log = logger ?? console.log;
+export function loggingMiddleware(logger, options) {
+    const log = logger ?? ((msg) => console.log(msg));
+    const maxFieldLength = options?.maxFieldLength ?? MAX_LOG_FIELD_LENGTH;
+    const includeErrorMessage = options?.includeErrorMessage ?? false;
     return {
         name: "logging",
         handler: async (ctx, next) => {
             const start = performance.now();
-            log(`[middleware] → ${ctx.method ?? "UNKNOWN"} ${ctx.path ?? "/"}`);
+            const method = sanitizeLogValue(ctx.method ?? "UNKNOWN", maxFieldLength);
+            const path = sanitizeLogValue(ctx.path ?? "/", maxFieldLength);
+            log(`[middleware] → ${method} ${path}`);
             try {
-                await next();
+                const result = await next();
                 const ms = (performance.now() - start).toFixed(1);
                 log(`[middleware] ✓ completed in ${ms}ms`);
+                return result;
             }
             catch (error) {
                 const ms = (performance.now() - start).toFixed(1);
-                log(`[middleware] ✗ failed in ${ms}ms: ${error}`);
+                const detail = includeErrorMessage
+                    ? `: ${sanitizeLogValue(error instanceof Error ? error.message : error, maxFieldLength)}`
+                    : "";
+                log(`[middleware] ✗ failed in ${ms}ms${detail}`);
                 throw error;
             }
         },
@@ -31,9 +67,11 @@ export function loggingMiddleware(logger) {
 /**
  * Create an error-handling middleware.
  *
- * Catches errors and wraps them with context.
+ * Reports errors through `onError` and rethrows them. A reporter that throws
+ * cannot replace the error it was reporting — its own failure goes to
+ * `onReporterError` instead.
  */
-export function errorMiddleware(onError) {
+export function errorMiddleware(onError, onReporterError) {
     return {
         name: "error-handler",
         priority: 0,
@@ -42,7 +80,12 @@ export function errorMiddleware(onError) {
                 return await next();
             }
             catch (error) {
-                onError?.(error, ctx);
+                try {
+                    onError?.(error, ctx);
+                }
+                catch (reporterError) {
+                    onReporterError?.(reporterError);
+                }
                 throw error;
             }
         },
@@ -51,40 +94,148 @@ export function errorMiddleware(onError) {
 /**
  * Create a timeout middleware.
  *
- * Rejects if the pipeline takes too long.
+ * Rejects with a {@link MiddlewareTimeoutError} if the rest of the pipeline
+ * takes too long. The timer is always cleared, so a fast request leaves
+ * nothing pending on the event loop, and the losing promise stays handled so
+ * a late rejection cannot surface as an unhandled rejection.
+ *
+ * The downstream work is not cancelled — nothing in the middleware contract
+ * can cancel it. Use the pipeline's `signal` option, or carry an
+ * `AbortSignal` on your own context, when the work itself needs to stop.
  */
-export function timeoutMiddleware(timeoutMs) {
+export function timeoutMiddleware(timeoutMs, options) {
+    const name = options?.name ?? "timeout";
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new MiddlewareError(`Timeout must be a positive, finite number of milliseconds; received ${timeoutMs}`, { middlewareName: name });
+    }
     return {
-        name: "timeout",
-        handler: async (ctx, next) => {
-            return Promise.race([
-                next(),
-                new Promise((_, reject) => setTimeout(() => reject(new Error(`Middleware timeout after ${timeoutMs}ms`)), timeoutMs)),
-            ]);
+        // The configured name, not a constant: two timeouts in one pipeline were
+        // both reported as "timeout" in `executedMiddleware` and in error
+        // attribution, so `options.name` reached the error message and nothing
+        // else.
+        name,
+        handler: async (_ctx, next) => {
+            let timer;
+            const pending = next();
+            // Keep the loser of the race handled: if the timeout wins and the
+            // downstream work rejects later, that rejection must not escape.
+            void pending.catch(() => { });
+            try {
+                return await Promise.race([
+                    pending,
+                    new Promise((_resolve, reject) => {
+                        timer = setTimeout(() => {
+                            reject(new MiddlewareTimeoutError(name, timeoutMs));
+                        }, timeoutMs);
+                        if (typeof timer === "object" && "unref" in timer) {
+                            timer.unref();
+                        }
+                    }),
+                ]);
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            }
         },
     };
 }
 /**
  * Create a rate-limiting middleware.
  *
- * Uses a sliding window counter per key.
+ * Implements a true sliding window: each key keeps the timestamps of its
+ * requests within `windowMs`, so a client cannot burst `2 × maxRequests`
+ * across a window boundary the way a fixed-window counter allows.
+ *
+ * Rejections throw {@link MiddlewareRateLimitError}, which carries
+ * `retryAfterMs` for an HTTP adapter to turn into a 429 with `Retry-After`.
+ *
+ * State is per-instance and in-process. Behind more than one instance of a
+ * service, each process enforces its own limit; use a shared store for a
+ * cluster-wide one.
  */
-export function rateLimitMiddleware(maxRequests, windowMs) {
-    const counts = new Map();
+export function rateLimitMiddleware(maxRequests, windowMs, options) {
+    if (!Number.isInteger(maxRequests) || maxRequests <= 0) {
+        throw new MiddlewareError(`maxRequests must be a positive integer; received ${maxRequests}`, { middlewareName: "rate-limit" });
+    }
+    if (!Number.isFinite(windowMs) || windowMs <= 0) {
+        throw new MiddlewareError(`windowMs must be a positive, finite number; received ${windowMs}`, { middlewareName: "rate-limit" });
+    }
+    const maxKeys = options?.maxKeys ?? 10_000;
+    const sweepIntervalMs = options?.sweepIntervalMs ?? 60_000;
+    const rejectUnkeyed = options?.rejectUnkeyed ?? false;
+    /** key → request timestamps inside the current window, oldest first. */
+    const hits = new Map();
+    let lastSweep = Date.now();
+    function prune(timestamps, now) {
+        const cutoff = now - windowMs;
+        let firstLive = 0;
+        while (firstLive < timestamps.length && timestamps[firstLive] <= cutoff) {
+            firstLive++;
+        }
+        return timestamps.slice(firstLive);
+    }
+    function sweep(now) {
+        for (const [key, timestamps] of hits) {
+            const live = prune(timestamps, now);
+            if (live.length === 0)
+                hits.delete(key);
+            else
+                hits.set(key, live);
+        }
+        lastSweep = now;
+    }
+    function enforceKeyBudget(now) {
+        if (hits.size <= maxKeys)
+            return;
+        sweep(now);
+        // Map preserves insertion order and every touch re-inserts, so the head
+        // of the iteration order is the least recently seen key.
+        while (hits.size > maxKeys) {
+            const oldest = hits.keys().next();
+            if (oldest.done === true)
+                break;
+            hits.delete(oldest.value);
+        }
+    }
     return {
         name: "rate-limit",
+        inspect(key) {
+            const now = Date.now();
+            const live = prune(hits.get(key) ?? [], now);
+            if (live.length === 0)
+                return undefined;
+            return {
+                count: live.length,
+                retryAfterMs: Math.max(0, live[0] + windowMs - now),
+            };
+        },
+        size() {
+            return hits.size;
+        },
+        reset() {
+            hits.clear();
+        },
         handler: async (ctx, next) => {
-            const key = ctx.key ?? "global";
             const now = Date.now();
-            const entry = counts.get(key);
-            if (!entry || now > entry.resetAt) {
-                counts.set(key, { count: 1, resetAt: now + windowMs });
-                return next();
+            if (ctx.key === undefined && rejectUnkeyed) {
+                throw new MiddlewareError("Rate-limited request carried no key and unkeyed requests are rejected", { middlewareName: "rate-limit" });
             }
-            if (entry.count >= maxRequests) {
-                throw new Error(`Rate limit exceeded: ${maxRequests} requests per ${windowMs}ms`);
+            const key = ctx.key ?? "global";
+            if (now - lastSweep >= sweepIntervalMs)
+                sweep(now);
+            const live = prune(hits.get(key) ?? [], now);
+            if (live.length >= maxRequests) {
+                hits.set(key, live);
+                const retryAfterMs = Math.max(1, live[0] + windowMs - now);
+                throw new MiddlewareRateLimitError(maxRequests, windowMs, retryAfterMs);
             }
-            entry.count++;
+            live.push(now);
+            // Delete first so the re-insert moves the key to the end of the
+            // iteration order, which is what makes eviction least-recently-seen.
+            hits.delete(key);
+            hits.set(key, live);
+            enforceKeyBudget(now);
             return next();
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/middleware",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Composable middleware pipeline with composition, timing, error handling, and context propagation.",
   "license": "MIT",
   "type": "module",
@@ -15,23 +15,19 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "dependencies": {
-    "@zudojs/errors": "0.1.0"
+    "@zudojs/errors": "1.0.0"
   },
   "engines": {
     "node": ">=24.0.0"
   },
   "devDependencies": {
-    "typescript": "^7.0.2",
+    "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },
   "publishConfig": {
@@ -44,8 +40,19 @@
     "composition"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/middleware"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}