millas 0.2.12-beta-1 → 0.2.13

package/src/logger/formatters/JsonFormatter.js

@@ -1,12 +1,14 @@
 'use strict';
 
-const { LEVEL_NAMES } = require('../levels');
+const { LEVEL_NAMES }     = require('../levels');
+const { LogRedactor }     = require('../LogRedactor');
 
 /**
  * JsonFormatter
  *
  * Emits one JSON object per log entry — ideal for production environments
  * where logs are shipped to Datadog, Elasticsearch, CloudWatch, etc.
+ * Sensitive context fields are automatically redacted before serialisation.
  *
  * Output (one line per entry):
  *   {"ts":"2026-03-15T12:00:00.000Z","level":"INFO","tag":"Auth","msg":"Login","ctx":{...}}
@@ -15,11 +17,13 @@ class JsonFormatter {
   /**
    * @param {object} options
    * @param {boolean} [options.pretty=false]   — pretty-print JSON (for debugging)
-   * @param {object}  [options.extra]          — static fields merged into every entry (e.g. service name)
+   * @param {object}  [options.extra]          — static fields merged into every entry
+   * @param {boolean} [options.redact=true]    — redact sensitive context fields
    */
   constructor(options = {}) {
     this.pretty = options.pretty || false;
     this.extra  = options.extra  || {};
+    this.redact = options.redact !== false;   // default: true
   }
 
   format(entry) {
@@ -33,7 +37,10 @@ class JsonFormatter {
 
     if (tag)     record.tag = tag;
     record.msg = message;
-    if (context !== undefined && context !== null) record.ctx = context;
+
+    if (context !== undefined && context !== null) {
+      record.ctx = this.redact ? LogRedactor.redact(context) : context;
+    }
 
     if (error instanceof Error) {
       record.error = {
@@ -49,4 +56,4 @@ class JsonFormatter {
   }
 }
 
-module.exports = JsonFormatter;
+module.exports = JsonFormatter;

package/src/logger/formatters/PrettyFormatter.js

@@ -1,98 +1,136 @@
 'use strict';
 
-const { LEVEL_NAMES, LEVEL_TAGS, LEVEL_COLOURS, RESET, BOLD, DIM } = require('../levels');
-
-/**
- * PrettyFormatter
- *
- * Colourful, human-readable output. Designed for development.
- * Inspired by Timber (Android) and Laravel's log formatting.
- *
- * Output:
- *   [2026-03-15 12:00:00] I  UserController  User #5 logged in
- *   [2026-03-15 12:00:01] E  Database        Connection refused  { host: 'localhost' }
- *   [2026-03-15 12:00:02] W  Auth            Token expiring soon
- *
- * WTF level also prints the full stack trace.
- */
+const { LEVEL_TAGS, LEVEL_COLOURS, RESET, BOLD } = require('../levels');
+const { LogRedactor } = require('../LogRedactor');
+
+const SEP = '  ';
+const TAG_WIDTH = 18;
+
+// Matches /absolute/path/to/file.js or /absolute/path/to/file.js:12:34
+const FILE_PATH_RE = /(\/[^\s)'"]+\.(js|ts|json|mjs|cjs)(?::\d+(?::\d+)?)?)/g;
+// Matches http(s):// URLs
+const URL_RE = /(https?:\/\/[^\s)'"]+)/g;
+
+function linkify(text, dim, useColour) {
+  if (!useColour) return text;
+
+  text = text.replace(FILE_PATH_RE, (match) => {
+    const filePath = match.replace(/(:\d+)+$/, '');
+    const uri = `file://${filePath}`;
+    return `${RESET}\x1b]8;;${uri}\x1b\\${match}\x1b]8;;\x1b\\`;
+  });
+
+  text = text.replace(URL_RE, (match) => {
+    return `${RESET}\x1b]8;;${match}\x1b\\${match}\x1b]8;;\x1b\\`;
+  });
+
+  return text;
+}
+
 class PrettyFormatter {
-  /**
-   * @param {object} options
-   * @param {boolean} [options.timestamp=true]    — show timestamp
-   * @param {boolean} [options.tag=true]          — show tag/component name
-   * @param {boolean} [options.colour=true]       — ANSI colour (disable for pipes/files)
-   * @param {string}  [options.timestampFormat]   — 'iso' | 'short' (default: 'short')
-   */
   constructor(options = {}) {
     this.showTimestamp = options.timestamp !== false;
     this.showTag       = options.tag       !== false;
     this.colour        = options.colour    !== false;
     this.tsFormat      = options.timestampFormat || 'short';
+    this.tagWidth      = options.tagWidth || TAG_WIDTH;
   }
 
   format(entry) {
     const { level, tag, message, context, error } = entry;
 
-    const c    = this.colour ? LEVEL_COLOURS[level] : '';
-    const r    = this.colour ? RESET                : '';
-    const b    = this.colour ? BOLD                 : '';
-    const d    = this.colour ? '\x1b[2m'            : '';
-    const lvl  = LEVEL_TAGS[level] || '?';
+    const c   = this.colour ? (LEVEL_COLOURS[level] || '') : '';
+    const r   = this.colour ? RESET     : '';
+    const b   = this.colour ? BOLD      : '';
+    const d   = this.colour ? '\x1b[2m' : '';
+    const lvl = LEVEL_TAGS[level] || '?';
 
-    const parts = [];
+    // ── 1. Measure plain prefix once ─────────────────────────────────────────
+    const ts = this._timestamp();
+    const plainCols = [];
+    if (this.showTimestamp)    plainCols.push(`[${ts}]`);
+    plainCols.push(lvl);
+    if (this.showTag && tag)   plainCols.push(tag.padEnd(this.tagWidth));
 
-    // Timestamp
-    if (this.showTimestamp) {
-      const ts = this._timestamp();
-      parts.push(`${d}[${ts}]${r}`);
-    }
+    const indentWidth = plainCols.join(SEP).length + SEP.length;
+    const indent      = ' '.repeat(indentWidth);
 
-    // Level tag (single letter, coloured)
-    parts.push(`${c}${b}${lvl}${r}`);
+    // ── 2. Coloured prefix ───────────────────────────────────────────────────
+    const colCols = [];
+    if (this.showTimestamp)    colCols.push(`${d}[${ts}]${r}`);
+    colCols.push(`${c}${b}${lvl}${r}`);
+    if (this.showTag && tag)   colCols.push(`${b}${tag.padEnd(this.tagWidth)}${r}`);
 
-    // Component/tag
-    if (this.showTag && tag) {
-      const tagStr = tag.padEnd(18);
-      parts.push(`${b}${tagStr}${r}`);
-    }
+    const prefix = colCols.join(SEP) + SEP;
 
-    // Message (handle multi-line)
-    const lines = message.split('\n');
-    parts.push(`${c}${lines[0]}${r}`);
+    // ── 3. Terminal width ────────────────────────────────────────────────────
+    const termWidth = (process.stdout.columns || 120);
+    const msgWidth  = termWidth - indentWidth;
 
-    let output = parts.join('  ');
+    // ── 4. Collect all logical lines ─────────────────────────────────────────
+    const logicalLines = [];
 
-    // Continuation lines (aligned with first line)
-    if (lines.length > 1) {
-      const prefix = parts.slice(0, -1).map(p => p.replace(/\x1b\[[0-9;]*m/g, '')).join('  ');
-      const indent = ' '.repeat(prefix.length + 2);
-      for (let i = 1; i < lines.length; i++) {
-        output += `\n${indent}${c}${lines[i]}${r}`;
-      }
-    }
+    for (const l of String(message).split('\n')) logicalLines.push({ text: l, dim: false });
 
-    // Context object
-    if (context !== undefined && context !== null) {
-      const ctx = typeof context === 'object'
-        ? JSON.stringify(context, null, 0)
-        : String(context);
-      output += `  ${d}${ctx}${r}`;
+    if (context != null) {
+      const safe = this.redact !== false ? LogRedactor.redact(context) : context;
+      const ctx  = typeof safe === 'object' ? JSON.stringify(safe) : String(safe);
+      logicalLines.push({ text: ctx, dim: true });
     }
 
-    // Error stack
     if (error instanceof Error) {
-      output += `\n${d}${error.stack || error.message}${r}`;
+      for (const l of (error.stack || error.message).split('\n'))
+        logicalLines.push({ text: l, dim: true });
+    }
+
+    // ── 5. Hard-wrap (skip stack frames so paths stay intact) ────────────────
+    const wrappedLines = [];
+
+    for (const { text, dim } of logicalLines) {
+      const isStackFrame = dim && /^\s*at /.test(text);
+
+      if (isStackFrame || text.length <= msgWidth) {
+        wrappedLines.push({ text, dim });
+        continue;
+      }
+
+      const words = text.split(' ');
+      let chunk = '';
+      for (const word of words) {
+        if (chunk.length === 0) {
+          if (word.length > msgWidth) {
+            for (let i = 0; i < word.length; i += msgWidth)
+              wrappedLines.push({ text: word.slice(i, i + msgWidth), dim });
+          } else {
+            chunk = word;
+          }
+        } else if (chunk.length + 1 + word.length <= msgWidth) {
+          chunk += ' ' + word;
+        } else {
+          wrappedLines.push({ text: chunk, dim });
+          chunk = word;
+        }
+      }
+      if (chunk.length) wrappedLines.push({ text: chunk, dim });
     }
 
-    // WTF: print big warning banner
+    // ── 6. Render + linkify ───────────────────────────────────────────────────
+    const rendered = wrappedLines.map((line, i) => {
+      const col  = line.dim ? d : c;
+      const text = linkify(line.text, line.dim, this.colour);
+      if (i === 0) return `${prefix}${col}${text}${r}`;
+      return `${indent}${col}${text}${r}`;
+    }).join('\n');
+
+    // ── 7. WTF banner ─────────────────────────────────────────────────────────
     if (level === 5) {
-      const banner = this.colour
+      const bar = this.colour
         ? `\x1b[35m\x1b[1m${'━'.repeat(60)}\x1b[0m`
         : '━'.repeat(60);
-      output = `${banner}\n${output}\n${banner}`;
+      return `${bar}\n${rendered}\n${bar}`;
     }
 
-    return output;
+    return rendered;
   }
 
   _timestamp() {
@@ -102,4 +140,4 @@ class PrettyFormatter {
   }
 }
 
-module.exports = PrettyFormatter;
+module.exports = PrettyFormatter;

package/src/logger/formatters/SimpleFormatter.js

@@ -1,18 +1,28 @@
 'use strict';
 
 const { LEVEL_NAMES } = require('../levels');
+const { LogRedactor } = require('../LogRedactor');
 
 /**
  * SimpleFormatter
  *
  * Plain, no-colour text. Suitable for file output or any sink
- * where ANSI codes would be noise.
+ * where ANSI codes would be noise. Sensitive context fields are
+ * automatically redacted before serialisation.
  *
  * Output:
  *   [2026-03-15 12:00:00] [INFO]  Auth: User logged in
  *   [2026-03-15 12:00:01] [ERROR] DB: Query failed {"table":"users"}
  */
 class SimpleFormatter {
+  /**
+   * @param {object} [options]
+   * @param {boolean} [options.redact=true]  — redact sensitive context fields
+   */
+  constructor(options = {}) {
+    this.redact = options.redact !== false;
+  }
+
   format(entry) {
     const { level, tag, message, context, error, timestamp } = entry;
 
@@ -23,7 +33,8 @@ class SimpleFormatter {
     let line = `[${ts}] [${lvlName}] ${tagPart}${message}`;
 
     if (context !== undefined && context !== null) {
-      line += ' ' + (typeof context === 'object' ? JSON.stringify(context) : String(context));
+      const safe = this.redact ? LogRedactor.redact(context) : context;
+      line += ' ' + (typeof safe === 'object' ? JSON.stringify(safe) : String(safe));
     }
 
     if (error instanceof Error) {
@@ -34,4 +45,4 @@ class SimpleFormatter {
   }
 }
 
-module.exports = SimpleFormatter;
+module.exports = SimpleFormatter;

package/src/middleware/ThrottleMiddleware.js

@@ -7,18 +7,41 @@ const { jsonify }    = require('../http/helpers');
 /**
  * ThrottleMiddleware
  *
- * Simple in-memory rate limiter.
- * Uses the Millas middleware signature: handle(req, next).
+ * Per-IP (or per-user) rate limiter registered as the 'throttle' middleware alias.
+ * Used via the route middleware system — developers never import this directly.
+ *
+ * Usage in routes:
+ *   Route.middleware('throttle:5,10').group(() => {    // 5 req per 10 min
+ *     Route.post('/login', AuthController, 'login');
+ *   });
+ *
+ *   Route.post('/login', AuthController, 'login')     // same, single route
+ *     — add 'throttle:5,10' to route middleware array
+ *
+ * Format: 'throttle:<max>,<minutes>'
+ *   throttle:60,1   — 60 requests per minute
+ *   throttle:5,10   — 5 requests per 10 minutes
+ *   throttle:100,15 — 100 requests per 15 minutes
  */
 class ThrottleMiddleware extends Middleware {
   constructor(options = {}) {
     super();
     this.max    = options.max    || 60;
-    this.window = options.window || 60;
+    this.window = options.window || 60;   // seconds
     this.keyBy  = options.keyBy  || ((req) => req.ip || 'anonymous');
     this._store = new Map();
   }
 
+  /**
+   * Factory used by MiddlewareRegistry when parsing 'throttle:max,minutes'.
+   * @param {string[]} params  — ['5', '10'] from 'throttle:5,10'
+   */
+  static fromParams(params) {
+    const max     = parseInt(params[0], 10) || 60;
+    const minutes = parseInt(params[1], 10) || 1;
+    return new ThrottleMiddleware({ max, window: minutes * 60 });
+  }
+
   async handle(req, next) {
     const key    = this.keyBy(req);
     const now    = Date.now();
@@ -54,4 +77,4 @@ class ThrottleMiddleware extends Middleware {
   }
 }
 
-module.exports = ThrottleMiddleware;
+module.exports = ThrottleMiddleware;

package/src/migrations/system/0001_users.js

@@ -0,0 +1,21 @@
+'use strict';
+
+/**
+ * System migration: 0001_users
+ *
+ * Previously created the users table directly.
+ *
+ * As of Millas 0.3+, the users table is owned by the APP — not the framework.
+ * AuthUser is now fully abstract (no table). The app defines its own User model
+ * that extends AuthUser and owns whatever table it wants (typically 'users').
+ *
+ * This migration is kept as a no-op so existing projects that depend on
+ * ['system', '0001_users'] don't break. It creates nothing.
+ *
+ * Equivalent to Django's pattern: AbstractUser has no table; your custom
+ * User model creates its own table via app migrations.
+ */
+module.exports = {
+  dependencies: [],
+  operations:   [],
+};

package/src/migrations/system/0002_admin_log.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const { CreateModel } = require('../../orm/migration/operations');
+
+/**
+ * System migration: millas_admin_log
+ * Equivalent to Django's django_admin_log.
+ */
+module.exports = {
+  dependencies: [['system', '0001_users']],
+
+  operations: [
+    new CreateModel('millas_admin_log', {
+      id:         { type: 'id',        unsigned: true,  nullable: false, unique: false, default: null, max: null, enumValues: null, references: null, precision: null, scale: null },
+      user_id:    { type: 'integer',   unsigned: true,  nullable: true,  unique: false, default: null, max: null, enumValues: null, references: { table: 'users', column: 'id', onDelete: 'SET NULL' }, precision: null, scale: null },
+      user_email: { type: 'string',    max: 255,        nullable: true,  unique: false, default: null, unsigned: false, enumValues: null, references: null, precision: null, scale: null },
+      resource:   { type: 'string',    max: 100,        nullable: false, unique: false, default: null, unsigned: false, enumValues: null, references: null, precision: null, scale: null },
+      record_id:  { type: 'string',    max: 100,        nullable: true,  unique: false, default: null, unsigned: false, enumValues: null, references: null, precision: null, scale: null },
+      action:     { type: 'enum',      enumValues: ['create','update','delete'], nullable: false, unique: false, default: null, max: null, unsigned: false, references: null, precision: null, scale: null },
+      label:      { type: 'string',    max: 255,        nullable: true,  unique: false, default: null, unsigned: false, enumValues: null, references: null, precision: null, scale: null },
+      change_msg: { type: 'text',      nullable: true,  unique: false, default: null, max: null, unsigned: false, enumValues: null, references: null, precision: null, scale: null },
+      created_at: { type: 'timestamp', nullable: true,  unique: false, default: null, max: null, unsigned: false, enumValues: null, references: null, precision: null, scale: null },
+    }),
+  ],
+};

package/src/migrations/system/0003_sessions.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const { CreateModel } = require('../../orm/migration/operations');
+
+/**
+ * System migration: millas_sessions
+ * Equivalent to Django's django_session.
+ */
+module.exports = {
+  dependencies: [['system', '0001_users']],
+
+  operations: [
+    new CreateModel('millas_sessions', {
+      session_key: { type: 'string',    max: 64,  nullable: false, unique: false, default: null, unsigned: false, enumValues: null, references: null, precision: null, scale: null },
+      user_id:     { type: 'integer',   unsigned: true, nullable: false, unique: false, default: null, max: null, enumValues: null, references: { table: 'users', column: 'id', onDelete: 'CASCADE' }, precision: null, scale: null },
+      payload:     { type: 'text',      nullable: true,  unique: false, default: null, max: null, unsigned: false, enumValues: null, references: null, precision: null, scale: null },
+      ip_address:  { type: 'string',    max: 45,  nullable: true,  unique: false, default: null, unsigned: false, enumValues: null, references: null, precision: null, scale: null },
+      user_agent:  { type: 'string',    max: 512, nullable: true,  unique: false, default: null, unsigned: false, enumValues: null, references: null, precision: null, scale: null },
+      expires_at:  { type: 'timestamp', nullable: false, unique: false, default: null, max: null, unsigned: false, enumValues: null, references: null, precision: null, scale: null },
+      created_at:  { type: 'timestamp', nullable: true,  unique: false, default: null, max: null, unsigned: false, enumValues: null, references: null, precision: null, scale: null },
+    }),
+  ],
+};