vibe-gx 4.1.2 → 4.2.0

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.2",
+  "version": "4.2.0",
   "description": "A lightweight, high-performance Node.js web framework.",
   "type": "module",
   "main": "vibe.js",

package/utils/core/logger.js

@@ -9,6 +9,7 @@ const LOG_LEVELS = {
   warn: 40,
   error: 50,
   fatal: 60,
+  silent: 100, // Higher than all levels — suppresses all output (logger: false)
 };
 
 const LEVEL_NAMES = {
@@ -136,45 +137,59 @@ export class Logger {
   _printPretty(log) {
     const time = new Date(log.time).toLocaleTimeString();
     const lvlName = LEVEL_NAMES[log.level] || "INFO";
-    let prefixC = color.cyan;
-    if (log.level >= 50) prefixC = color.red;
-    else if (log.level === 40) prefixC = color.yellow;
-    else if (log.level <= 20) prefixC = color.dim;
-
-    const prefix = prefixC(`[VIBE ${lvlName} ${time}]`);
-    let context = "";
-    if (log.reqId) {
-      context = `\x1b[90m[${log.reqId}]\x1b[0m `;
-    }
 
-    let content = log.msg || "";
-    if (log.color && color[log.color]) {
-      content = color[log.color](content);
-    }
+    const isError = log.level >= 50;
+    const isWarn  = log.level === 40;
+    const isDebug = log.level <= 20;
+
+    // Build context tag (reqId)
+    const context = log.reqId ? `[${log.reqId}] ` : "";
 
+    // Build message content
+    let content = log.msg || "";
     if (log.err && log.err.stack) {
-      content += "\n" + prefixC(log.err.stack);
+      content += "\n" + log.err.stack;
     }
 
-    // Attempt to print remaining metadata if it's not standard
+    // Build metadata string (skip standard keys)
     const skipKeys = [
-      "level",
-      "time",
-      "pid",
-      "hostname",
-      "reqId",
-      "msg",
-      "err",
-      "color",
+      "level", "time", "pid", "hostname", "reqId", "msg", "err", "color",
     ];
     let metaStr = "";
     for (const key of Object.keys(log)) {
       if (!skipKeys.includes(key)) {
-        metaStr += ` \x1b[90m${key}=${JSON.stringify(log[key])}\x1b[0m`;
+        metaStr += ` ${key}=${JSON.stringify(log[key])}`;
       }
     }
 
-    this.stream.write(`${prefix} ${context}${content}${metaStr}\n`);
+    const rawPrefix = `[VIBE ${lvlName} ${time}]`;
+
+    if (isError) {
+      // Entire line is red — prefix, context, message, stack, metadata
+      const fullLine = `${rawPrefix} ${context}${content}${metaStr}`;
+      this.stream.write(color.red(fullLine) + "\n");
+    } else if (isWarn) {
+      // Yellow prefix, bright content
+      const coloredContent = log.color && color[log.color]
+        ? color[log.color](content)
+        : color.bright(content);
+      this.stream.write(
+        color.yellow(rawPrefix) + " " + context + coloredContent +
+        (metaStr ? color.dim(metaStr) : "") + "\n",
+      );
+    } else if (isDebug) {
+      // Dim entire line for trace/debug
+      this.stream.write(color.dim(`${rawPrefix} ${context}${content}${metaStr}`) + "\n");
+    } else {
+      // Info — green prefix + bright content (matches [VIBE LOG] style)
+      const coloredContent = log.color && color[log.color]
+        ? color[log.color](content)
+        : color.bright(content);
+      this.stream.write(
+        color.green(rawPrefix) + " " + context + coloredContent +
+        (metaStr ? color.dim(metaStr) : "") + "\n",
+      );
+    }
   }
 }
 

package/utils/core/parser.js

@@ -103,7 +103,7 @@ function parseMultipart(req, res, media, options, resolve, reject) {
       },
     });
   } catch (err) {
-    console.error("Busboy init failed:", err);
+    options.logger?.error(err, "[VIBE] Busboy init failed");
     return resolve();
   }
 
