millas 0.2.11 → 0.2.12-beta-1

package/src/http/adapters/ExpressAdapter.js

@@ -0,0 +1,315 @@
+'use strict';
+
+const HttpAdapter = require('./HttpAdapter');
+const MillasRequest = require('../MillasRequest');
+const MillasResponse = require('../MillasResponse');
+const RequestContext = require('../RequestContext');
+const ErrorRenderer = require('../../errors/ErrorRenderer');
+const WelcomePage = require('../WelcomePage');
+const http = require("http");
+
+/**
+ * ExpressAdapter
+ *
+ * The Express implementation of HttpAdapter.
+ * This is the ONLY file in the entire Millas codebase that imports Express
+ * or calls Express APIs (req, res, next, app[verb], app.use, etc.).
+ *
+ * Swapping to a different HTTP engine means writing a new adapter class —
+ * zero changes to the kernel, Router, MiddlewareRegistry, or any user code.
+ */
+class ExpressAdapter extends HttpAdapter {
+
+    /**
+     * @param {import('express').Application} expressApp
+     */
+    constructor(expressApp) {
+        super();
+        this._app = expressApp;
+        this._server = null;
+    }
+
+    // ── Setup ──────────────────────────────────────────────────────────────────
+
+    applyBodyParsers() {
+        const express = require('express');
+        this._app.use(express.json());
+        this._app.use(express.urlencoded({extended: true}));
+    }
+
+    applyMiddleware(fn) {
+        this._app.use(fn);
+    }
+
+    // ── Route mounting ─────────────────────────────────────────────────────────
+
+    mountRoute(verb, path, handlers) {
+        this._app[verb.toLowerCase()](path, ...handlers);
+    }
+
+    mountWelcome(handler) {
+        this._app.get('/', handler);
+    }
+
+    mountNotFound() {
+        this._app.use(ErrorRenderer.notFound());
+    }
+
+    mountErrorHandler() {
+        this._app.use(ErrorRenderer.handler());
+    }
+
+    // ── Request / Response bridge ──────────────────────────────────────────────
+
+    /**
+     * Wrap a Millas kernel handler into an Express (req, res, next) function.
+     *
+     * This is the ONLY place in the codebase where Express req/res/next
+     * appear outside of adapter code. The kernel handler never sees them.
+     */
+    wrapKernelHandler(kernelFn, displayName, container) {
+        const fnName = displayName || kernelFn.name || 'anonymous';
+
+        return (expressReq, expressRes, expressNext) => {
+            const millaReq = new MillasRequest(expressReq);
+            const ctx = new RequestContext(millaReq, container);
+
+            let nextCalled = false;
+            const trackedNext = (...args) => {
+                nextCalled = true;
+                expressNext(...args);
+            };
+
+            new Promise((resolve, reject) => {
+                try {
+                    resolve(kernelFn(ctx, trackedNext));
+                } catch (err) {
+                    reject(err);
+                }
+            })
+                .then(value => {
+                    if (nextCalled) return;
+                    if (expressRes.headersSent) return;
+
+                    if (value === undefined || value === null) {
+                        return expressNext(Object.assign(
+                            new Error(
+                                `Route handler "${fnName}" did not return a response.\n` +
+                                `Return a MillasResponse or a plain value:\n\n` +
+                                `  return jsonify({ ok: true })\n` +
+                                `  return { ok: true }           // auto-wrapped\n` +
+                                `  return 'Hello world'          // auto-wrapped\n` +
+                                `  return redirect('/login')\n` +
+                                `  return view('home', { data })`
+                            ),
+                            {status: 500, statusCode: 500}
+                        ));
+                    }
+
+                    if (value instanceof Error) return expressNext(value);
+
+                    try {
+                        const response = MillasResponse.isResponse(value)
+                            ? value
+                            : this._autoWrap(value);
+                        this.dispatch(response, expressRes);
+                    } catch (dispatchErr) {
+                        expressNext(dispatchErr);
+                    }
+                })
+                .catch(expressNext);
+        };
+    }
+
+    /**
+     * Wrap a Millas middleware instance into an Express (req, res, next) function.
+     */
+    wrapMiddleware(instance, container) {
+        return (expressReq, expressRes, expressNext) => {
+            const millaReq = new MillasRequest(expressReq);
+            const ctx = new RequestContext(millaReq, container);
+
+            const next = () => {
+                expressNext();
+                return undefined;
+            };
+
+            new Promise((resolve, reject) => {
+                try {
+                    resolve(instance.handle(ctx, next));
+                } catch (err) {
+                    reject(err);
+                }
+            })
+                .then(value => {
+                    if (value !== undefined && value !== null && !expressRes.headersSent) {
+                        const response = MillasResponse.isResponse(value)
+                            ? value
+                            : this._autoWrap(value);
+                        this.dispatch(response, expressRes);
+                    }
+                })
+                .catch(expressNext);
+        };
+    }
+
+    /**
+     * Dispatch a MillasResponse to the Express res object.
+     * This is the ONLY place in the codebase where Express res methods are called.
+     */
+    dispatch(response, expressRes) {
+        if (!response || !MillasResponse.isResponse(response)) {
+            throw new Error(
+                '[ExpressAdapter] Expected a MillasResponse. Got: ' + typeof response
+            );
+        }
+
+        // Status
+        expressRes.status(response.statusCode);
+
+        // CORS headers stored by CorsMiddleware on next() calls
+        const corsHeaders = expressRes.req?._corsHeaders;
+        if (corsHeaders) {
+            for (const [name, value] of Object.entries(corsHeaders)) {
+                expressRes.setHeader(name, value);
+            }
+        }
+
+        // Response headers
+        for (const [name, value] of Object.entries(response.headers)) {
+            expressRes.setHeader(name, value);
+        }
+
+        // Cookies
+        for (const [name, {value, options}] of Object.entries(response.cookies)) {
+            if (options.maxAge === 0 || options.expires?.getTime() === 0) {
+                expressRes.clearCookie(name, options);
+            } else {
+                expressRes.cookie(name, value, options);
+            }
+        }
+
+        // Body
+        const {type, body} = response;
+
+        switch (type) {
+            case 'json':
+                return expressRes.json(body);
+
+            case 'html':
+            case 'text':
+                return expressRes.send(body);
+
+            case 'redirect':
+                return expressRes.redirect(response.statusCode, body);
+
+            case 'empty':
+                return expressRes.end();
+
+            case 'file': {
+                const {path: filePath, download, name: fileName} = body;
+                if (download) {
+                    return expressRes.download(
+                        filePath,
+                        fileName || require('path').basename(filePath)
+                    );
+                }
+                return expressRes.sendFile(require('path').resolve(filePath));
+            }
+
+            case 'view': {
+                const {template, data} = body;
+                return expressRes.render(template, data);
+            }
+
+            case 'stream': {
+                if (body && typeof body.pipe === 'function') {
+                    body.pipe(expressRes);
+                } else {
+                    expressRes.end();
+                }
+                return;
+            }
+
+            default:
+                return expressRes.send(body);
+        }
+    }
+
+    // ── Server lifecycle ───────────────────────────────────────────────────────
+
+    listen(port, host) {
+        return new Promise((resolve, reject) => {
+            this.initListener(port, host, resolve, reject);
+        });
+    }
+
+    initListener(port, host, onListening, onError) {
+        const server = http.createServer(this._app);
+        server.listen(port, host);
+        server.on('error', onError);
+        server.on('listening', onListening);
+    }
+
+    close() {
+        return new Promise((resolve) => {
+            if (!this._server) return resolve();
+            this._server.close(() => resolve());
+        });
+    }
+
+    // ── WelcomePage factory ───────────────────────────────────────────────────
+
+    /**
+     * Build the welcome page native handler.
+     * Returned value is passed directly to mountWelcome().
+     */
+    makeWelcomeHandler(version) {
+        return WelcomePage.handler(version);
+    }
+
+    // ── Internal ──────────────────────────────────────────────────────────────
+
+    /**
+     * Auto-wrap a plain JS value into a MillasResponse.
+     * Kept inside the adapter — not on the kernel — because it ultimately
+     * decides what to send over the wire, which is adapter territory.
+     */
+    _autoWrap(value) {
+        if (MillasResponse.isResponse(value)) return value;
+        if (value instanceof Error) throw value;
+
+        if (typeof value === 'string') {
+            return value.trimStart().startsWith('<')
+                ? MillasResponse.html(value)
+                : MillasResponse.text(value);
+        }
+
+        if (
+            typeof value === 'object' ||
+            typeof value === 'number' ||
+            typeof value === 'boolean'
+        ) {
+            return MillasResponse.json(value);
+        }
+
+        return MillasResponse.text(String(value));
+    }
+
+    /**
+     * Expose the raw Express app for escape hatches.
+     * Prefer not using this — it couples code to Express.
+     */
+    get nativeApp() {
+        return this._app;
+    }
+
+    /**
+     * Expose the raw net.Server once listen() has been called.
+     */
+    get server() {
+        return this._server;
+    }
+}
+
+module.exports = ExpressAdapter;

