vibe-gx 4.1.1 → 4.1.4

package/README.md

@@ -50,6 +50,8 @@ npm install vibe-gx
 | 🎨 **Decorators**             | Extend app, request, and response                          |
 | ⚡ **Cluster Mode**           | Built-in multi-process scaling                             |
 | 💾 **LRU Cache**              | Built-in response caching with ETag                        |
+| 🛡️ **Rate Limiting**          | Built-in sliding window rate limiter — no dependencies     |
+| 🌐 **CORS**                   | Built-in CORS with preflight handling — no dependencies    |
 | 🔗 **Connection Pool**        | Generic pool for databases                                 |
 | 📂 **File Uploads**           | Multipart uploads with size/type validation                |
 | 🌊 **Streaming**              | Large file uploads without buffering                       |
@@ -474,15 +476,61 @@ Use any Express middleware with the adapter:
 
 ```javascript
 import vibe, { adapt } from "vibe-gx";
-import cors from "cors";
 import helmet from "helmet";
 import compression from "compression";
 
-app.plugin(adapt(cors()));
 app.plugin(adapt(helmet()));
 app.plugin(adapt(compression()));
 ```
 
+> **Note:** Vibe ships with a native `cors()` helper. No need to adapt the `cors` npm package.
+
+---
+
+## 🛡️ Rate Limiting
+
+Built-in sliding window rate limiter — no external dependencies:
+
+```javascript
+import vibe, { rateLimit } from "vibe-gx";
+
+const app = vibe();
+
+// Global limit: 100 requests per minute per IP
+app.plugin(rateLimit({ max: 100, window: 60_000 }));
+
+// Per-route: tight limit on login (brute force protection)
+app.post(
+  "/auth/login",
+  { intercept: rateLimit({ max: 5, window: 60_000 }) },
+  handler,
+);
+```
+
+Sets `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and `Retry-After` headers automatically.
+
+---
+
+## 🌐 CORS
+
+Built-in CORS with automatic preflight handling — no external dependencies:
+
+```javascript
+import vibe, { cors } from "vibe-gx";
+
+const app = vibe();
+
+app.plugin(
+  cors({
+    origin: "https://myapp.com",
+    credentials: true,
+    maxAge: 86_400, // cache preflight for 24 hours
+  }),
+);
+```
+
+Supports wildcard, single origin, array of origins, and dynamic origin functions.
+
 ---
 
 ## 🔒 Security
@@ -602,18 +650,18 @@ app.post(
 
 ### Request (`req`)
 
-| Property      | Description                |
-| :------------ | :------------------------- |
-| `req.id`      | Auto-generated UUID logic  |
-| `req.log`     | Context-bound logger API   |
-| `req.params`  | Route parameters (`:id`)   |
-| `req.query`   | Query string (`?page=1`)   |
-| `req.body`    | Parsed JSON/form body      |
-| `req.files`   | Uploaded files (multipart) |
-| `req.ip`      | Client IP address          |
-| `req.method`  | HTTP method                |
-| `req.url`     | Request URL                |
-| `req.headers` | Request headers            |
+| Property      | Description                                              |
+| :------------ | :------------------------------------------------------- |
+| `req.id`      | Lazy UUID — generated only on first access               |
+| `req.log`     | Lazy context-bound logger — created only on first access |
+| `req.params`  | Route parameters (`:id`)                                 |
+| `req.query`   | Query string (`?page=1`)                                 |
+| `req.body`    | Parsed JSON/form body                                    |
+| `req.files`   | Uploaded files (multipart)                               |
+| `req.ip`      | Real client IP — proxy-aware (`x-forwarded-for` first)   |
+| `req.method`  | HTTP method                                              |
+| `req.url`     | Request URL (pathname only, query stripped)              |
+| `req.headers` | Request headers                                          |
 
 ### Response (`res`)
 
@@ -665,6 +713,18 @@ app.post(
 | `pool.close()`     | Close pool             |
 | `pool.stats`       | Get pool statistics    |
 
+### Rate Limit Utilities
+
+| Function          | Description                          |
+| :---------------- | :----------------------------------- |
+| `rateLimit(opts)` | Create a sliding window rate limiter |
+
+### CORS Utilities
+
+| Function      | Description               |
+| :------------ | :------------------------ |
+| `cors(opts?)` | Create a CORS interceptor |
+
 ---
 
 ## 📊 Benchmarks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-gx",
-  "version": "4.1.1",
+  "version": "4.1.4",
   "description": "A lightweight, high-performance Node.js web framework.",
   "type": "module",
   "main": "vibe.js",

package/utils/core/logger.js

@@ -1,4 +1,5 @@
 import os from "os";
+import fs from "fs";
 import { color } from "../helpers/colors.js";
 
 const LOG_LEVELS = {
@@ -25,11 +26,20 @@ const LEVEL_NAMES = {
 export class Logger {
   constructor(options = {}) {
     this.level = LOG_LEVELS[options.level || "info"] || 30;
-    this.prettyPrint = options.prettyPrint || false;
+    this.colors = options.colors !== undefined ? options.colors : true;
+    this.prettyPrint =
+      options.prettyPrint !== undefined ? options.prettyPrint : this.colors;
     this.lifecycle = options.lifecycle || false;
     this.stream = options.stream || process.stdout;
+    this.dest = options.dest || "console"; // "console", "file", "both"
+    this.logFile = options.logFile;
     this.bindings = options.bindings || {};
 
+    // Initialize file stream if needed
+    if (this.logFile && (this.dest === "file" || this.dest === "both")) {
+      this.fileStream = fs.createWriteStream(this.logFile, { flags: "a" });
+    }
+
     if (!this.bindings.pid) this.bindings.pid = process.pid;
     if (!this.bindings.hostname) this.bindings.hostname = os.hostname();
   }
@@ -42,9 +52,12 @@ export class Logger {
       level: Object.keys(LOG_LEVELS).find(
         (key) => LOG_LEVELS[key] === this.level,
       ),
+      colors: this.colors,
       prettyPrint: this.prettyPrint,
       lifecycle: this.lifecycle,
       stream: this.stream,
+      dest: this.dest,
+      logFile: this.logFile,
       bindings: { ...this.bindings, ...bindings },
     });
   }
@@ -107,10 +120,16 @@ export class Logger {
 
     const finalLog = { ...base, ...logData };
 
-    if (this.prettyPrint) {
-      this._printPretty(finalLog);
-    } else {
-      this.stream.write(JSON.stringify(finalLog) + "\n");
+    if (this.dest === "console" || this.dest === "both") {
+      if (this.prettyPrint) {
+        this._printPretty(finalLog);
+      } else {
+        this.stream.write(JSON.stringify(finalLog) + "\n");
+      }
+    }
+
+    if ((this.dest === "file" || this.dest === "both") && this.fileStream) {
+      this.fileStream.write(JSON.stringify(finalLog) + "\n");
     }
   }
 

package/utils/core/server.js

@@ -90,12 +90,40 @@ async function server(options, port, host, callback) {
 
   // Main request handler - ULTRA OPTIMIZED
   function reqListener(req, res) {
-    req.id = crypto.randomUUID();
-    req.log = options.logger.child({ reqId: req.id });
+    // Lazy req.id and req.log — UUID and child logger are only created
+    // on first access. Routes that don't log or need an ID pay zero cost.
+    let _reqId = null;
+    let _reqLog = null;
+    Object.defineProperty(req, "id", {
+      get() {
+        if (_reqId === null) _reqId = crypto.randomUUID();
+        return _reqId;
+      },
+      configurable: true,
+    });
+    Object.defineProperty(req, "log", {
+      get() {
+        if (_reqLog === null)
+          _reqLog = options.logger.child({ reqId: req.id });
+        return _reqLog;
+      },
+      configurable: true,
+    });
 
     if (options.loggerConfig && options.loggerConfig.lifecycle) {
       req.startTime = Date.now();
-      req.log.info({ type: "req" }, "Incoming request");
+
+      // Determine sender IP early for logging
+      const sender =
+        req.headers["x-forwarded-for"]?.split(",")[0]?.trim() ||
+        req.headers["x-real-ip"] ||
+        req.socket.remoteAddress ||
+        "unknown";
+
+      req.log.info(
+        { type: "req", url: req.url, method: req.method, sender },
+        "Incoming request",
+      );
 
       res.on("finish", () => {
         req.log.info(
@@ -121,6 +149,12 @@ async function server(options, port, host, callback) {
 
     req.url = pathname;
 
+    // Resolve real client IP once — proxy-aware, available on ALL paths
+    req.ip =
+      req.headers["x-forwarded-for"]?.split(",")[0]?.trim() ||
+      req.headers["x-real-ip"] ||
+      req.socket.remoteAddress;
+
     // Stamp response with options ref (ONLY per-request cost for response methods)
     res._vibeOptions = options;
 
@@ -207,10 +241,7 @@ async function server(options, port, host, callback) {
       if (!(await runIntercept(interceptors, req, res))) return;
     }
 
-    // Lazy IP
-    if (!req.ip) {
-      req.ip = req.socket.remoteAddress || req.headers["x-forwarded-for"];
-    }
+    // Lazy IP already resolved in reqListener — no-op needed here
 
     // Route matching - FAST PATH first
     const routeKey = req.method + pathname;

package/utils/helpers/cors.js

@@ -0,0 +1,124 @@
+/**
+ * Built-in CORS (Cross-Origin Resource Sharing) helper for Vibe.
+ *
+ * Returns an interceptor that handles preflight OPTIONS requests and sets
+ * the appropriate Access-Control-* headers on every response.
+ *
+ * @example
+ * import vibe, { cors } from "vibe-gx";
+ * const app = vibe();
+ *
+ * app.plugin(cors({ origin: "https://myapp.com", credentials: true }));
+ */
+
+// Pre-allocated headers for preflight responses
+const PREFLIGHT_HEADERS = { "content-length": "0" };
+
+/**
+ * @typedef {Object} CorsOptions
+ * @property {string | string[] | ((origin: string) => boolean)} [origin="*"]
+ *   Allowed origin(s). Can be a string, array of strings, or a function
+ *   that returns true/false for a given origin.
+ * @property {string[]} [methods] Allowed HTTP methods. Default: common methods
+ * @property {string[]} [allowedHeaders] Allowed request headers
+ * @property {string[]} [exposedHeaders] Headers exposed to the browser
+ * @property {boolean} [credentials=false] Allow cookies / auth headers
+ * @property {number} [maxAge] Preflight cache duration in seconds
+ */
+
+/**
+ * Creates a CORS interceptor.
+ *
+ * - Handles OPTIONS preflight requests automatically (responds 204 and stops).
+ * - Sets Access-Control-* headers on every request.
+ * - Supports wildcard, single origin, array of origins, or dynamic function.
+ *
+ * @param {CorsOptions} [opts={}]
+ * @returns {import("../vibe.js").Interceptor}
+ */
+export function cors(opts = {}) {
+  const {
+    origin = "*",
+    methods = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"],
+    allowedHeaders = ["Content-Type", "Authorization"],
+    exposedHeaders = [],
+    credentials = false,
+    maxAge,
+  } = opts;
+
+  // Pre-compute static header values where possible
+  const methodsStr = methods.join(", ");
+  const allowedHeadersStr = allowedHeaders.join(", ");
+  const exposedHeadersStr = exposedHeaders.length
+    ? exposedHeaders.join(", ")
+    : null;
+  const maxAgeStr = maxAge != null ? String(maxAge) : null;
+
+  /**
+   * Resolve the Access-Control-Allow-Origin value for a given request origin.
+   * @param {string} requestOrigin
+   * @returns {string | null} The value to set, or null to omit the header
+   */
+  function resolveOrigin(requestOrigin) {
+    if (origin === "*") return "*";
+
+    if (typeof origin === "function") {
+      return origin(requestOrigin) ? requestOrigin : null;
+    }
+
+    if (Array.isArray(origin)) {
+      return origin.includes(requestOrigin) ? requestOrigin : null;
+    }
+
+    // Single string
+    return origin === requestOrigin ? requestOrigin : null;
+  }
+
+  /**
+   * The interceptor returned to app.plugin().
+   * @param {import("../vibe.js").VibeRequest} req
+   * @param {import("../vibe.js").VibeResponse} res
+   * @returns {boolean}
+   */
+  return function corsInterceptor(req, res) {
+    const requestOrigin = req.headers["origin"];
+
+    // No Origin header — not a cross-origin request, skip CORS headers
+    if (!requestOrigin) return true;
+
+    const allowedOrigin = resolveOrigin(requestOrigin);
+
+    if (allowedOrigin) {
+      res.setHeader("Access-Control-Allow-Origin", allowedOrigin);
+
+      // If not wildcard, tell proxies/CDNs the response varies by Origin
+      if (allowedOrigin !== "*") {
+        res.setHeader("Vary", "Origin");
+      }
+    }
+
+    if (credentials) {
+      res.setHeader("Access-Control-Allow-Credentials", "true");
+    }
+
+    if (exposedHeadersStr) {
+      res.setHeader("Access-Control-Expose-Headers", exposedHeadersStr);
+    }
+
+    // Handle preflight (OPTIONS) — respond immediately and stop
+    if (req.method === "OPTIONS") {
+      res.setHeader("Access-Control-Allow-Methods", methodsStr);
+      res.setHeader("Access-Control-Allow-Headers", allowedHeadersStr);
+
+      if (maxAgeStr) {
+        res.setHeader("Access-Control-Max-Age", maxAgeStr);
+      }
+
+      res.writeHead(204, PREFLIGHT_HEADERS);
+      res.end();
+      return false; // Stop further processing
+    }
+
+    return true;
+  };
+}

package/utils/scaling/rate-limit.js

@@ -0,0 +1,113 @@
+/**
+ * Built-in sliding window rate limiter for Vibe.
+ *
+ * Works as both a global plugin and a per-route interceptor.
+ * Uses an in-memory Map with automatic TTL-based cleanup.
+ * No external dependencies.
+ *
+ * @example
+ * // Global — all routes
+ * import { rateLimit } from "vibe-gx";
+ * app.plugin(rateLimit({ max: 100, window: 60_000 }));
+ *
+ * @example
+ * // Per-route — tight limit on login
+ * app.post("/auth/login", { intercept: rateLimit({ max: 5, window: 60_000 }) }, handler);
+ */
+
+/**
+ * @typedef {Object} RateLimitOptions
+ * @property {number} max - Maximum number of requests allowed per window
+ * @property {number} [window=60000] - Window duration in milliseconds. Default: 60s
+ * @property {(req: import("../vibe.js").VibeRequest) => string} [keyBy] - Custom key function. Default: req.ip
+ * @property {string} [message] - Custom error message. Default: "Too Many Requests"
+ * @property {number} [statusCode=429] - HTTP status code when limit exceeded. Default: 429
+ * @property {(req: import("../vibe.js").VibeRequest) => boolean} [skip] - Return true to bypass the limiter for a request
+ */
+
+// Pre-allocated 429 response headers
+const RATE_LIMIT_HEADERS = { "content-type": "text/plain" };
+
+/**
+ * Creates a rate limiter interceptor using a sliding window algorithm.
+ *
+ * Each unique key (default: IP address) gets a counter and a window start time.
+ * When the window expires the counter resets. When the counter exceeds `max`
+ * the request is rejected with 429 and a `Retry-After` header.
+ *
+ * @param {RateLimitOptions} opts
+ * @returns {import("../vibe.js").Interceptor}
+ */
+export function rateLimit(opts = {}) {
+  const max = opts.max;
+
+  if (!max || typeof max !== "number" || max < 1) {
+    throw new Error("[vibe] rateLimit: `max` must be a positive number");
+  }
+
+  const windowMs = opts.window ?? 60_000;
+  const message = opts.message ?? "Too Many Requests";
+  const statusCode = opts.statusCode ?? 429;
+  const keyBy = opts.keyBy ?? ((req) => req.ip ?? "unknown");
+  const skip = opts.skip ?? null;
+
+  // In-memory store: key → { count, windowStart }
+  // Entries are cleaned up automatically when the window expires
+  const store = new Map();
+
+  // Periodic cleanup to prevent unbounded memory growth.
+  // Runs every `windowMs` and removes all expired entries.
+  const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of store) {
+      if (now - entry.windowStart >= windowMs) {
+        store.delete(key);
+      }
+    }
+  }, windowMs);
+
+  // Don't keep the process alive just for cleanup
+  if (cleanupInterval.unref) cleanupInterval.unref();
+
+  /**
+   * The interceptor function returned to app.plugin() or route intercept.
+   * @param {import("../vibe.js").VibeRequest} req
+   * @param {import("../vibe.js").VibeResponse} res
+   * @returns {boolean}
+   */
+  return function rateLimitInterceptor(req, res) {
+    // Allow bypassing for certain requests (e.g. internal health checks)
+    if (skip && skip(req)) return true;
+
+    const key = keyBy(req);
+    const now = Date.now();
+
+    let entry = store.get(key);
+
+    // No entry yet or window has expired — start a fresh window
+    if (!entry || now - entry.windowStart >= windowMs) {
+      entry = { count: 1, windowStart: now };
+      store.set(key, entry);
+    } else {
+      entry.count++;
+    }
+
+    const remaining = Math.max(0, max - entry.count);
+    const resetInMs = windowMs - (now - entry.windowStart);
+    const resetInSeconds = Math.ceil(resetInMs / 1000);
+
+    // Always set informational headers
+    res.setHeader("X-RateLimit-Limit", max);
+    res.setHeader("X-RateLimit-Remaining", remaining);
+    res.setHeader("X-RateLimit-Reset", Math.ceil((entry.windowStart + windowMs) / 1000));
+
+    if (entry.count > max) {
+      res.setHeader("Retry-After", resetInSeconds);
+      res.writeHead(statusCode, RATE_LIMIT_HEADERS);
+      res.end(message);
+      return false; // Stop request processing
+    }
+
+    return true;
+  };
+}

package/vibe.d.ts

@@ -181,6 +181,12 @@ export interface LoggerConfig {
   lifecycle?: boolean;
   /** If true, formats JSON output into human-readable Vibe-styled terminal lines (like pino-pretty) */
   prettyPrint?: boolean;
+  /** If true, applies ANSI color formatting to terminal logs. Default: true (unless overridden) */
+  colors?: boolean;
+  /** Destination for the logs. Accepts "console", "file", or "both". Default: "console" */
+  dest?: "console" | "file" | "both";
+  /** Absolute or relative path to the target log file. Active when dest is "file" or "both" */
+  logFile?: string;
   /** Custom writable stream to output logs to (defaults to process.stdout) */
   stream?: NodeJS.WritableStream;
 }
@@ -640,6 +646,98 @@ export function parseJsonStream(
   onError?: (err: Error) => void,
 ): void;
 
+// ==========================================
+// Rate Limiting
+// ==========================================
+
+export interface RateLimitOptions {
+  /** Maximum number of requests allowed per window */
+  max: number;
+  /** Window duration in milliseconds. Default: 60000 (1 minute) */
+  window?: number;
+  /**
+   * Custom function to derive the rate limit key from the request.
+   * Defaults to req.ip.
+   * @example keyBy: (req) => req.headers["authorization"] // limit per token
+   */
+  keyBy?: (req: VibeRequest) => string;
+  /** Custom message sent when limit is exceeded. Default: "Too Many Requests" */
+  message?: string;
+  /** HTTP status code when limit is exceeded. Default: 429 */
+  statusCode?: number;
+  /**
+   * Function to skip rate limiting for certain requests.
+   * Return true to bypass the limiter.
+   * @example skip: (req) => req.ip === "127.0.0.1"
+   */
+  skip?: (req: VibeRequest) => boolean;
+}
+
+/**
+ * Creates a sliding window rate limiter interceptor.
+ *
+ * Works as a global plugin or a per-route interceptor.
+ * Sets X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers.
+ * Returns 429 with a Retry-After header when the limit is exceeded.
+ *
+ * @example
+ * // Global rate limit
+ * import { rateLimit } from "vibe-gx";
+ * app.plugin(rateLimit({ max: 100, window: 60_000 }));
+ *
+ * @example
+ * // Per-route (tight limit on login)
+ * app.post("/auth/login", { intercept: rateLimit({ max: 5, window: 60_000 }) }, handler);
+ */
+export function rateLimit(options: RateLimitOptions): Interceptor;
+
+// ==========================================
+// CORS
+// ==========================================
+
+export interface CorsOptions {
+  /**
+   * Allowed origin(s). Can be:
+   * - `"*"` to allow all origins
+   * - A single origin string e.g. `"https://myapp.com"`
+   * - An array of allowed origins
+   * - A function `(origin: string) => boolean` for dynamic allow/deny
+   * Default: `"*"`
+   */
+  origin?: string | string[] | ((origin: string) => boolean);
+  /** Allowed HTTP methods. Default: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS */
+  methods?: string[];
+  /** Headers the browser is allowed to send. Default: Content-Type, Authorization */
+  allowedHeaders?: string[];
+  /** Headers exposed to the browser in the response */
+  exposedHeaders?: string[];
+  /** Allow cookies and Authorization headers. Default: false */
+  credentials?: boolean;
+  /** Seconds to cache the preflight response. Reduces OPTIONS calls from the browser */
+  maxAge?: number;
+}
+
+/**
+ * Creates a CORS interceptor.
+ *
+ * Handles OPTIONS preflight requests automatically and sets
+ * Access-Control-* headers on every cross-origin response.
+ *
+ * @example
+ * import { cors } from "vibe-gx";
+ *
+ * // Allow all origins
+ * app.plugin(cors());
+ *
+ * // Specific origin with credentials
+ * app.plugin(cors({ origin: "https://myapp.com", credentials: true }));
+ *
+ * // Multiple origins
+ * app.plugin(cors({ origin: ["https://myapp.com", "https://admin.myapp.com"] }));
+ */
+export function cors(options?: CorsOptions): Interceptor;
+
+
 // ==========================================
 // Express Middleware Adapter
 // ==========================================

package/vibe.js

@@ -6,6 +6,7 @@ import { PathToRegex } from "./utils/core/handler.js";
 import { compileSerializer } from "./utils/core/compile-serializer.js";
 import { createLogger, Logger } from "./utils/core/logger.js";
 import { handleError } from "./utils/core/handler.js";
+import { clusterize } from "./utils/scaling/cluster.js";
 
 /**
  * Helper to generate regex for a path
@@ -135,6 +136,10 @@ function pathToRegex(path) {
  * @param {Object|boolean} [config.logger] - Logger configuration
  * @returns {VibeApp}
  */
+// Guard to ensure process-level listeners are only registered once
+// across multiple vibe() instances (e.g. in test environments)
+let _processListenersInstalled = false;
+
 const vibe = (config = {}) => {
   // Route trie for O(log n) matching (used when routes > threshold)
   const trie = new RouteTrie();
@@ -143,7 +148,7 @@ const vibe = (config = {}) => {
   const routes = [];
 
   // Threshold for switching between linear and trie matching
-  const TRIE_THRESHOLD = 50;
+  const TRIE_THRESHOLD = 40;
 
   // Static routes Map for O(1) lookup (routes without params)
   const staticRoutes = new Map();
@@ -173,6 +178,25 @@ const vibe = (config = {}) => {
     errorHandler: handleError,
   };
 
+  // Register global process listeners once only (prevents listener leak
+  // when vibe() is called multiple times e.g. in tests)
+  if (!_processListenersInstalled) {
+    _processListenersInstalled = true;
+
+    process.on("uncaughtException", (err) => {
+      appLogger.fatal(err, "Uncaught Exception crashed the server");
+      setTimeout(() => process.exit(1), 100);
+    });
+
+    process.on("unhandledRejection", (reason) => {
+      appLogger.fatal(
+        { err: reason },
+        "Unhandled Promise Rejection crashed the server",
+      );
+      setTimeout(() => process.exit(1), 100);
+    });
+  }
+
   // Register default landing route
   const defaultRoute = {
     method: "GET",
@@ -411,16 +435,26 @@ const vibe = (config = {}) => {
       ...options.decorators,
     };
 
-    // Execute plugin
+    // Execute plugin — invoke fn() synchronously first so all route
+    // registrations that happen synchronously inside the plugin use the
+    // correct prefix.  Restore currentPrefix IMMEDIATELY after the call
+    // (before any await) so that concurrent un-awaited register() calls
+    // from the caller cannot inherit this plugin's prefix.
+    let result;
     try {
-      const result = fn(scopedApp, opts);
-      if (result && result.then) {
-        await result;
-      }
+      result = fn(scopedApp, opts);
     } finally {
-      // Restore prefix
+      // Restore prefix synchronously — this is the critical fix.
+      // If fn() is async its routes should already be registered
+      // synchronously at the top of the function; the await below is
+      // only needed to propagate rejections.
       currentPrefix = previousPrefix;
     }
+
+    // Await async plugins for error propagation only (prefix already restored)
+    if (result && typeof result.then === "function") {
+      await result;
+    }
   }
 
   /**
@@ -606,3 +640,6 @@ export {
 export { LRUCache, cacheMiddleware } from "./utils/scaling/cache.js";
 export { Pool, createPool } from "./utils/scaling/pool.js";
 export { parseJsonStream } from "./utils/core/parser.js";
+export { rateLimit } from "./utils/scaling/rate-limit.js";
+export { cors } from "./utils/helpers/cors.js";
+