@@ -152,7 +152,10 @@ function parseMultipart(req, res, media, options, resolve, reject) {
       media.public &&
       !dest.startsWith(path.resolve(options.publicFolder || ""))
     ) {
-      console.warn("Attempted upload outside public folder, skipping");
+      options.logger?.warn(
+        { dest, publicFolder: options.publicFolder },
+        "[VIBE] Attempted upload outside public folder, skipping",
+      );
       pendingWrites--;
       checkComplete();
       return file.resume();
@@ -161,7 +164,7 @@ function parseMultipart(req, res, media, options, resolve, reject) {
     try {
       if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
     } catch (err) {
-      console.error("Failed to create upload folder:", err);
+      options.logger?.error(err, "[VIBE] Failed to create upload folder");
       pendingWrites--;
       checkComplete();
       return file.resume();
@@ -200,14 +203,14 @@ function parseMultipart(req, res, media, options, resolve, reject) {
     });
 
     file.on("error", (err) => {
-      console.error("File stream error:", err);
+      options.logger?.error(err, "[VIBE] File stream error");
       writeStream.end();
       pendingWrites--;
       checkComplete();
     });
 
     writeStream.on("error", (err) => {
-      console.error("Write stream error:", err);
+      options.logger?.error(err, "[VIBE] Write stream error");
       file.resume();
       pendingWrites--;
       checkComplete();
@@ -231,7 +234,7 @@ function parseMultipart(req, res, media, options, resolve, reject) {
   });
 
   bb.on("error", (err) => {
-    console.error("Busboy error:", err);
+    options.logger?.error(err, "[VIBE] Busboy error");
     req.unpipe(bb);
     reject(err);
   });
@@ -266,7 +269,10 @@ function parseJson(req, res, media, options, resolve, reject) {
   req.on("data", (chunk) => {
     body += chunk;
     if (body.length > limit) {
-      console.warn("JSON payload too large, destroying connection");
+      options.logger?.warn(
+        { limit, received: body.length },
+        "[VIBE] JSON payload too large, destroying connection",
+      );
       req.destroy();
     }
   });

package/utils/core/response.js

@@ -243,7 +243,12 @@ const vibeResponseMethods = {
    * @param {Error} error
    */
   serverError(error) {
-    console.error(error);
+    const logger = this._vibeOptions?.logger;
+    if (logger) {
+      logger.error(error, "[VIBE] Internal server error");
+    } else {
+      console.error(error);
+    }
     this.writeHead(500, JSON_CT);
     this.end(RESPONSES.serverError);
   },

package/utils/core/server.js

@@ -90,15 +90,35 @@ 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();
 
       // Determine sender IP early for logging
       const sender =
-        req.socket.remoteAddress || req.headers["x-forwarded-for"] || "unknown";
+        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 },
@@ -129,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;
 
@@ -215,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;
@@ -296,8 +319,14 @@ async function server(options, port, host, callback) {
     getNetworkIP(mainHost, port);
 
     const strategy = useTrieMatching ? "Trie (O(log n))" : "Linear (O(n))";
-    console.log(
-      `[VIBE] Route matching: ${strategy} (${options.routeCount} routes, ${staticRoutes.size} static, threshold: ${options.trieThreshold})`,
+    options.logger.info(
+      {
+        strategy,
+        routeCount: options.routeCount,
+        staticRoutes: staticRoutes.size,
+        trieThreshold: options.trieThreshold,
+      },
+      "[VIBE] Route matching strategy initialized",
     );
 
     if (callback) callback();

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

@@ -219,8 +219,6 @@ export interface LoggerAPI {
 export interface VibeConfig {
   /** Configuration for the native Vibe terminal logger */
   logger?: LoggerConfig | boolean;
-  /** Enable automatic process restarting on crash. Spawns an internal cluster manager. Default: false */
-  autoRestart?: boolean;
 }
 
 // ==========================================
@@ -239,10 +237,8 @@ export interface VibeRequest extends IncomingMessage {
   body: Record<string, any>;
   /** Uploaded files array (if multipart/form-data) */
   files?: UploadedFile[];
-  /** Client IP address */
+  /** Real client IP — first entry from x-forwarded-for, x-real-ip, or socket address */
   ip?: string;
-  /** Detailed client IP info */
-  fullIp?: string;
   /** Automatically generated UUID for the request lifecycle */
   id: string;
   /** Context-bound logger automatically stamped with the req.id constraint */
@@ -304,9 +300,58 @@ export type Interceptor = (
   res: VibeResponse,
 ) => boolean | void | Promise<boolean | void>;
 
+/**
+ * Scoped app interface passed to register() plugin callbacks.
+ * A subset of VibeApp — excludes server-level methods that make no sense
+ * inside an encapsulated plugin (listen, logRoutes, setPublicFolder, include).
+ */
+export interface ScopedVibeApp {
+  get: RouteRegistrar;
+  post: RouteRegistrar;
+  put: RouteRegistrar;
+  del: RouteRegistrar;
+  patch: RouteRegistrar;
+  head: RouteRegistrar;
+
+  /** Register a global interceptor within this plugin scope */
+  plugin: (interceptor: Interceptor) => void;
+
+  /** Register a nested plugin */
+  register: (fn: PluginCallback, opts?: RegisterOptions) => Promise<void>;
+
+  /** Decorate the app with a custom property */
+  decorate: (name: string, value: any) => void;
+
+  /** Decorate request objects with a custom property */
+  decorateRequest: (name: string, value: any) => void;
+
+  /** Decorate response objects with a custom property */
+  decorateReply: (name: string, value: any) => void;
+
+  /** Override the error handler for this plugin scope */
+  setErrorHandler: (
+    fn: (error: Error, req: VibeRequest, res: VibeResponse) => void,
+  ) => void;
+
+  /** Structured logger — app.log.info(), .warn(), .error() etc. */
+  log: LoggerAPI;
+
+  /** Alias for log */
+  logger: LoggerAPI;
+
+  /** Legacy colorized string logger */
+  logLegacy: (
+    value: any,
+    typeOrColor?: ColorName | "info" | "error" | "warn" | "req",
+  ) => void;
+
+  /** Any decorators registered via decorate() are available as direct properties */
+  [key: string]: any;
+}
+
 /** Plugin callback function (Fastify-style) */
 export type PluginCallback = (
-  app: VibeApp,
+  app: ScopedVibeApp,
   opts: RegisterOptions,
 ) => void | Promise<void>;
 
@@ -393,11 +438,23 @@ export interface RouterAPI {
   head: RouteRegistrar;
 
   /**
-   * Log helper supporting native colors and Vibe-stylized log levels
-   * @param value The message or object to log
-   * @param typeOrColor Optional color name (e.g. 'green') or level ('info', 'warn', 'error', 'req')
+   * Pino/Fastify-compatible structured logger.
+   * Available inside both `app.register()` plugins and `app.include()` sub-routers.
+   * @example
+   * api.log.info("Route registered");
+   * api.log.warn({ userId: 1 }, "Slow query");
+   */
+  log: LoggerAPI;
+
+  /** Alias for `log` — consistent with `app.logger` */
+  logger: LoggerAPI;
+
+  /**
+   * Legacy colorized string logger (plain terminal output).
+   * @param value The message to log
+   * @param typeOrColor Optional color name (e.g. 'green', 'red')
    */
-  log: (
+  logLegacy: (
     value: any,
     typeOrColor?: ColorName | "info" | "error" | "warn" | "req",
   ) => void;
@@ -489,6 +546,17 @@ export interface VibeApp extends RouterAPI {
 
   /** Alias for `app.log` */
   logger: LoggerAPI;
+
+  /**
+   * Legacy colorized string logger (plain terminal output).
+   * Bypasses the Pino JSON interface — for simple dev-time messages.
+   * @param value The message to log
+   * @param typeOrColor Optional color name (e.g. 'green', 'red')
+   */
+  logLegacy: (
+    value: any,
+    typeOrColor?: ColorName | "info" | "error" | "warn" | "req",
+  ) => void;
 }
 
 /**
@@ -648,6 +716,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
 // ==========================================
@@ -669,11 +829,3 @@ export function adapt(
   mw: (req: any, res: any, next: (err?: any) => void) => void,
 ): Interceptor;
 
-/**
- * Adapt multiple Express middlewares at once.
- * @param middlewares - Express middleware functions
- * @returns Array of Vibe-compatible interceptors
- */
-export function adaptAll(
-  ...middlewares: Array<(req: any, res: any, next: (err?: any) => void) => void>
-): Interceptor[];

package/vibe.js

@@ -37,7 +37,6 @@ function pathToRegex(path) {
  *     size: number
  *   }>,
  *   ip?: string,
- *   fullIp?: string
  * }} VibeRequest
  */
 
@@ -134,9 +133,12 @@ function pathToRegex(path) {
  * Initializes a Vibe application instance.
  * @param {Object} [config={}]
  * @param {Object|boolean} [config.logger] - Logger configuration
- * @param {boolean} [config.autoRestart] - Restart server automatically on crash
  * @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();
@@ -145,7 +147,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();
@@ -175,21 +177,24 @@ const vibe = (config = {}) => {
     errorHandler: handleError,
   };
 
-  // Add global uncaught exception handler to prevent silent deaths and log cleanly
-  process.on("uncaughtException", (err) => {
-    appLogger.fatal(err, "Uncaught Exception crashed the server");
-    // Only exit here if we're not exiting gracefully anyway,
-    // cluster manager will restart it.
-    setTimeout(() => process.exit(1), 100);
-  });
+  // 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("unhandledRejection", (reason, promise) => {
-    appLogger.fatal(
-      { err: reason },
-      "Unhandled Promise Rejection crashed the server",
-    );
-    setTimeout(() => process.exit(1), 100);
-  });
+    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 = {
@@ -395,13 +400,7 @@ const vibe = (config = {}) => {
       host = undefined;
     }
 
-    const startServer = () => server(options, Number(port), host, callback);
-
-    if (config.autoRestart) {
-      clusterize(startServer, { workers: 1, restart: true });
-    } else {
-      startServer();
-    }
+    server(options, Number(port), host, callback);
   }
 
   /**
@@ -430,21 +429,34 @@ const vibe = (config = {}) => {
       decorateRequest,
       decorateReply,
       register,
-      log,
+      log: appLogger,        // Structured logger (api.log.info / warn / error etc.)
+      logger: appLogger,     // Alias — consistent with root app.logger
+      logLegacy: log,        // Legacy colorized string logger (api.logLegacy(msg, color))
+      setErrorHandler: (fn) => { options.errorHandler = fn; },
       // Expose decorators
       ...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;
+    }
   }
 
   /**
@@ -476,7 +488,9 @@ const vibe = (config = {}) => {
       del: wrap("DELETE"),
       patch: wrap("PATCH"),
       head: wrap("HEAD"),
-      log,
+      log: appLogger,    // Structured logger — consistent with app.log
+      logger: appLogger, // Alias
+      logLegacy: log,    // Legacy colorized string logger
       plugin,
     };
   }
@@ -630,3 +644,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";
+