package/src/http/adapters/HttpAdapter.js

@@ -0,0 +1,168 @@
+'use strict';
+
+/**
+ * HttpAdapter
+ *
+ * Abstract interface between the Millas kernel and any underlying HTTP engine.
+ * The kernel never imports Express (or Fastify, or Hono) directly — it only
+ * calls the methods defined here.
+ *
+ * To add a new HTTP engine, create a class that extends HttpAdapter and
+ * implements every method. The kernel works unchanged.
+ *
+ * ── Implemented by ───────────────────────────────────────────────────────────
+ *
+ *   ExpressAdapter   (default, ships with Millas)
+ *   FastifyAdapter   (future)
+ *   HonoAdapter      (future)
+ *
+ * ── Lifecycle ────────────────────────────────────────────────────────────────
+ *
+ *   1. adapter.applyBodyParsers()          — JSON + urlencoded
+ *   2. adapter.applyMiddleware(fn)         — any raw adapter-level middleware
+ *   3. adapter.mountRoute(verb, path, handlers) — register app routes
+ *   4. adapter.mountWelcome(handler)       — optional dev welcome page
+ *   5. adapter.mountNotFound()             — 404 handler
+ *   6. adapter.mountErrorHandler()         — global error handler
+ *   7. await adapter.listen(port, host)    — start accepting connections
+ *   8. adapter.close()                     — graceful shutdown
+ */
+class HttpAdapter {
+
+  // ── Setup ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Apply JSON + urlencoded body parsers.
+   * Called once during bootstrap, before any routes are mounted.
+   */
+  applyBodyParsers() {
+    throw new Error(`${this.constructor.name} must implement applyBodyParsers()`);
+  }
+
+  /**
+   * Apply a single raw middleware function at the adapter level.
+   * Used for things like helmet(), compression() that are engine-specific.
+   *
+   * @param {Function} fn  — adapter-native middleware function
+   */
+  applyMiddleware(fn) {
+    throw new Error(`${this.constructor.name} must implement applyMiddleware(fn)`);
+  }
+
+  // ── Route mounting ─────────────────────────────────────────────────────────
+
+  /**
+   * Register a route handler.
+   *
+   * @param {string}     verb      — 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS'
+   * @param {string}     path      — e.g. '/users/:id'
+   * @param {Function[]} handlers  — [middleware..., terminalHandler]
+   *                                 Each handler is a Millas kernel handler
+   *                                 (expressReq, expressRes, expressNext) already
+   *                                 converted by the adapter's wrapKernelHandler().
+   */
+  mountRoute(verb, path, handlers) {
+    throw new Error(`${this.constructor.name} must implement mountRoute(verb, path, handlers)`);
+  }
+
+  /**
+   * Mount the dev welcome page for GET /.
+   * Only called when no user route covers GET /.
+   *
+   * @param {Function} handler  — adapter-native handler function
+   */
+  mountWelcome(handler) {
+    throw new Error(`${this.constructor.name} must implement mountWelcome(handler)`);
+  }
+
+  /**
+   * Mount the 404 fallback handler.
+   * Must be called AFTER all routes and mountWelcome().
+   */
+  mountNotFound() {
+    throw new Error(`${this.constructor.name} must implement mountNotFound()`);
+  }
+
+  /**
+   * Mount the global error handler.
+   * Must be called LAST — after mountNotFound().
+   */
+  mountErrorHandler() {
+    throw new Error(`${this.constructor.name} must implement mountErrorHandler()`);
+  }
+
+  // ── Request / Response bridge ──────────────────────────────────────────────
+
+  /**
+   * Wrap a Millas kernel handler function into an adapter-native handler.
+   *
+   * The kernel handler signature is:
+   *   (millaCtx: RequestContext, trackedNext: Function) => Promise<MillasResponse>
+   *
+   * The adapter wraps this into whatever its native handler signature is,
+   * e.g. (req, res, next) for Express.
+   *
+   * @param {Function} kernelFn
+   * @param {string}   displayName  — for error messages
+   * @param {object}   container    — DI container
+   * @returns {Function}  adapter-native handler
+   */
+  wrapKernelHandler(kernelFn, displayName, container) {
+    throw new Error(`${this.constructor.name} must implement wrapKernelHandler()`);
+  }
+
+  /**
+   * Wrap a Millas middleware instance into an adapter-native handler.
+   *
+   * @param {object} instance  — Millas Middleware instance with handle(ctx, next)
+   * @param {object} container — DI container
+   * @returns {Function}  adapter-native handler
+   */
+  wrapMiddleware(instance, container) {
+    throw new Error(`${this.constructor.name} must implement wrapMiddleware()`);
+  }
+
+  /**
+   * Dispatch a MillasResponse to the underlying engine's response object.
+   *
+   * @param {MillasResponse} response
+   * @param {*}              nativeRes  — e.g. Express res
+   */
+  dispatch(response, nativeRes) {
+    throw new Error(`${this.constructor.name} must implement dispatch(response, nativeRes)`);
+  }
+
+  // ── Server lifecycle ───────────────────────────────────────────────────────
+
+  /**
+   * Start listening on port/host.
+   * Returns a Promise that resolves once the server is bound.
+   *
+   * @param {number} port
+   * @param {string} host
+   * @returns {Promise<void>}
+   */
+  listen(port, host) {
+    throw new Error(`${this.constructor.name} must implement listen(port, host)`);
+  }
+
+  /**
+   * Gracefully close the server.
+   * Returns a Promise that resolves once all connections are drained.
+   *
+   * @returns {Promise<void>}
+   */
+  close() {
+    throw new Error(`${this.constructor.name} must implement close()`);
+  }
+
+  /**
+   * The name of this adapter, used in logs and error messages.
+   * @returns {string}
+   */
+  get name() {
+    return this.constructor.name;
+  }
+}
+
+module.exports = HttpAdapter;

