kaelum 1.4.8 → 1.6.0

package/core/plugin.js

@@ -0,0 +1,82 @@
+// core/plugin.js
+// Kaelum plugin registration system.
+// Plugins are functions that receive (app, options) and can add routes,
+// middleware, and config to the Kaelum app instance.
+
+/**
+ * Resolve the display name and dedup key for a plugin function.
+ * Checks fn.pluginName first, then fn.name, falls back to null (anonymous).
+ * @param {Function} fn
+ * @returns {string|null}
+ */
+function resolvePluginName(fn) {
+  if (typeof fn.pluginName === "string" && fn.pluginName) {
+    return fn.pluginName;
+  }
+  if (typeof fn.name === "string" && fn.name) {
+    return fn.name;
+  }
+  return null;
+}
+
+/**
+ * Register a plugin on the Kaelum app.
+ *
+ * @param {Object} app - Kaelum/Express app instance
+ * @param {Function} fn - Plugin function with signature (app, options) => void
+ * @param {Object} [options={}] - Options passed to the plugin
+ * @returns {Object} app - for chaining
+ * @throws {Error} if fn is not a function
+ * @throws {Error} if a named plugin with the same name is already registered
+ */
+function registerPlugin(app, fn, options = {}) {
+  if (typeof fn !== "function") {
+    throw new Error(
+      `Kaelum plugin: expected a function, got ${typeof fn}`
+    );
+  }
+
+  // ensure registry exists
+  if (!app.locals) app.locals = {};
+  if (!Array.isArray(app.locals._kaelum_plugins)) {
+    app.locals._kaelum_plugins = [];
+  }
+
+  const name = resolvePluginName(fn);
+
+  // duplicate guard for named plugins
+  if (name) {
+    const already = app.locals._kaelum_plugins.find((p) => p.name === name);
+    if (already) {
+      throw new Error(
+        `Kaelum plugin: "${name}" is already registered. ` +
+          `Each named plugin can only be registered once.`
+      );
+    }
+  }
+
+  // execute the plugin
+  fn(app, options);
+
+  // record in registry
+  app.locals._kaelum_plugins.push({
+    name: name || `anonymous_${app.locals._kaelum_plugins.length}`,
+    options,
+  });
+
+  return app;
+}
+
+/**
+ * Return the list of registered plugin names.
+ * @param {Object} app
+ * @returns {string[]}
+ */
+function getPlugins(app) {
+  if (!app.locals || !Array.isArray(app.locals._kaelum_plugins)) {
+    return [];
+  }
+  return app.locals._kaelum_plugins.map((p) => p.name);
+}
+
+module.exports = { registerPlugin, getPlugins };

package/core/setConfig.js

@@ -257,6 +257,26 @@ function setConfig(app, options = {}) {
     }
   }
 
+  // --- 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

@@ -19,6 +19,8 @@ const { errorHandler } = require("./core/errorHandler");
 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();
@@ -29,6 +31,9 @@ function createApp() {
   // ensure locals object and initial persisted config
   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);
 
@@ -169,6 +174,28 @@ function createApp() {
   // alias for convenience
   app.errorHandler = app.useErrorHandler;
 
+  // ---------------------------
+  // Plugin system
+  // ---------------------------
+  app.plugin = function (fn, options) {
+    return registerPlugin(app, fn, options);
+  };
+
+  app.getPlugins = function () {
+    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,7 @@ interface KaelumConfig {
   port?: number;
   views?: { engine?: string; path?: string };
   logger?: boolean | false;
+  gracefulShutdown?: boolean | GracefulShutdownConfig;
 }
 
 interface HealthOptions {
@@ -32,6 +33,13 @@ 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 RedirectEntry {
   path: string;
   to: string;
@@ -53,6 +61,9 @@ interface RouteHandlers {
   [subpath: string]: any;
 }
 
+/** Plugin function signature */
+type KaelumPlugin = (app: KaelumApp, options?: Record<string, any>) => void;
+
 interface KaelumApp extends Express {
   /** Configure Kaelum features (cors, helmet, static, logs, etc.) */
   setConfig(options: KaelumConfig): KaelumConfig;
@@ -93,6 +104,19 @@ interface KaelumApp extends Express {
 
   /** Remove static file serving */
   removeStatic(): KaelumConfig;
+
+  /** Register a plugin */
+  plugin(fn: KaelumPlugin, options?: Record<string, any>): KaelumApp;
+
+  /** 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.4.8",
+  "version": "1.6.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"