create-jen-app 1.2.2 → 1.2.4

package/templates/static/lib/middleware/kernel.js

@@ -1,39 +1,194 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
- */
 import { Pipeline } from "./pipeline.js";
 import { MiddlewareRegistry } from "./registry.js";
 import { Context } from "./context.js";
+import { log } from "../shared/log.js";
+/**
+ * Core HTTP request handler that manages middleware execution and request context.
+ *
+ * The Kernel implements a middleware pipeline pattern:
+ * 1. Receives Node.js req and res objects
+ * 2. Wraps them in a Context object with helper methods and properties
+ * 3. Composes registered middlewares into a callable pipeline
+ * 4. Executes the pipeline with the context for request processing
+ *
+ * Middlewares can:
+ * - Access/modify request and response via ctx.req, ctx.res, ctx.response
+ * - Read/set cookies, headers, query params, route params
+ * - Store and retrieve shared state in ctx.state
+ * - Call ctx.response.json() or other response builders
+ * - Control flow via next() to continue to next middleware
+ */
 export class Kernel {
-    globalMiddleware = [];
-    constructor() { }
-    use(mw) {
-        this.globalMiddleware.push(mw);
+  /**
+   * Array of global middleware functions that run for every request.
+   * Middlewares are stored in order of registration (use() calls).
+   * Executed sequentially in Pipeline.compose().
+   */
+  globalMiddleware = [];
+  constructor() {}
+  /**
+   * Registers a middleware function to run for all requests.
+   * Middleware can be a function, a class constructor, or an object with handle() method.
+   *
+   * @param mw Middleware function: (ctx, next) => Promise<void>
+   *           Or class with: new MyMiddleware().handle(ctx, next)
+   *
+   * @example
+   * kernel.use(async (ctx, next) => {
+   *   console.log(`${ctx.req.method} ${ctx.url.pathname}`);
+   *   await next();
+   * });
+   */
+  use(mw) {
+    this.globalMiddleware.push(mw);
+  }
+  /**
+   * Processes an HTTP request through the global middleware pipeline.
+   * Creates a Context wrapping the request/response, composes middlewares, and executes them.
+   * Catches any uncaught errors and sends a safe 500 response.
+   *
+   * @param req Node.js IncomingMessage (HTTP request object)
+   * @param res Node.js ServerResponse (HTTP response object)
+   *
+   * @returns Promise that resolves when middleware chain completes
+   *
+   * @example
+   * const server = createServer((req, res) => {
+   *   kernel.handle(req, res);
+   * });
+   */
+  async handle(req, res) {
+    try {
+      const ctx = new Context(req, res);
+      const fn = Pipeline.compose(this.globalMiddleware);
+      await fn(ctx, async () => {});
+    } catch (err) {
+      // Uncaught error in middleware pipeline
+      log.error(`[Kernel] Uncaught error: ${err}`);
+      if (err && err.stack) {
+        log.error(`Stack: ${err.stack}`);
+      }
+      // If headers already sent, destroy socket
+      if (res.headersSent) {
+        log.error("[Kernel] Headers already sent, destroying socket");
+        if (res.socket && !res.socket.destroyed) {
+          res.socket.destroy();
+        }
+        return;
+      }
+      // Try to send a safe 500 response
+      try {
+        res.statusCode = 500;
+        res.setHeader("content-type", "text/html; charset=utf-8");
+        res.setHeader("cache-control", "no-store, no-cache, must-revalidate");
+        res.end(`<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>500 - Internal Server Error</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+      background: #f5f5f5;
+      margin: 0;
+      padding: 20px;
+    }
+    .container {
+      max-width: 600px;
+      margin: 60px auto;
+      background: white;
+      padding: 40px;
+      border-radius: 8px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+    }
+    h1 {
+      color: #d32f2f;
+      margin: 0 0 20px 0;
+      font-size: 32px;
+    }
+    p {
+      color: #666;
+      line-height: 1.6;
+      margin: 10px 0;
     }
-    async handle(req, res) {
-        const ctx = new Context(req, res);
-        const fn = Pipeline.compose(this.globalMiddleware);
-        await fn(ctx, async () => { });
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>500 - Internal Server Error</h1>
+    <p>The server encountered an unexpected error while processing your request.</p>
+    <p>Our team has been notified. Please try again later.</p>
+  </div>
+</body>
+</html>`);
+      } catch (e) {
+        log.error(`[Kernel] Failed to send error response: ${e}`);
+        // Last resort: destroy socket
+        if (res.socket && !res.socket.destroyed) {
+          res.socket.destroy();
+        }
+      }
     }
-    async handleWithGroup(req, res, groupName) {
-        const ctx = new Context(req, res);
-        const registry = MiddlewareRegistry.get();
-        const groupMw = registry.getGroup(groupName);
-        const fn = Pipeline.compose([...this.globalMiddleware, ...groupMw]);
-        await fn(ctx, async () => { });
+  }
+  /**
+   * Processes a request through global middleware plus a registered middleware group.
+   * Retrieves middleware from the registry by group name and composes them with global middleware.
+   * Useful for route-specific or feature-specific middleware chains.
+   * Catches any uncaught errors and sends a safe 500 response.
+   *
+   * @param req Node.js IncomingMessage
+   * @param res Node.js ServerResponse
+   * @param groupName Name of the middleware group registered in MiddlewareRegistry
+   *
+   * @returns Promise that resolves when complete middleware chain executes
+   *
+   * @example
+   * // Given a group named "apiMiddleware" with auth and logging
+   * await kernel.handleWithGroup(req, res, "apiMiddleware");
+   */
+  async handleWithGroup(req, res, groupName) {
+    try {
+      const ctx = new Context(req, res);
+      const registry = MiddlewareRegistry.get();
+      const groupMw = registry.getGroup(groupName);
+      const fn = Pipeline.compose([...this.globalMiddleware, ...groupMw]);
+      await fn(ctx, async () => {});
+    } catch (err) {
+      // Uncaught error in middleware pipeline
+      log.error(
+        `[Kernel] Uncaught error in middleware group "${groupName}": ${err}`,
+      );
+      if (err && err.stack) {
+        log.error(`Stack: ${err.stack}`);
+      }
+      // If headers already sent, destroy socket
+      if (res.headersSent) {
+        log.error("[Kernel] Headers already sent, destroying socket");
+        if (res.socket && !res.socket.destroyed) {
+          res.socket.destroy();
+        }
+        return;
+      }
+      // Try to send a safe 500 response
+      try {
+        res.statusCode = 500;
+        res.setHeader("content-type", "application/json");
+        res.setHeader("cache-control", "no-store, no-cache, must-revalidate");
+        res.end(
+          JSON.stringify({
+            error: "Internal Server Error",
+            message:
+              "An unexpected error occurred while processing your request.",
+          }),
+        );
+      } catch (e) {
+        log.error(`[Kernel] Failed to send error response: ${e}`);
+        // Last resort: destroy socket
+        if (res.socket && !res.socket.destroyed) {
+          res.socket.destroy();
+        }
+      }
     }
+  }
 }

package/templates/static/lib/middleware/pipeline.js

@@ -1,67 +1,148 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
+/**
+ * Middleware composition and execution engine.
+ * Composes multiple middleware functions into a single callable function.
+ * Supports functions, class constructors, and objects with handle() methods.
  *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
+ * The Pipeline implements the "cascade" or "onion" middleware pattern:
+ * - Middlewares are executed sequentially in order
+ * - Each middleware receives a next() function to pass control to the next handler
+ * - Execution returns through each middleware in reverse order
+ * - Early termination is possible by not calling next()
  *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ * @example
+ * const middlewares = [
+ *   (ctx, next) => { console.log("1 start"); next().then(() => console.log("1 end")); },
+ *   (ctx, next) => { console.log("2 start"); next().then(() => console.log("2 end")); },
+ * ];
+ * // Logs: "1 start", "2 start", "2 end", "1 end" (onion pattern)
  */
 export class Pipeline {
-    static compose(middleware) {
-        if (!Array.isArray(middleware))
-            throw new TypeError("Middleware stack must be an array!");
-        const handlers = middleware.map((mw) => this.resolveMiddleware(mw));
-        return function (context, next) {
-            let index = -1;
-            function dispatch(i) {
-                if (i <= index)
-                    return Promise.reject(new Error("next() called multiple times"));
-                index = i;
-                let fn = handlers[i];
-                if (i === handlers.length) {
-                    fn = next;
-                }
-                if (!fn)
-                    return Promise.resolve();
-                try {
-                    return Promise.resolve(fn(context, dispatch.bind(null, i + 1)));
-                }
-                catch (err) {
-                    return Promise.reject(err);
-                }
-            }
-            return dispatch(0);
-        };
-    }
-    static resolveMiddleware(mw) {
-        if (typeof mw === "function") {
-            // Check if it's a class constructor (has prototype.handle)
-            if ("prototype" in mw &&
-                mw.prototype &&
-                typeof mw.prototype.handle === "function") {
-                try {
-                    const instance = new mw();
-                    return instance.handle.bind(instance);
-                }
-                catch (e) {
-                    // If instantiation fails, assume it's a simple function middleware
-                    return mw;
-                }
-            }
-            return mw;
+  /**
+   * Composes an array of middleware into a single callable function.
+   * The composed function accepts (context, finalNext) and executes middlewares in sequence.
+   *
+   * Middleware resolution:
+   * - Functions are passed through as-is
+   * - Class constructors (functions with prototype.handle) are instantiated and their handle() bound
+   * - Objects with handle() methods have handle() bound to them
+   *
+   * @param middleware Array of middleware to compose
+   * @returns Composed function: async (context, next) => Promise<void>
+   *
+   * @throws {TypeError} If middleware is not an array
+   * @throws {TypeError} If a middleware is not a function, class, or object with handle()
+   *
+   * @example
+   * const composed = Pipeline.compose([authMiddleware, loggingMiddleware]);
+   * await composed(ctx, () => console.log("done"));
+   */
+  static compose(middleware) {
+    if (!Array.isArray(middleware))
+      throw new TypeError("Middleware stack must be an array!");
+    /**
+     * Resolve each middleware to a callable function.
+     * Handles functions, class constructors, and objects with handle() methods.
+     */
+    const handlers = middleware.map((mw) => this.resolveMiddleware(mw));
+    /**
+     * Returns the composed middleware function that executes the pipeline.
+     * Uses the dispatch() pattern to enforce single-next-call and maintain order.
+     *
+     * @param context Request context object passed to each middleware
+     * @param next Final handler called after all middlewares
+     * @returns Promise that resolves when entire pipeline completes
+     */
+    return function (context, next) {
+      /**
+       * Tracks the current dispatch index to detect "next() called multiple times".
+       * This prevents middleware from accidentally calling next() twice,
+       * which would cause handlers to execute in wrong order.
+       */
+      let index = -1;
+      /**
+       * Dispatches (executes) the middleware at index i.
+       * Enforces that next() can only be called once by checking index increment.
+       *
+       * @param i Index of the middleware to execute
+       * @returns Promise from the middleware or final next() handler
+       */
+      function dispatch(i) {
+        if (i <= index)
+          return Promise.reject(new Error("next() called multiple times"));
+        index = i;
+        let fn = handlers[i];
+        /**
+         * If we've exhausted all middlewares, call the final next() handler.
+         * This allows code after Pipeline.compose() to run.
+         */
+        if (i === handlers.length) {
+          fn = next;
         }
-        if (typeof mw === "object" && mw !== null && "handle" in mw) {
-            return mw.handle.bind(mw);
+        if (!fn) return Promise.resolve();
+        try {
+          /**
+           * Execute the middleware function, passing:
+           * - context: the request context object
+           * - dispatch.bind(null, i + 1): the next() function for chaining
+           *
+           * Promise.resolve() wraps non-promise returns for consistency.
+           */
+          return Promise.resolve(fn(context, dispatch.bind(null, i + 1)));
+        } catch (err) {
+          return Promise.reject(err);
         }
-        throw new TypeError("Middleware must be a function, a class constructor, or an object with a handle() method");
+      }
+      /**
+       * Start the pipeline at the first middleware (index 0).
+       */
+      return dispatch(0);
+    };
+  }
+  /**
+   * Resolves a middleware to a callable (context, next) => Promise function.
+   * Supports three forms:
+   * 1. Function: Used directly
+   * 2. Class constructor with handle() method: Instantiated and bound
+   * 3. Object with handle() method: handle() method is bound
+   *
+   * @param mw Middleware in one of the above forms
+   * @returns Callable (context, next) => Promise function
+   *
+   * @throws {TypeError} If mw is not a recognized middleware type
+   */
+  static resolveMiddleware(mw) {
+    if (typeof mw === "function") {
+      /**
+       * Check if this is a class constructor with a handle() method.
+       * Constructors have a prototype property with methods defined on it.
+       */
+      if (
+        "prototype" in mw &&
+        mw.prototype &&
+        typeof mw.prototype.handle === "function"
+      ) {
+        try {
+          const instance = new mw();
+          return instance.handle.bind(instance);
+        } catch (e) {
+          /**
+           * If instantiation fails (constructor requires params),
+           * assume it's a simple function middleware and use it directly.
+           */
+          return mw;
+        }
+      }
+      return mw;
+    }
+    /**
+     * Check for object with handle() method.
+     * Useful for class instances or middleware objects.
+     */
+    if (typeof mw === "object" && mw !== null && "handle" in mw) {
+      return mw.handle.bind(mw);
     }
+    throw new TypeError(
+      "Middleware must be a function, a class constructor, or an object with a handle() method",
+    );
+  }
 }

package/templates/static/lib/middleware/registry.js

@@ -1,41 +1,85 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
+/**
+ * Global registry for named middleware and middleware groups.
+ * Enables reusable middleware composition patterns where middlewares are registered once
+ * and then referenced by name in groups or applied globally.
  *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
+ * The registry follows the singleton pattern to maintain a single shared instance
+ * throughout the application lifecycle.
  *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ * @example
+ * const registry = MiddlewareRegistry.get();
+ * registry.register('auth', authMiddleware);
+ * registry.register('logger', loggingMiddleware);
+ * registry.group('api', ['auth', 'logger']);
+ * // Later, get the group to apply to routes
+ * const apiMw = registry.getGroup('api'); // [authMiddleware, loggingMiddleware]
  */
 export class MiddlewareRegistry {
-    static instance;
-    middleware = new Map();
-    groups = new Map();
-    constructor() { }
-    static get() {
-        if (!this.instance)
-            this.instance = new MiddlewareRegistry();
-        return this.instance;
-    }
-    register(name, mw) {
-        this.middleware.set(name, mw);
-    }
-    get(name) {
-        return this.middleware.get(name);
-    }
-    group(groupName, middlewareNames) {
-        this.groups.set(groupName, middlewareNames);
-    }
-    getGroup(groupName) {
-        const names = this.groups.get(groupName) || [];
-        return names.map((n) => this.get(n)).filter((m) => !!m);
-    }
+  // Singleton instance shared across the application.
+  static instance;
+  // Map of named middleware functions.
+  middleware = new Map();
+  // Map of middleware group definitions (groups contain names of registered middleware).
+  groups = new Map();
+  constructor() {}
+  /**
+   * Gets or creates the singleton registry instance.
+   * All calls to this method return the same instance, ensuring a single registry.
+   *
+   * @returns The singleton MiddlewareRegistry instance.
+   */
+  static get() {
+    if (!this.instance) this.instance = new MiddlewareRegistry();
+    return this.instance;
+  }
+  /**
+   * Registers a middleware function with a name.
+   * Named middleware can be referenced in groups or applied individually.
+   *
+   * @param name Unique identifier for the middleware.
+   * @param mw The middleware function to register.
+   *
+   * @example
+   * registry.register('cors', corsMiddleware);
+   */
+  register(name, mw) {
+    this.middleware.set(name, mw);
+  }
+  /**
+   * Retrieves a registered middleware by name.
+   *
+   * @param name The name of the middleware to retrieve.
+   * @returns The middleware function, or undefined if not found.
+   */
+  get(name) {
+    return this.middleware.get(name);
+  }
+  /**
+   * Defines a group of middleware by names.
+   * Groups allow composing multiple middleware into a named set that can be applied together.
+   *
+   * @param groupName The name of the group.
+   * @param middlewareNames Array of registered middleware names to include in the group.
+   *
+   * @example
+   * registry.group('secure', ['auth', 'rateLimit', 'securityHeaders']);
+   */
+  group(groupName, middlewareNames) {
+    this.groups.set(groupName, middlewareNames);
+  }
+  /**
+   * Retrieves all middleware functions in a named group.
+   * Resolves group names to actual middleware functions.
+   * Skips missing middleware names gracefully.
+   *
+   * @param groupName The name of the group to retrieve.
+   * @returns Array of middleware functions in the group (in order).
+   *
+   * @example
+   * const middlewares = registry.getGroup('secure'); // [authFn, rateLimitFn, securityHeadersFn]
+   */
+  getGroup(groupName) {
+    const names = this.groups.get(groupName) || [];
+    return names.map((n) => this.get(n)).filter((m) => !!m);
+  }
 }