package/src/http/adapters/index.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const HttpAdapter    = require('./HttpAdapter');
+const ExpressAdapter = require('./ExpressAdapter');
+
+module.exports = {
+  HttpAdapter,
+  ExpressAdapter,
+};

package/src/http/helpers.js

@@ -0,0 +1,164 @@
+'use strict';
+
+const MillasResponse = require('./MillasResponse');
+const HttpError      = require('../errors/HttpError');
+
+/**
+ * Millas HTTP Helper Functions
+ *
+ * These are the only response-building tools developers need.
+ * Import them at the top of any route/controller file.
+ *
+ *   const { jsonify, view, redirect, text, abort } = require('millas');
+ *
+ * Every helper returns a MillasResponse instance. Nothing is written
+ * to the socket until the kernel's ResponseDispatcher processes it.
+ */
+
+/**
+ * Return a JSON response.
+ *
+ *   return jsonify(users)
+ *   return jsonify(user, { status: 201 })
+ *   return jsonify({ error: 'Not found' }, { status: 404 })
+ *   return jsonify(data).header('X-Total', String(total))
+ *   return jsonify(data).cookie('token', jwt, { httpOnly: true })
+ *
+ * @param {*}      data
+ * @param {object} [options]
+ * @param {number} [options.status=200]
+ * @param {object} [options.headers={}]
+ * @returns {MillasResponse}
+ */
+function jsonify(data, options = {}) {
+  return MillasResponse.json(data, options);
+}
+
+/**
+ * Return an HTML view (template) response.
+ *
+ *   return view('users/index', { users })
+ *   return view('emails/welcome', { user }, { status: 200 })
+ *
+ * @param {string} template  — template path relative to views directory
+ * @param {object} [data={}] — data passed to the template
+ * @param {object} [options]
+ * @param {number} [options.status=200]
+ * @returns {MillasResponse}
+ */
+function view(template, data = {}, options = {}) {
+  return MillasResponse.view(template, data, options);
+}
+
+/**
+ * Return a redirect response.
+ *
+ *   return redirect('/login')
+ *   return redirect('/dashboard', { status: 301 })
+ *   return redirect('back')   // redirects to Referer header or '/'
+ *
+ * @param {string} url
+ * @param {object} [options]
+ * @param {number} [options.status=302]
+ * @returns {MillasResponse}
+ */
+function redirect(url, options = {}) {
+  return MillasResponse.redirect(url, options);
+}
+
+/**
+ * Return a plain text response.
+ *
+ *   return text('Hello, world')
+ *   return text('Created', { status: 201 })
+ *
+ * @param {string} content
+ * @param {object} [options]
+ * @param {number} [options.status=200]
+ * @returns {MillasResponse}
+ */
+function text(content, options = {}) {
+  return MillasResponse.text(content, options);
+}
+
+/**
+ * Return a file response (send / download).
+ *
+ *   return file('/storage/uploads/report.pdf')
+ *   return file('/storage/uploads/report.pdf', { download: true })
+ *   return file('/storage/uploads/report.pdf', { download: true, name: 'report.pdf' })
+ *
+ * @param {string} filePath  — absolute or relative path
+ * @param {object} [options]
+ * @param {boolean} [options.download=false] — force download (Content-Disposition: attachment)
+ * @param {string}  [options.name]           — filename shown to the user on download
+ * @returns {MillasResponse}
+ */
+function file(filePath, options = {}) {
+  return MillasResponse.file(filePath, options);
+}
+
+/**
+ * Return an empty response.
+ *
+ *   return empty()        // 204 No Content
+ *   return empty(200)     // 200 with no body
+ *
+ * @param {number} [status=204]
+ * @returns {MillasResponse}
+ */
+function empty(status = 204) {
+  return MillasResponse.empty(status);
+}
+
+/**
+ * Throw an HTTP error — caught by the kernel and rendered by ErrorRenderer.
+ *
+ *   abort(404)
+ *   abort(403, 'You are not allowed to do that')
+ *   abort(422, 'Validation failed', { email: ['Email is required'] })
+ *
+ * @param {number} status
+ * @param {string} [message]
+ * @param {object} [errors]
+ * @throws {HttpError}
+ */
+function abort(status, message, errors = null) {
+  throw new HttpError(status, message, errors);
+}
+
+/**
+ * Throw a 404 Not Found error.
+ *   notFound()
+ *   notFound('User not found')
+ */
+function notFound(message = 'Not Found') {
+  abort(404, message);
+}
+
+/**
+ * Throw a 401 Unauthorized error.
+ */
+function unauthorized(message = 'Unauthorized') {
+  abort(401, message);
+}
+
+/**
+ * Throw a 403 Forbidden error.
+ */
+function forbidden(message = 'Forbidden') {
+  abort(403, message);
+}
+
+module.exports = {
+  jsonify,
+  view,
+  redirect,
+  text,
+  file,
+  empty,
+  abort,
+  notFound,
+  unauthorized,
+  forbidden,
+};

package/src/http/index.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const MillasRequest      = require('./MillasRequest');
+const MillasResponse     = require('./MillasResponse');
+const ResponseDispatcher = require('./ResponseDispatcher');
+const helpers            = require('./helpers');
+
+module.exports = {
+  MillasRequest,
+  MillasResponse,
+  ResponseDispatcher,
+  ...helpers,
+};