millas 0.2.10 → 0.2.12-beta

package/src/index.js

@@ -1,6 +1,46 @@
 'use strict';
 
 // ── HTTP Layer ────────────────────────────────────────────────────
+const {
+  MillasRequest,
+  MillasResponse,
+  ResponseDispatcher,
+  jsonify,
+  view,
+  redirect,
+  text,
+  file,
+  empty,
+  abort,
+  notFound,
+  unauthorized,
+  forbidden,
+} = require('./http/index');
+const RequestContext = require('./http/RequestContext');
+
+// ── Validation ────────────────────────────────────────────────────
+const {
+  Validator,
+  BaseValidator,
+  StringValidator,
+  EmailValidator,
+  NumberValidator,
+  BooleanValidator,
+  DateValidator,
+  ArrayValidator,
+  ObjectValidator,
+  FileValidator,
+  string,
+  email,
+  number,
+  boolean,
+  date,
+  array,
+  object: objectField,
+  file:   fileField,
+} = require('./validation/Validator');
+const MillasApp = require('./container/MillasApp');
+// ── HTTP Layer (old) ──────────────────────────────────────────────
 const Controller         = require('./controller/Controller');
 const Middleware         = require('./middleware/Middleware');
 const MiddlewarePipeline = require('./middleware/MiddlewarePipeline');
@@ -12,7 +52,6 @@ const HttpError          = require('./errors/HttpError');
 // ── DI Container ─────────────────────────────────────────────────
 const Container          = require('./container/Container');
 const Application        = require('./container/Application');
-const MillasApp          = require('./container/MillasApp');
 const ServiceProvider    = require('./providers/ServiceProvider');
 const ProviderRegistry   = require('./providers/ProviderRegistry');
 
