kaelum 1.5.0 → 1.7.0

package/core/rateLimit.js

@@ -0,0 +1,153 @@
+// core/rateLimit.js
+// Kaelum built-in rate limiting middleware.
+// Zero-dependency, in-memory sliding-window rate limiter.
+
+/**
+ * In-memory store for tracking request counts per key.
+ * Automatically cleans up expired entries on an interval.
+ */
+class MemoryStore {
+  /**
+   * @param {number} windowMs - window duration in milliseconds
+   */
+  constructor(windowMs) {
+    this.windowMs = windowMs;
+    /** @type {Map<string, { hits: number, resetTime: number }>} */
+    this.hits = new Map();
+    // clean up expired entries every 60s (or every window if shorter)
+    this._cleanupInterval = setInterval(
+      () => this._cleanup(),
+      Math.min(windowMs, 60000)
+    );
+    // don't block process exit
+    if (this._cleanupInterval.unref) {
+      this._cleanupInterval.unref();
+    }
+  }
+
+  /**
+   * Increment the hit counter for a key.
+   * @param {string} key
+   * @returns {{ totalHits: number, resetTime: number }}
+   */
+  increment(key) {
+    const now = Date.now();
+    const entry = this.hits.get(key);
+
+    if (entry && now < entry.resetTime) {
+      entry.hits += 1;
+      return { totalHits: entry.hits, resetTime: entry.resetTime };
+    }
+
+    // new window
+    const resetTime = now + this.windowMs;
+    const record = { hits: 1, resetTime };
+    this.hits.set(key, record);
+    return { totalHits: 1, resetTime };
+  }
+
+  /**
+   * Reset the counter for a specific key.
+   * @param {string} key
+   */
+  resetKey(key) {
+    this.hits.delete(key);
+  }
+
+  /**
+   * Remove expired entries from the store.
+   */
+  _cleanup() {
+    const now = Date.now();
+    for (const [key, entry] of this.hits) {
+      if (now >= entry.resetTime) {
+        this.hits.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Shut down the store and clear the cleanup interval.
+   */
+  shutdown() {
+    clearInterval(this._cleanupInterval);
+    this.hits.clear();
+  }
+}
+
+/**
+ * Create a rate-limiting middleware function.
+ *
+ * @param {Object} [options]
+ * @param {number}   [options.windowMs=900000]   - window duration in ms (default 15 min)
+ * @param {number}   [options.max=100]           - max requests per window per key
+ * @param {string|Object} [options.message]      - response body when limited
+ * @param {number}   [options.statusCode=429]    - HTTP status when limited
+ * @param {Function} [options.keyGenerator]      - (req) => string  (default: req.ip)
+ * @param {Function} [options.skip]              - (req) => boolean (default: false)
+ * @param {boolean}  [options.headers=true]      - send standard rate-limit headers
+ * @param {Object}   [options.store]             - custom store (must implement increment/resetKey/shutdown)
+ * @returns {Function} Express middleware
+ */
+function createRateLimiter(options = {}) {
+  const {
+    windowMs = 15 * 60 * 1000,
+    max = 100,
+    message = { error: "Too many requests, please try again later." },
+    statusCode = 429,
+    keyGenerator = (req) => req.ip || req.connection.remoteAddress || "unknown",
+    skip = () => false,
+    headers = true,
+    store: customStore,
+  } = options;
+
+  const store = customStore || new MemoryStore(windowMs);
+
+  /**
+   * Express middleware function.
+   */
+  function rateLimitMiddleware(req, res, next) {
+    // allow skipping for certain requests
+    if (skip(req)) {
+      return next();
+    }
+
+    const key = keyGenerator(req);
+    const { totalHits, resetTime } = store.increment(key);
+    const remaining = Math.max(0, max - totalHits);
+
+    // attach rate-limit info to request for downstream use
+    req.rateLimit = { limit: max, remaining, resetTime };
+
+    // set standard headers
+    if (headers) {
+      res.setHeader("RateLimit-Limit", String(max));
+      res.setHeader("RateLimit-Remaining", String(remaining));
+      res.setHeader(
+        "RateLimit-Reset",
+        String(Math.ceil(resetTime / 1000))
+      );
+    }
+
+    // exceeded limit
+    if (totalHits > max) {
+      if (headers) {
+        const retryAfter = Math.ceil((resetTime - Date.now()) / 1000);
+        res.setHeader("Retry-After", String(Math.max(retryAfter, 0)));
+      }
+
+      const body =
+        typeof message === "string" ? { error: message } : message;
+      return res.status(statusCode).json(body);
+    }
+
+    next();
+  }
+
+  // attach store reference so setConfig can call shutdown on removal
+  rateLimitMiddleware._store = store;
+
+  return rateLimitMiddleware;
+}
+
+module.exports = { createRateLimiter, MemoryStore };

package/core/setConfig.js

@@ -90,6 +90,23 @@ function removeKaelumHelmet(app) {
   }
 }
 
+/**
+ * Remove Kaelum-installed rate-limiting middleware (if any)
+ * Also shuts down the MemoryStore cleanup interval.
+ * @param {Object} app
+ */
+function removeKaelumRateLimit(app) {
+  const prev = app.locals && app.locals._kaelum_ratelimit;
+  if (prev) {
+    // shut down the store's cleanup interval if present
+    if (prev._store && typeof prev._store.shutdown === "function") {
+      prev._store.shutdown();
+    }
+    removeMiddlewareByFn(app, prev);
+    app.locals._kaelum_ratelimit = null;
+  }
+}
+
 /**
  * Apply configuration options to the app
  * @param {Object} app - express app instance
@@ -257,6 +274,47 @@ function setConfig(app, options = {}) {
     }
   }
 
+  // --- Rate Limiting ---
+  if (options.hasOwnProperty("rateLimit")) {
+    if (options.rateLimit) {
+      const { createRateLimiter } = require("./rateLimit");
+      const rateLimitOpts =
+        options.rateLimit === true ? {} : options.rateLimit;
+
+      // remove previous Kaelum-installed rate limiter if exists
+      removeKaelumRateLimit(app);
+
+      const rateLimitFn = createRateLimiter(rateLimitOpts);
+      app.locals._kaelum_ratelimit = rateLimitFn;
+      app.use(rateLimitFn);
+      console.log("⏱️  Rate limiting activated.");
+    } else {
+      // disable Kaelum-installed rate limiter if present
+      removeKaelumRateLimit(app);
+      console.log("⏱️  Rate limiting disabled (Kaelum-managed).");
+    }
+  }
+
+  // --- Graceful Shutdown ---
+  if (options.hasOwnProperty("gracefulShutdown")) {
+    const server = app.locals && app.locals._kaelum_server;
+    if (server && server.listening) {
+      const {
+        enableGracefulShutdown,
+        removeSignalHandlers,
+      } = require("./shutdown");
+      if (options.gracefulShutdown === false) {
+        removeSignalHandlers(app);
+      } else {
+        const shutdownOpts =
+          typeof options.gracefulShutdown === "object"
+            ? options.gracefulShutdown
+            : {};
+        enableGracefulShutdown(app, shutdownOpts);
+      }
+    }
+  }
+
   // Return the full merged config for convenience
   return app.locals.kaelumConfig;
 }

package/core/shutdown.js

@@ -0,0 +1,167 @@
+// core/shutdown.js
+// Kaelum graceful shutdown module.
+// Handles process signal interception, connection draining, and cleanup hook execution.
+
+const DEFAULT_TIMEOUT = 10000;
+const DEFAULT_SIGNALS = ["SIGTERM", "SIGINT"];
+
+/**
+ * Register a cleanup function to run during shutdown.
+ */
+function onShutdown(app, fn) {
+  if (!app) throw new Error("onShutdown requires an app instance");
+  if (typeof fn !== "function") {
+    throw new Error("onShutdown: expected a function, got " + typeof fn);
+  }
+
+  if (!Array.isArray(app.locals._kaelum_shutdown_hooks)) {
+    app.locals._kaelum_shutdown_hooks = [];
+  }
+
+  app.locals._kaelum_shutdown_hooks.push(fn);
+  return app;
+}
+
+/**
+ * Run all registered cleanup hooks in order.
+ * Errors in individual hooks are caught and logged but do not abort the sequence.
+ */
+async function runCleanupHooks(app) {
+  const hooks = (app.locals && app.locals._kaelum_shutdown_hooks) || [];
+  for (const fn of hooks) {
+    try {
+      await Promise.resolve(fn());
+    } catch (err) {
+      console.error(
+        "Kaelum shutdown: cleanup hook error:",
+        err && err.message ? err.message : err
+      );
+    }
+  }
+}
+
+/**
+ * Gracefully close the server and run cleanup hooks.
+ *
+ * If callback is provided: calls cb(err) and returns app.
+ * If no callback: returns a Promise<void>.
+ */
+function close(app, cb) {
+  if (!app) throw new Error("close requires an app instance");
+
+  // Prevent double-shutdown
+  if (app.locals._kaelum_shutdown_in_progress) {
+    if (typeof cb === "function") {
+      process.nextTick(() => cb());
+      return app;
+    }
+    return Promise.resolve();
+  }
+
+  app.locals._kaelum_shutdown_in_progress = true;
+
+  const timeout = app.locals._kaelum_shutdown_timeout || DEFAULT_TIMEOUT;
+  const server = app.locals._kaelum_server;
+
+  // Remove signal handlers to prevent re-entry
+  removeSignalHandlers(app);
+
+  const doShutdown = async () => {
+    try {
+      // Phase 1: close the HTTP server (drain existing connections)
+      if (server && typeof server.close === "function") {
+        await new Promise((resolve) => {
+          const timer = setTimeout(() => {
+            console.error(
+              "Kaelum shutdown: server close timed out after " + timeout + "ms"
+            );
+            resolve();
+          }, timeout);
+          if (timer.unref) timer.unref();
+
+          server.close((err) => {
+            clearTimeout(timer);
+            if (err) {
+              console.error(
+                "Kaelum shutdown: server close error:",
+                err.message || err
+              );
+            }
+            resolve();
+          });
+        });
+      }
+
+      // Phase 2: run cleanup hooks (always runs, even after timeout)
+      await runCleanupHooks(app);
+    } finally {
+      app.locals._kaelum_shutdown_in_progress = false;
+    }
+  };
+
+  if (typeof cb === "function") {
+    doShutdown()
+      .then(() => cb(null))
+      .catch((err) => cb(err));
+    return app;
+  }
+
+  return doShutdown();
+}
+
+/**
+ * Register process signal handlers for automatic graceful shutdown.
+ * Called internally from start.js after server creation.
+ */
+function enableGracefulShutdown(app, options) {
+  if (!app) return;
+
+  const cfg = typeof options === "object" && options !== null ? options : {};
+  const timeout = cfg.timeout || DEFAULT_TIMEOUT;
+  const signals = Array.isArray(cfg.signals) ? cfg.signals : DEFAULT_SIGNALS;
+
+  app.locals._kaelum_shutdown_timeout = timeout;
+
+  // Remove existing handlers before registering new ones
+  removeSignalHandlers(app);
+
+  const handlers = {};
+
+  for (const signal of signals) {
+    const handler = () => {
+      console.log(
+        "\nKaelum: received " + signal + ", starting graceful shutdown..."
+      );
+      close(app)
+        .then(() => process.exit(0))
+        .catch((err) => {
+          console.error("Kaelum shutdown error:", err.message || err);
+          process.exit(1);
+        });
+    };
+    handlers[signal] = handler;
+    process.on(signal, handler);
+  }
+
+  app.locals._kaelum_shutdown_handlers = handlers;
+}
+
+/**
+ * Remove signal handlers previously installed by enableGracefulShutdown.
+ */
+function removeSignalHandlers(app) {
+  const handlers = app.locals && app.locals._kaelum_shutdown_handlers;
+  if (handlers && typeof handlers === "object") {
+    for (const signal of Object.keys(handlers)) {
+      process.removeListener(signal, handlers[signal]);
+    }
+    app.locals._kaelum_shutdown_handlers = null;
+  }
+}
+
+module.exports = {
+  onShutdown,
+  close,
+  enableGracefulShutdown,
+  removeSignalHandlers,
+};

package/core/start.js

@@ -5,6 +5,9 @@
 // - If a server is already running, returns the existing server (no double-listen)
 // - Stores the server instance in app.locals._kaelum_server
 // - Attaches basic error logging for startup errors
+// - Enables graceful shutdown by default (unless config disables it)
+
+const { enableGracefulShutdown } = require("./shutdown");
 
 /**
  * Normalize and validate a port-like value.
@@ -109,6 +112,16 @@ function start(app, port, cb) {
   // persist reference so we can check or close later
   app.locals._kaelum_server = server;
 
+  // enable graceful shutdown by default unless explicitly disabled
+  const shutdownCfg = cfg.gracefulShutdown;
+  if (shutdownCfg !== false) {
+    const shutdownOpts =
+      typeof shutdownCfg === "object" && shutdownCfg !== null
+        ? shutdownCfg
+        : {};
+    enableGracefulShutdown(app, shutdownOpts);
+  }
+
   return server;
 }
 

package/createApp.js

@@ -20,6 +20,7 @@ const registerHealth = require("./core/healthCheck");
 const redirect = require("./core/redirect");
 const { removeMiddlewareByFn } = require("./core/utils");
 const { registerPlugin, getPlugins } = require("./core/plugin");
+const { onShutdown, close } = require("./core/shutdown");
 
 function createApp() {
   const app = express();
@@ -31,6 +32,8 @@ function createApp() {
   app.locals = app.locals || {};
   app.locals.kaelumConfig = app.locals.kaelumConfig || {};
   app.locals._kaelum_plugins = [];
+  app.locals._kaelum_shutdown_hooks = [];
+  app.locals._kaelum_shutdown_in_progress = false;
   // persist baseline config so app.get("kaelum:config") is always available
   app.set("kaelum:config", app.locals.kaelumConfig);
 
@@ -182,6 +185,17 @@ function createApp() {
     return getPlugins(app);
   };
 
+  // ---------------------------
+  // Graceful shutdown
+  // ---------------------------
+  app.onShutdown = function (fn) {
+    return onShutdown(app, fn);
+  };
+
+  app.close = function (cb) {
+    return close(app, cb);
+  };
+
   return app;
 }
 

package/index.d.ts

@@ -10,6 +10,8 @@ interface KaelumConfig {
   port?: number;
   views?: { engine?: string; path?: string };
   logger?: boolean | false;
+  gracefulShutdown?: boolean | GracefulShutdownConfig;
+  rateLimit?: boolean | RateLimitConfig;
 }
 
 interface HealthOptions {
@@ -32,6 +34,36 @@ interface ErrorHandlerOptions {
   onError?: (err: Error, req: any, res: any) => void;
 }
 
+interface GracefulShutdownConfig {
+  /** Timeout in milliseconds before forcing shutdown (default: 10000) */
+  timeout?: number;
+  /** Process signals to handle (default: ["SIGTERM", "SIGINT"]) */
+  signals?: string[];
+}
+
+interface RateLimitConfig {
+  /** Window duration in ms (default: 900000 = 15 min) */
+  windowMs?: number;
+  /** Max requests per window per key (default: 100) */
+  max?: number;
+  /** Response body when rate limited */
+  message?: string | object;
+  /** HTTP status when rate limited (default: 429) */
+  statusCode?: number;
+  /** Custom key generator (default: req.ip) */
+  keyGenerator?: (req: any) => string;
+  /** Skip rate limiting for certain requests */
+  skip?: (req: any) => boolean;
+  /** Send standard rate-limit headers (default: true) */
+  headers?: boolean;
+  /** Custom store (must implement increment, resetKey, shutdown) */
+  store?: {
+    increment(key: string): { totalHits: number; resetTime: number };
+    resetKey(key: string): void;
+    shutdown(): void;
+  };
+}
+
 interface RedirectEntry {
   path: string;
   to: string;
@@ -102,6 +134,13 @@ interface KaelumApp extends Express {
 
   /** List registered plugin names */
   getPlugins(): string[];
+
+  /** Gracefully close the server and run cleanup hooks */
+  close(): Promise<void>;
+  close(cb: (err?: Error | null) => void): KaelumApp;
+
+  /** Register a cleanup function to run during graceful shutdown */
+  onShutdown(fn: () => void | Promise<void>): KaelumApp;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaelum",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "A minimalist Node.js framework for building web pages and APIs with simplicity and speed.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -38,7 +38,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/kaelumjs/kaelum.git"
+    "url": "git+https://github.com/kaelumjs/kaelum.git"
   },
   "bugs": {
     "url": "https://github.com/kaelumjs/kaelum/issues"