millas 0.2.11 → 0.2.12-beta-1

package/src/container/Application.js

@@ -1,12 +1,14 @@
 'use strict';
 
-const Container        = require('./Container');
+const Container = require('./Container');
 const ProviderRegistry = require('../providers/ProviderRegistry');
-const { Route, Router, MiddlewareRegistry } = require('../router');
-const CorsMiddleware     = require('../middleware/CorsMiddleware');
+const {Route, Router, MiddlewareRegistry} = require('../router');
+const CorsMiddleware = require('../middleware/CorsMiddleware');
 const ThrottleMiddleware = require('../middleware/ThrottleMiddleware');
-const LogMiddleware      = require('../middleware/LogMiddleware');
-const AuthMiddleware     = require('../auth/AuthMiddleware');
+const LogMiddleware = require('../middleware/LogMiddleware');
+const AuthMiddleware = require('../auth/AuthMiddleware');
+const Facade = require("../facades/Facade");
+const UrlGenerator = require("../http/UrlGenerator");
 
 /**
  * Application
@@ -14,195 +16,298 @@ const AuthMiddleware     = require('../auth/AuthMiddleware');
  * The central Millas kernel. Owns:
  *   - The DI container
  *   - The provider registry
- *   - The Express app
+ *   - The HttpAdapter  (NOT Express directly — any adapter works)
  *   - The route instance
  *   - The middleware registry
  *
+ * The kernel is fully decoupled from Express. It talks to the HTTP layer
+ * exclusively through the HttpAdapter interface.
+ *
  * Usage in bootstrap/app.js:
  *
- *   const { Application } = require('millas/src/container');
- *   const app = new Application(expressApp);
- *   app.providers([AppServiceProvider, DatabaseServiceProvider]);
+ *   const { Application }    = require('millas/src/container');
+ *   const { ExpressAdapter } = require('millas/src/http/adapters');
+ *   const express = require('express');
+ *
+ *   const adapter = new ExpressAdapter(express());
+ *   const app     = new Application(adapter);
+ *   app.providers([AppServiceProvider]);
  *   await app.boot();
- *   app.routes(route => {
- *     require('../routes/web')(route);
- *     require('../routes/api')(route);
- *   });
+ *   app.routes(Route => require('../routes/api')(Route));
  *   app.mount();
  *   app.listen();
  */
 class Application {
-  constructor(expressApp) {
-    this._express   = expressApp;
-    this._container = new Container();
-    this._providers = new ProviderRegistry(this._container, expressApp);
-    this._mwRegistry = new MiddlewareRegistry();
-    this._route     = new Route();
-    this._booted    = false;
-
-    // Register core framework bindings
-    this._registerCoreBindings();
-  }
-
-  // ─── Configuration ───────────────────────────────────────────────────────────
-
-  /**
-   * Add service providers.
-   * @param {Array} providers
-   */
-  providers(providers = []) {
-    this._providers.addMany(providers);
-    return this;
-  }
-
-  /**
-   * Register a middleware alias.
-   *
-   * app.middleware('auth', AuthMiddleware)
-   * app.middleware('throttle', new ThrottleMiddleware({ max: 60 }))
-   */
-  middleware(alias, handler) {
-    this._mwRegistry.register(alias, handler);
-    return this;
-  }
-
-  /**
-   * Define all routes via a callback.
-   *
-   * app.routes(route => {
-   *   require('../routes/web')(route);
-   *   require('../routes/api')(route);
-   * });
-   */
-  routes(callback) {
-    callback(this._route);
-    return this;
-  }
-
-  // ─── Lifecycle ───────────────────────────────────────────────────────────────
-
-  /**
-   * Run the full provider register → boot lifecycle.
-   */
-  async boot() {
-    if (this._booted) return this;
-    await this._providers.boot();
-    this._booted = true;
-    return this;
-  }
-
-  /**
-   * Bind all routes onto the Express app.
-   * Does NOT add 404/error fallbacks — call mountFallbacks() after
-   * registering any extra middleware (e.g. Admin panel).
-   *
-   * Typical usage:
-   *   app.mountRoutes();
-   *   Admin.mount(expressApp);   // admin routes added here
-   *   app.mountFallbacks();      // 404 + error handler last
-   *
-   * Or use app.mount() which does all three in one call.
-   */
-  mountRoutes() {
-    this._router = new Router(this._express, this._route.getRegistry(), this._mwRegistry);
-    this._router.mountRoutes();
-    return this;
-  }
-
-  /**
-   * Add 404 + global error handlers. Must be called LAST.
-   */
-  mountFallbacks() {
-    if (!this._router) {
-      this._router = new Router(this._express, this._route.getRegistry(), this._mwRegistry);
-    }
-    this._router.mountFallbacks();
-    return this;
-  }
-
-  /**
-   * Bind routes + add 404/error handlers in one call.
-   * Use this when NOT using the Admin panel, or when Admin
-   * is mounted before this call.
-   */
-  mount() {
-    const router = new Router(this._express, this._route.getRegistry(), this._mwRegistry);
-    router.mount();
-    return this;
-  }
-
-  /**
-   * Start the HTTP server.
-   */
-  listen(port, host, callback) {
-    const _port = port || parseInt(process.env.APP_PORT, 10) || 3000;
-    const _host = host || process.env.MILLAS_HOST || 'localhost';
-
-    this._express.listen(_port, _host, () => {
-      if (!process.env.MILLAS_ROUTE_LIST) {
+    /**
+     * @param {import('../http/adapters/HttpAdapter')} adapter
+     */
+    constructor(adapter) {
+        this._adapter = adapter;
+        this._container = new Container();
+        this._providers = new ProviderRegistry(this._container, adapter.nativeApp || adapter);
+        this._mwRegistry = new MiddlewareRegistry();
+        this._route = new Route();
+        this._booted = false;
+
+        this._registerCoreBindings();
+    }
+
+    // ── Configuration ──────────────────────────────────────────────────────────
+
+    providers(providers = []) {
+        this._providers.addMany(providers);
+        return this;
+    }
+
+    /**
+     * Register a middleware alias.
+     *
+     *   app.middleware('auth', AuthMiddleware)
+     *   app.middleware('throttle', new ThrottleMiddleware({ max: 60 }))
+     */
+    middleware(alias, handler) {
+        this._mwRegistry.register(alias, handler);
+        return this;
+    }
+
+    /**
+     * Define all routes via a callback.
+     *
+     *   app.routes(Route => {
+     *     require('../routes/api')(Route);
+     *   });
+     */
+    routes(callback) {
+        callback(this._route);
+        return this;
+    }
+
+    // ── Lifecycle ──────────────────────────────────────────────────────────────
+
+    /**
+     * Run the full provider lifecycle:
+     *   Phase 0 — beforeBoot  (sync, global setup)
+     *   Phase 1 — register    (sync, container bindings)
+     *   Phase 2 — boot        (async, all bindings available)
+     */
+    async boot() {
+        if (this._booted) return this;
+
+        this._emitSync('platform.booting', {providers: this._providers.list()});
+
+        await this._providers.boot();
+        this._booted = true;
+
+        this._emitSync('platform.booted', {providers: this._providers.list()});
+
+        return this;
+    }
+
+    /**
+     * Mount all registered routes onto the adapter.
+     * Does NOT add fallbacks — call mountFallbacks() separately after
+     * any extra middleware (e.g. Admin panel) is mounted.
+     */
+    mountRoutes() {
+        this._router = new Router(
+            this._adapter,
+            this._route.getRegistry(),
+            this._mwRegistry,
+            this._container
+        );
+        this._router.mountRoutes();
+        return this;
+    }
+
+    /**
+     * Mount 404 + error handler. Must be called LAST.
+     */
+    mountFallbacks() {
+        if (!this._router) {
+            this._router = new Router(
+                this._adapter,
+                this._route.getRegistry(),
+                this._mwRegistry,
+                this._container
+            );
+        }
+        this._router.mountFallbacks();
+        return this;
+    }
+
+    /**
+     * Mount routes + fallbacks in one call.
+     */
+    mount() {
+        const router = new Router(
+            this._adapter,
+            this._route.getRegistry(),
+            this._mwRegistry,
+            this._container
+        );
+        router.mount();
+        return this;
+    }
+
+    /**
+     * Start the HTTP server via the adapter.
+     * Emits: platform.listening
+     */
+    async listen(port, host, callback) {
+        const _port = port
+            || parseInt(process.env.MILLAS_INTERNAL_PORT, 10)
+            || parseInt(process.env.APP_PORT, 10)
+            || 3000;
+        const _host = host || process.env.MILLAS_HOST || 'localhost';
+
+        await this._adapter.listen(_port, _host);
+
+        if (process.env.APP_ENV === "development" && process.env.MILLAS_START_UP && !process.env.MILLERS_NODE_ENV) {
+            this._printStartupLog(_host, _port);
+        }
+
+        this._emitSync('platform.listening', {port: _port, host: _host});
+
+        if (typeof callback === 'function') callback(_port, _host);
+
+        return this;
+    }
+
+    _printStartupLog(host, port) {
+        const chalk = _tryChalk();
         const routeCount = this._route.list().length;
-        console.log(`\n  ⚡ Millas running at http://${_host}:${_port}`);
-        console.log(`  ${routeCount} route(s) registered\n`);
-      }
-      if (typeof callback === 'function') callback(_port, _host);
-    });
-
-    return this;
-  }
-
-  // ─── Container Proxy ─────────────────────────────────────────────────────────
-
-  /**
-   * Bind a transient into the container.
-   */
-  bind(abstract, concrete) {
-    this._container.bind(abstract, concrete);
-    return this;
-  }
-
-  /**
-   * Bind a singleton into the container.
-   */
-  singleton(abstract, concrete) {
-    this._container.singleton(abstract, concrete);
-    return this;
-  }
-
-  /**
-   * Register a pre-built instance.
-   */
-  instance(abstract, value) {
-    this._container.instance(abstract, value);
-    return this;
-  }
-
-  /**
-   * Resolve something from the container.
-   */
-  make(abstract, overrides) {
-    return this._container.make(abstract, overrides);
-  }
-
-  // ─── Accessors ───────────────────────────────────────────────────────────────
-
-  get container()    { return this._container; }
-  get route()        { return this._route; }
-  get express()      { return this._express; }
-  get mwRegistry()   { return this._mwRegistry; }
-
-  // ─── Internal ────────────────────────────────────────────────────────────────
-
-  _registerCoreBindings() {
-    // Register the application itself
-    this._container.instance('app',       this);
-    this._container.instance('container', this._container);
-
-    // Register built-in middleware
-    this._mwRegistry.register('cors',     new CorsMiddleware());
-    this._mwRegistry.register('throttle', new ThrottleMiddleware({ max: 60, window: 60 }));
-    this._mwRegistry.register('log',      new LogMiddleware());
-    this._mwRegistry.register('auth',     AuthMiddleware);
-  }
+        const url = `http://${host}:${port}`;
+
+        // console.error(chalk.dim('›') + '  ' +
+        //     chalk.dim('Listening on ') + chalk.bold.white(url)
+        // );
+        console.log(chalk.dim('›') + '  ' +
+            chalk.white(routeCount + ' route' + (routeCount !== 1 ? 's' : '') + ' registered')
+        );
+        console.error(chalk.dim('›') + '  ' +
+            chalk.dim('Press ') + chalk.bold('Ctrl+C') + chalk.dim(' to stop')
+        );
+    }
+
+    /**
+     * Graceful shutdown.
+     */
+    async shutdown(code = 0) {
+        this._emitSync('platform.shutting_down', {});
+        await this._adapter.close();
+        process.exit(code);
+    }
+
+    // ── Platform event bus ─────────────────────────────────────────────────────
+
+    on(event, fn) {
+        if (!this._platformListeners) this._platformListeners = new Map();
+        if (!this._platformListeners.has(event)) this._platformListeners.set(event, []);
+        this._platformListeners.get(event).push(fn);
+        return this;
+    }
+
+    _emitSync(event, data) {
+        if (!this._platformListeners) return;
+        const listeners = this._platformListeners.get(event) || [];
+        for (const fn of listeners) {
+            try {
+                fn(data);
+            } catch {
+            }
+        }
+    }
+
+    // ── Container proxy ────────────────────────────────────────────────────────
+
+    bind(abstract, concrete) {
+        this._container.bind(abstract, concrete);
+        return this;
+    }
+
+    singleton(abstract, c) {
+        this._container.singleton(abstract, c);
+        return this;
+    }
+
+    instance(abstract, value) {
+        this._container.instance(abstract, value);
+        return this;
+    }
+
+    make(abstract, overrides) {
+        return this._container.make(abstract, overrides);
+    }
+
+    // ── Accessors ──────────────────────────────────────────────────────────────
+
+    get container() {
+        return this._container;
+    }
+
+    get route() {
+        return this._route;
+    }
+
+    get adapter() {
+        return this._adapter;
+    }
+
+    get mwRegistry() {
+        return this._mwRegistry;
+    }
+
+    /**
+     * express — backward-compatible escape hatch.
+     * Returns the native app from the adapter if available.
+     * Prefer adapter.nativeApp for new code.
+     */
+    get express() {
+        return this._adapter.nativeApp || this._adapter;
+    }
+
+    // ── Internal ───────────────────────────────────────────────────────────────
+
+    _registerCoreBindings() {
+        this._container.instance('app', this);
+        this._container.instance('container', this._container);
+
+        const Facade = require('../facades/Facade');
+        Facade.setContainer(this._container);
+        // Http client — always available, no provider needed
+        const {HttpClient} = require('../http/HttpClient');
+        this._container.instance('HttpClient', HttpClient);
+        this._container.alias('http', "HttpClient");
+
+        const UrlGenerator = require('../http/UrlGenerator');
+        const urlGenerator = new UrlGenerator({
+            baseUrl: process.env.APP_URL || '',
+            appKey: process.env.APP_KEY || '',
+            routeRegistry: this._route?.getRegistry?.() || null,
+        });
+        this._container.instance('url', urlGenerator);
+
+
+        this._mwRegistry.register('cors', new CorsMiddleware());
+        this._mwRegistry.register('throttle', new ThrottleMiddleware({max: 60, window: 60}));
+        this._mwRegistry.register('log', new LogMiddleware());
+        this._mwRegistry.register('auth', AuthMiddleware);
+    }
 }
 
 module.exports = Application;
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function _tryChalk() {
+    try {
+        return require('chalk');
+    } catch {
+        const id = s => s;
+        const p = new Proxy({}, {get: () => p, apply: (_, __, [s]) => String(s || '')});
+        p.dim = id;
+        p.bold = p;
+        p.white = id;
+        return p;
+    }
+}