@@ -61,11 +100,25 @@ const Storage     = require('./storage/Storage');
 const LocalDriver = require('./storage/drivers/LocalDriver');
 
 module.exports = {
+  // Millas App
+  MillasApp,
+  // ── Millas HTTP layer ──────────────────────────────────────────
+  MillasRequest, MillasResponse, ResponseDispatcher, RequestContext,
+  jsonify, view, redirect, text, send_file:file, empty,
+  abort, notFound, unauthorized, forbidden,
+  // ── Validation ────────────────────────────────────────────────
+  Validator,
+  BaseValidator,
+  StringValidator, EmailValidator, NumberValidator, BooleanValidator,
+  DateValidator, ArrayValidator, ObjectValidator, FileValidator,
+  string, email, number, boolean, date, array,
+  object: objectField,
+  file:   fileField,
   // HTTP
   Controller, Middleware, MiddlewarePipeline,
   CorsMiddleware, ThrottleMiddleware, LogMiddleware, HttpError,
   // DI
-  Container, Application, MillasApp, ServiceProvider, ProviderRegistry,
+  Container, Application, ServiceProvider, ProviderRegistry,
   // ORM
   Model, fields, QueryBuilder, DatabaseManager, SchemaBuilder,
   MigrationRunner, ModelInspector, DatabaseServiceProvider,

package/src/logger/internal.js

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * src/logger/internal.js
+ *
+ * MillasLog — the Millas framework's own internal logger.
+ *
+ * This is separate from the user-facing `Log` singleton. It is used by:
+ *   - ORM (queries, relation warnings, migration runner)
+ *   - Admin panel
+ *   - Queue worker
+ *   - Any other framework-internal code
+ *
+ * It always works — no provider, no config, no try/catch needed at call sites.
+ * It starts in a sensible default state (WARN+ to console) and is upgraded
+ * by LogServiceProvider once the app boots and config/logging.js is read.
+ *
+ * ── Usage inside framework code ────────────────────────────────────────────
+ *
+ *   const MillasLog = require('../logger/internal');
+ *
+ *   MillasLog.d('ORM', 'Running query', { table: 'users' });
+ *   MillasLog.w('ORM', 'Relation not defined', { model: 'Post', name: 'tags' });
+ *   MillasLog.e('Migration', 'Failed to run migration', error);
+ *
+ * ── Configuring from config/logging.js ─────────────────────────────────────
+ *
+ *   module.exports = {
+ *     // ... app channels ...
+ *
+ *     internal: {
+ *       level: 'debug',      // show all ORM/framework logs (default: 'warn')
+ *       format: 'pretty',    // pretty | simple | json
+ *     },
+ *   };
+ *
+ * ── Disabling internal logs entirely ───────────────────────────────────────
+ *
+ *   internal: false
+ *
+ * ── Writing to a separate file ─────────────────────────────────────────────
+ *
+ *   internal: {
+ *     level:  'debug',
+ *     channels: [
+ *       { driver: 'console', format: 'pretty', level: 'warn' },
+ *       { driver: 'file', format: 'simple', path: 'storage/logs', prefix: 'millas-internal', level: 'debug' },
+ *     ],
+ *   },
+ */
+
+const Logger          = require('./Logger');
+const { LEVELS }      = require('./levels');
+const ConsoleChannel  = require('./channels/ConsoleChannel');
+const PrettyFormatter = require('./formatters/PrettyFormatter');
+const { NullChannel } = require('./channels/index');
+
+// ── Create the MillasLog singleton ───────────────────────────────────────────
+
+const MillasLog = new Logger();
+
+// Default: WARN and above, pretty-formatted to console.
+// This means normal app runs are quiet — you only see warnings and errors
+// from the framework itself unless you opt in to lower levels.
+MillasLog.configure({
+  defaultTag: 'Millas',
+  minLevel:   LEVELS.WARN,
+  channel:    new ConsoleChannel({
+    formatter: new PrettyFormatter({
+      colour: process.stdout.isTTY !== false,
+    }),
+    minLevel: LEVELS.WARN,
+  }),
+});
+
+module.exports = MillasLog;

package/src/logger/patchConsole.js

@@ -0,0 +1,135 @@
+'use strict';
+
+const { LEVELS } = require('./levels');
+
+/**
+ * patchConsole(Log, defaultTag)
+ *
+ * Replaces the global console.* methods so that all console output
+ * in the app goes through the configured Log channels — same formatting,
+ * same level filtering, same file output.
+ *
+ * Safe: ConsoleChannel writes via process.stdout.write / process.stderr.write,
+ * never via console.*, so there is no recursion risk.
+ *
+ * Called once from LogServiceProvider.boot() when interceptConsole is enabled.
+ * Returns a restore() function that puts the originals back.
+ *
+ * Level mapping:
+ *   console.log   → Log.i  (INFO)
+ *   console.info  → Log.i  (INFO)
+ *   console.warn  → Log.w  (WARN)
+ *   console.error → Log.e  (ERROR)
+ *   console.debug → Log.d  (DEBUG)
+ *   console.trace → Log.v  (VERBOSE)
+ *   console.dir   → Log.d  (DEBUG)
+ */
+function patchConsole(Log, defaultTag = 'App') {
+  // Save originals — restore() puts these back
+  const originals = {
+    log:   console.log.bind(console),
+    info:  console.info.bind(console),
+    warn:  console.warn.bind(console),
+    error: console.error.bind(console),
+    debug: console.debug.bind(console),
+    trace: console.trace.bind(console),
+    dir:   console.dir.bind(console),
+  };
+
+  // Build a dispatcher for a given level
+  function make(level) {
+    return function (...args) {
+      const { message, context, error } = parse(args);
+      Log._emit({
+        level,
+        tag:       defaultTag,
+        message:   message || '',
+        context,
+        error,
+        timestamp: new Date().toISOString(),
+        pid:       process.pid,
+      });
+    };
+  }
+
+  console.log   = make(LEVELS.INFO);
+  console.info  = make(LEVELS.INFO);
+  console.warn  = make(LEVELS.WARN);
+  console.error = make(LEVELS.ERROR);
+  console.debug = make(LEVELS.DEBUG);
+  console.trace = make(LEVELS.VERBOSE);
+  console.dir   = (obj) => Log._emit({ level: LEVELS.DEBUG, tag: defaultTag, message: '', context: obj, error: undefined, timestamp: new Date().toISOString(), pid: process.pid });
+
+  return function restore() {
+    Object.assign(console, originals);
+  };
+}
+
+// ── Argument parser ───────────────────────────────────────────────────────────
+//
+// Handles the main shapes people pass to console.*:
+//
+//   console.log('message')
+//   console.log('message', { ctx })
+//   console.log('message', error)
+//   console.error(error)
+//   console.log({ obj })
+//   console.log('x:', 42)          → message: 'x: 42'
+//   console.log('a', 'b', 'c')     → message: 'a b c'
+
+function parse(args) {
+  if (args.length === 0) {
+    return { message: '', context: undefined, error: undefined };
+  }
+
+  if (args.length === 1) {
+    const a = args[0];
+    if (a instanceof Error)                      return { message: a.message,    context: undefined, error: a };
+    if (typeof a === 'object' && a !== null)     return { message: '',           context: a,         error: undefined };
+    return { message: String(a), context: undefined, error: undefined };
+  }
+
+  const [first, ...rest] = args;
+
+  // First arg is an Error
+  if (first instanceof Error) {
+    return { message: first.message, context: rest.length ? rest : undefined, error: first };
+  }
+
+  // First arg is a string message
+  if (typeof first === 'string') {
+    // Single extra arg
+    if (rest.length === 1) {
+      const r = rest[0];
+      if (r instanceof Error)                    return { message: first, context: undefined, error: r };
+      if (typeof r === 'object' && r !== null)   return { message: first, context: r,         error: undefined };
+      // Scalar extra: append to message (console.log('count:', 42))
+      return { message: first + ' ' + String(r), context: undefined, error: undefined };
+    }
+
+    // Multiple extra args — find a trailing Error, collect the rest as context
+    const lastArg = rest[rest.length - 1];
+    if (lastArg instanceof Error) {
+      const ctx = rest.slice(0, -1);
+      return { message: first, context: ctx.length ? ctx : undefined, error: lastArg };
+    }
+
+    // All strings/scalars — join into message
+    if (rest.every(r => typeof r !== 'object' || r === null)) {
+      return { message: [first, ...rest].map(String).join(' '), context: undefined, error: undefined };
+    }
+
+    // Mixed — put extras in context
+    return { message: first, context: rest, error: undefined };
+  }
+
+  // First arg is an object
+  if (typeof first === 'object' && first !== null) {
+    return { message: '', context: first, error: undefined };
+  }
+
+  // Fallback — join everything as a string
+  return { message: args.map(String).join(' '), context: undefined, error: undefined };
+}
+
+module.exports = patchConsole;

package/src/middleware/CorsMiddleware.js

@@ -1,58 +1,50 @@
 'use strict';
 
-const Middleware = require('./Middleware');
+const Middleware     = require('./Middleware');
+const MillasResponse = require('../http/MillasResponse');
 
 /**
  * CorsMiddleware
  *
- * Adds Cross-Origin Resource Sharing headers to every response.
- *
- * Register:
- *   middlewareRegistry.register('cors', CorsMiddleware);
- *
- * Configure in bootstrap/app.js:
- *   new CorsMiddleware({
- *     origins: ['https://myapp.com'],
- *     methods: ['GET', 'POST'],
- *   })
- *
- * Or register the class directly for default permissive settings.
+ * Adds CORS headers. Uses the new ctx signature.
  */
 class CorsMiddleware extends Middleware {
   constructor(options = {}) {
     super();
     this.origins     = options.origins     || ['*'];
-    this.methods     = options.methods     || ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'];
-    this.headers     = options.headers     || ['Content-Type', 'Authorization', 'X-Requested-With'];
+    this.methods     = options.methods     || ['GET','POST','PUT','PATCH','DELETE','OPTIONS'];
+    this.headers     = options.headers     || ['Content-Type','Authorization','X-Requested-With'];
     this.credentials = options.credentials ?? false;
     this.maxAge      = options.maxAge      || 86400;
   }
 
-  async handle(req, res, next) {
-    const origin = req.headers.origin;
+  async handle({ req }, next) {
+    const origin = req.header('origin');
 
-    // Origin matching
+    // Build headers map
+    const h = {};
     if (this.origins.includes('*')) {
-      res.setHeader('Access-Control-Allow-Origin', '*');
+      h['Access-Control-Allow-Origin'] = '*';
     } else if (origin && this.origins.includes(origin)) {
-      res.setHeader('Access-Control-Allow-Origin', origin);
-      res.setHeader('Vary', 'Origin');
+      h['Access-Control-Allow-Origin'] = origin;
+      h['Vary'] = 'Origin';
     }
-
-    res.setHeader('Access-Control-Allow-Methods', this.methods.join(', '));
-    res.setHeader('Access-Control-Allow-Headers', this.headers.join(', '));
-    res.setHeader('Access-Control-Max-Age', String(this.maxAge));
-
+    h['Access-Control-Allow-Methods']  = this.methods.join(', ');
+    h['Access-Control-Allow-Headers']  = this.headers.join(', ');
+    h['Access-Control-Max-Age']        = String(this.maxAge);
     if (this.credentials) {
-      res.setHeader('Access-Control-Allow-Credentials', 'true');
+      h['Access-Control-Allow-Credentials'] = 'true';
     }
 
-    // Handle preflight
+    // Preflight — short-circuit with 204
     if (req.method === 'OPTIONS') {
-      return res.status(204).send();
+      return MillasResponse.empty(204).withHeaders(h);
     }
 
-    next();
+    // Proceed — but we still need headers on the eventual response.
+    // Store on raw req so ResponseDispatcher can pick them up.
+    req.raw._corsHeaders = h;
+    return next();
   }
 }
 

package/src/middleware/LogMiddleware.js

@@ -5,31 +5,8 @@ const Middleware = require('./Middleware');
 /**
  * LogMiddleware
  *
- * Django-style HTTP request logger.
- * Uses the Millas Log singleton — output goes through your configured channels.
- *
- * Log levels per status:
- *   2xx, 3xx  → INFO   (green)
- *   4xx       → WARN   (yellow)
- *   5xx       → ERROR  (red)
- *   slow req  → WARN   (with slow=true in context)
- *
- * Output:
- *   I  HTTP  GET /api/users 200 4ms
- *   W  HTTP  POST /api/login 401 12ms
- *   E  HTTP  GET /api/crash 500 3ms
- *
- * Usage (register as middleware):
- *   app.use(new LogMiddleware().handle.bind(new LogMiddleware()));
- *
- * Or use Log.requestMiddleware() directly for more options.
- *
- * Options:
- *   silent        — suppress all output (default: false)
- *   includeQuery  — include query string in URL (default: false)
- *   includeIp     — include client IP (default: true)
- *   slowThreshold — warn if response > Nms (default: 1000)
- *   skip          — function(req, res) => bool — skip matching routes
+ * Django-style HTTP request logging via MillasLog.
+ * Uses the new ctx signature: handle({ req }, next)
  */
 class LogMiddleware extends Middleware {
   constructor(options = {}) {
@@ -41,46 +18,37 @@ class LogMiddleware extends Middleware {
     this.skip          = options.skip          ?? null;
   }
 
-  async handle(req, res, next) {
+  async handle({ req }, next) {
     if (this.silent) return next();
-    if (typeof this.skip === 'function' && this.skip(req, res)) return next();
-
-    // Lazy-require Log so this file loads even before LogServiceProvider runs
-    let Log;
-    try {
-      Log = require('../logger/index').Log;
-    } catch {
-      return next();
-    }
+    if (typeof this.skip === 'function' && this.skip(req)) return next();
 
     const start = Date.now();
-    const { LEVELS } = require('../logger/levels');
-
-    res.on('finish', () => {
-      const ms     = Date.now() - start;
-      const status = res.statusCode;
-      const method = req.method;
-      let   url    = req.path || req.url || '/';
-
-      if (this.includeQuery && req.url && req.url.includes('?')) {
-        url = req.url;
-      }
-
-      // Level based on status + response time
-      let level;
-      if      (status >= 500)          level = LEVELS.ERROR;
-      else if (status >= 400)          level = LEVELS.WARN;
-      else if (ms > this.slowThreshold) level = LEVELS.WARN;
-      else                             level = LEVELS.INFO;
-
-      const ctx = { status, ms };
-      if (this.includeIp) ctx.ip = req.ip || req.connection?.remoteAddress;
-      if (ms > this.slowThreshold) ctx.slow = true;
 
-      Log._log(level, 'HTTP', `${method} ${url} ${status} ${ms}ms`, ctx);
+    // We can't hook into the response here since next() returns undefined.
+    // Instead attach a finish listener to the raw Express res.
+    req.raw.res.on('finish', () => {
+      try {
+        const MillasLog = require('../logger/internal');
+        const { LEVELS } = require('../logger/levels');
+        const ms     = Date.now() - start;
+        const status = req.raw.res.statusCode;
+        let   url    = req.path;
+        if (this.includeQuery && req.raw.url?.includes('?')) url = req.raw.url;
+
+        let level = status >= 500 ? LEVELS.ERROR
+                  : status >= 400 ? LEVELS.WARN
+                  : ms > this.slowThreshold ? LEVELS.WARN
+                  : LEVELS.INFO;
+
+        const ctx = { status, ms };
+        if (this.includeIp) ctx.ip = req.ip;
+        if (ms > this.slowThreshold) ctx.slow = true;
+
+        MillasLog._log(level, 'HTTP', `${req.method} ${url} ${status} ${ms}ms`, ctx);
+      } catch {}
     });
 
-    next();
+    return next();
   }
 }
 

package/src/middleware/Middleware.js

@@ -4,33 +4,42 @@
  * Middleware
  *
  * Base class for all Millas middleware.
- * Subclasses must implement handle(req, res, next).
  *
- * Usage:
+ * Middleware receives a RequestContext and a next() function.
+ * Destructure exactly what you need from the context — same as route handlers.
+ *
  *   class AuthMiddleware extends Middleware {
- *     async handle(req, res, next) {
- *       // ...
- *       next();
+ *     async handle({ headers, user }, next) {
+ *       if (!headers.authorization) {
+ *         return jsonify({ error: 'Unauthorized' }, { status: 401 });
+ *       }
+ *       return next();
+ *     }
+ *   }
+ *
+ *   class LogMiddleware extends Middleware {
+ *     async handle({ req }, next) {
+ *       Log.i('HTTP', `${req.method} ${req.path}`);
+ *       return next();
  *     }
  *   }
  */
 class Middleware {
   /**
-   * Handle the incoming request.
-   *
-   * @param {import('express').Request}  req
-   * @param {import('express').Response} res
-   * @param {Function}                   next
+   * @param {import('../http/RequestContext')} ctx
+   * @param {Function} next
+   * @returns {import('../http/MillasResponse')|Promise<import('../http/MillasResponse')>}
    */
-  async handle(req, res, next) {
-    throw new Error(`${this.constructor.name} must implement handle(req, res, next)`);
+  async handle(ctx, next) {
+    throw new Error(`${this.constructor.name} must implement handle(ctx, next).`);
   }
 
   /**
-   * Called after the response is sent.
-   * Override for cleanup, logging, etc.
+   * Called after the response is dispatched.
+   * @param {import('../http/RequestContext')}  ctx
+   * @param {import('../http/MillasResponse')}  response
    */
-  async terminate(req, res) {}
+  async terminate(ctx, response) {}
 }
 
 module.exports = Middleware;

package/src/middleware/MiddlewarePipeline.js

@@ -1,93 +1,56 @@
 'use strict';
 
+const MillasRequest      = require('../http/MillasRequest');
+const RequestContext     = require('../http/RequestContext');
+const MillasResponse     = require('../http/MillasResponse');
+const ResponseDispatcher = require('../http/ResponseDispatcher');
+
 /**
  * MiddlewarePipeline
  *
- * Composes an ordered list of middleware handlers into a single
- * Express-compatible function. Used internally by the Router.
- *
- * Each handler can be:
- *   - A Middleware subclass (instantiated automatically)
- *   - An already-instantiated Middleware object
- *   - A raw Express function (req, res, next) => {}
+ * Runs an ordered list of middleware instances against a request.
+ * Used for programmatic pipelines outside of the router (e.g. queue webhooks).
  *
- * Usage (internal):
- *   const pipeline = new MiddlewarePipeline([AuthMiddleware, LogMiddleware]);
- *   app.use(pipeline.compose());
+ * Each middleware receives a RequestContext and a next() function.
  */
 class MiddlewarePipeline {
-  constructor(handlers = []) {
-    this._handlers = handlers;
-  }
-
-  /**
-   * Add a handler to the end of the pipeline.
-   */
-  pipe(handler) {
-    this._handlers.push(handler);
-    return this;
+  constructor(middlewares = []) {
+    this._middlewares = middlewares;
   }
 
-  /**
-   * Add a handler to the beginning of the pipeline.
-   */
-  prepend(handler) {
-    this._handlers.unshift(handler);
+  add(middleware) {
+    this._middlewares.push(middleware);
     return this;
   }
 
   /**
-   * Compose all handlers into a single (req, res, next) function.
+   * Run the pipeline against an Express req/res.
+   * @param {object} expressReq
+   * @param {object} expressRes
+   * @param {object|null} container
    */
-  compose() {
-    const fns = this._handlers.map(h => this._resolve(h));
+  async run(expressReq, expressRes, container = null) {
+    const millaReq = new MillasRequest(expressReq);
+    const ctx      = new RequestContext(millaReq, container);
 
-    return function pipeline(req, res, next) {
-      let index = 0;
+    const dispatch = async (index) => {
+      if (index >= this._middlewares.length) return null;
 
-      function dispatch(i) {
-        if (i >= fns.length) return next();
-        const fn = fns[i];
+      const mw   = this._middlewares[index];
+      const next = () => dispatch(index + 1);
 
-        try {
-          const result = fn(req, res, (err) => {
-            if (err) return next(err);
-            dispatch(i + 1);
-          });
-          // Handle async middleware that returns a Promise
-          if (result && typeof result.catch === 'function') {
-            result.catch(next);
-          }
-        } catch (err) {
-          next(err);
-        }
-      }
+      const instance = typeof mw === 'function' && mw.prototype?.handle
+        ? new mw()
+        : mw;
 
-      dispatch(0);
+      return instance.handle(ctx, next);
     };
-  }
-
-  /**
-   * Resolve a handler to a plain (req, res, next) => {} function.
-   */
-  _resolve(handler) {
-    // Raw Express function
-    if (typeof handler === 'function' && !(handler.prototype instanceof require('./Middleware'))) {
-      return handler;
-    }
 
-    // Middleware class (not yet instantiated)
-    if (typeof handler === 'function' && handler.prototype instanceof require('./Middleware')) {
-      const instance = new handler();
-      return (req, res, next) => instance.handle(req, res, next);
-    }
+    const response = await dispatch(0);
 
-    // Instantiated Middleware object
-    if (handler && typeof handler.handle === 'function') {
-      return (req, res, next) => handler.handle(req, res, next);
+    if (response && MillasResponse.isResponse(response) && !expressRes.headersSent) {
+      ResponseDispatcher.dispatch(response, expressRes);
     }
-
-    throw new Error(`Invalid middleware: ${handler}. Must be a Middleware class, instance, or function.`);
   }
 }