package/src/container/HttpServer.js

@@ -0,0 +1,156 @@
+'use strict';
+
+/**
+ * HttpServer
+ *
+ * Owns everything that belongs to the process/server layer — the things
+ * Express puts in bin/www that have nothing to do with your app logic:
+ *
+ *   - Port normalisation and validation
+ *   - EADDRINUSE / EACCES error handling with clear messages
+ *   - Startup log (route count, URL, Ctrl+C hint)
+ *   - IPC ready signal to the hot-reload proxy (millas serve)
+ *   - Graceful shutdown on SIGTERM / SIGINT
+ *
+ * The Application kernel knows nothing about any of this.
+ *
+ * ── Usage in bootstrap/server.js ────────────────────────────────────────────
+ *
+ *   const app    = require('./app');          // configured Millas app, no listen()
+ *   const server = new HttpServer(app);
+ *   server.start();
+ *
+ * ── Advanced ─────────────────────────────────────────────────────────────────
+ *
+ *   new HttpServer(app, {
+ *     port:     4000,
+ *     host:     '0.0.0.0',
+ *     onStart:  (port, host) => console.log(`up on ${host}:${port}`),
+ *     onShutdown: () => db.close(),
+ *   }).start();
+ */
+class HttpServer {
+    /**
+     * @param {import('./Application')} app     — booted Millas Application instance
+     * @param {object}                  options
+     * @param {number}  [options.port]
+     * @param {string}  [options.host]
+     * @param {Function}[options.onStart]     — (port, host) => void, called after listen
+     * @param {Function}[options.onShutdown]  — async () => void, called before process.exit
+     */
+    constructor(app, options = {}) {
+        this._app = app;
+        this._options = options;
+    }
+
+    /**
+     * Resolve port, boot the server, wire signals.
+     * Returns a Promise that resolves once the server is listening.
+     */
+    async start() {
+        const port = this._resolvePort();
+        const host = this._options.host
+            || process.env.MILLAS_HOST
+            || process.env.HOST
+            || 'localhost';
+
+        // Boot providers if not already done
+        if (!this._app._booted) {
+            await this._app.boot();
+        }
+
+        // Mount routes + fallbacks if not already mounted
+        if (!this._app._router) {
+            this._app.mount();
+        }
+
+        // Start listening — may throw on EADDRINUSE / EACCES
+        try {
+            await this._app.listen(port, host);
+        } catch (err) {
+            this._handleListenError(err, port);
+            return; // _handleListenError always exits
+        }
+
+        // Notify the millas serve hot-reload proxy that we're ready
+        if (typeof process.send === 'function') {
+            process.send({type: 'ready', port});
+        }
+
+        // User callback
+        if (typeof this._options.onStart === 'function') {
+            this._options.onStart(port, host);
+        }
+        this._handleSignals();
+
+    }
+
+    // ── Private ────────────────────────────────────────────────────────────────
+
+    _resolvePort() {
+        const raw =
+            this._options.port ||
+            parseInt(process.env.MILLAS_INTERNAL_PORT, 10) ||
+            parseInt(process.env.APP_PORT, 10) ||
+            parseInt(process.env.PORT, 10) ||
+            3000;
+
+        return this._normalizePort(raw);
+    }
+
+    _normalizePort(val) {
+        const n = parseInt(val, 10);
+        if (isNaN(n)) return val;   // named pipe — pass through
+        if (n >= 0) return n;
+        return 3000;
+    }
+
+    _handleListenError(err, port) {
+        const bind = typeof port === 'string' ? `pipe ${port}` : `port ${port}`;
+
+        switch (err.code) {
+            case 'EACCES':
+                console.error(
+                    `✖  ${bind} requires elevated privileges.\n` +
+                    `     Try a port above 1024 or run with sudo.`
+                );
+                break;
+
+            case 'EADDRINUSE':
+                console.error(
+                    `✖  ${bind} is already in use.\n` +
+                    `     Another process is listening on that port.\n` +
+                    `     Try: APP_PORT=3001 millas serve`
+                );
+                break;
+
+            default:
+                console.error(`✖  Listen error: ${err.message}`);
+                if (process.env.APP_DEBUG) console.error(err.stack + '\n');
+        }
+
+        process.exit(1);
+    }
+
+
+    _handleSignals() {
+        const shutdown = async (signal) => {
+            process.exit(0);
+            // process.stdout.write(`\n  Shutting down (${signal})…\n`);
+            //
+            // if (typeof this._options.onShutdown === 'function') {
+            //     try {
+            //         await this._options.onShutdown();
+            //     } catch {
+            //     }
+            // }
+            //
+            // await this._app.shutdown(0);
+        };
+
+        process.once('SIGTERM', () => shutdown("SIGTERM"));
+        process.once('SIGINT', () => shutdown('SIGINT'));
+    }
+}
+
+module.exports = HttpServer;