millas 0.2.23 → 0.2.25

package/src/facades/Database.js

@@ -1,64 +1,53 @@
 'use strict';
 
-const Facade = require('./Facade');
+const { createFacade } = require('./Facade');
 
 /**
- * Database facade — direct access to the knex connection.
+ * Database facade — Laravel-style DB access.
  *
  * Usage:
+ *   const { Database } = require('millas');
+ *   // or
  *   const Database = require('millas/facades/Database');
  *
  *   // Raw SQL
- *   const result = await Database.raw('SELECT NOW()');
+ *   const users = await Database.select('SELECT * FROM users WHERE id = ?', [1]);
+ *   await Database.insert('INSERT INTO users (name, email) VALUES (?, ?)', ['John', 'john@example.com']);
+ *   await Database.update('UPDATE users SET name = ? WHERE id = ?', ['Jane', 1]);
+ *   await Database.delete('DELETE FROM users WHERE id = ?', [1]);
  *
- *   // Knex query builder
- *   const rows = await Database.table('posts').where('published', true).select('*');
+ *   // Query Builder (most common)
+ *   const users = await Database.table('users').get();
+ *   const user = await Database.table('users').where('id', 1).first();
+ *   await Database.table('users').insert({ name: 'John', email: 'john@example.com' });
+ *   await Database.table('users').where('id', 1).update({ name: 'Jane' });
+ *   await Database.table('users').where('id', 1).delete();
  *
- *   // Named connection
- *   const rows = await Database.connection('replica').raw('SELECT 1');
+ *   // Transactions
+ *   await Database.transaction(async (trx) => {
+ *     await trx.table('accounts').update({ balance: 100 });
+ *     await trx.table('transactions').insert({ amount: 100 });
+ *   });
+ *
+ *   // Multiple connections
+ *   await Database.connection('mysql').table('users').get();
+ *
+ *   // Raw expressions
+ *   await Database.table('users').select(Database.raw('COUNT(*) as total')).first();
+ *
+ * @class
+ * @property {function(string): *}                    table       - Query builder for a table
+ * @property {function(string, array=): Promise<*>}   raw         - Execute raw SQL
+ * @property {function(string, array=): Promise<*>}   select      - SELECT query
+ * @property {function(string, array=): Promise<*>}   insert      - INSERT query
+ * @property {function(string, array=): Promise<*>}   update      - UPDATE query
+ * @property {function(string, array=): Promise<*>}   delete      - DELETE query
+ * @property {function(function): Promise<*>}         transaction - Run queries in transaction
+ * @property {function(string=): *}                   connection  - Get named connection
+ *
+ * @see src/orm/drivers/DatabaseManager.js
  */
-class Database {
-  static _resolveInstance() {
-    const DatabaseManager = require('../orm/drivers/DatabaseManager');
-    return DatabaseManager.connection();
-  }
+class Database extends createFacade('db') {
 }
 
-// Proxy every static call to the knex connection
-module.exports = new Proxy(Database, {
-  get(target, prop) {
-    // Let real static members through
-    if (prop in target || prop === 'then' || prop === 'catch') {
-      return target[prop];
-    }
-    if (typeof prop === 'symbol') return target[prop];
-
-    // Special case: raw() — normalize result across dialects
-    if (prop === 'raw') {
-      return async (sql, bindings) => {
-        const db = Database._resolveInstance();
-        const result = await db.raw(sql, bindings);
-        // Postgres returns { rows: [...], command, rowCount, ... }
-        // SQLite/MySQL return [rows, fields] or just rows
-        if (result && result.rows) return result.rows;
-        if (Array.isArray(result)) return result[0] ?? result;
-        return result;
-      };
-    }
-
-    // Special case: connection(name) returns a named knex instance
-    if (prop === 'connection') {
-      return (name) => {
-        const DatabaseManager = require('../orm/drivers/DatabaseManager');
-        return DatabaseManager.connection(name || null);
-      };
-    }
-
-    // Proxy everything else to the default knex connection
-    return (...args) => {
-      const db = Database._resolveInstance();
-      if (typeof db[prop] !== 'function') return db[prop];
-      return db[prop](...args);
-    };
-  },
-});
+module.exports = Database;

package/src/facades/Schedule.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const Facade = require('./Facade');
+
+/**
+ * Schedule Facade
+ *
+ * Provides easy access to the task scheduler for defining scheduled tasks.
+ *
+ * Usage:
+ *   const { Schedule } = require('millas/facades');
+ *   
+ *   Schedule.job(SendEmailJob).daily().at('09:00');
+ *   Schedule.job(CleanupJob).hourly();
+ */
+class Schedule extends Facade {
+  static getAccessor() {
+    return 'scheduler';
+  }
+}
+
+module.exports = Schedule;

package/src/http/SecurityBootstrap.js

@@ -1,12 +1,21 @@
 'use strict';
 
-const SecurityHeaders  = require('./middleware/SecurityHeaders');
-const CsrfMiddleware   = require('./middleware/CsrfMiddleware');
-const { RateLimiter }  = require('./middleware/RateLimiter');
-const MillasResponse   = require('./MillasResponse');
+const SecurityHeaders      = require('./middleware/SecurityHeaders');
+const CsrfMiddleware       = require('./middleware/CsrfMiddleware');
+const { RateLimiter }      = require('./middleware/RateLimiter');
+const AllowedHostsMiddleware = require('./middleware/AllowedHostsMiddleware');
+const MillasResponse       = require('./MillasResponse');
 
 class SecurityBootstrap {
   static apply(app, config = {}) {
+    // ── ALLOWED_HOSTS (Django-style) ──────────────────────────────────────────
+    // Must be first — reject invalid hosts before any other processing
+    const allowedHostsMiddleware = AllowedHostsMiddleware.from({
+      allowedHosts: config.allowedHosts,
+      env: config.env || process.env.APP_ENV || 'production',
+    });
+    app.use(allowedHostsMiddleware.middleware());
+
     const headerConfig = config.headers !== undefined ? config.headers : {};
     app.use(SecurityHeaders.from(headerConfig).middleware());
 
@@ -48,6 +57,7 @@ class SecurityBootstrap {
 
     if (process.env.MILLAS_DEBUG_SECURITY === 'true') {
       console.log('[Millas Security] Controls applied:');
+      console.log('  ✓ Allowed hosts:    ', config.allowedHosts === false ? 'DISABLED' : (config.allowedHosts || 'development defaults'));
       console.log('  ✓ Security headers:  ', headerConfig === false ? 'DISABLED' : 'enabled');
       console.log('  ✓ Cookie defaults:   ', JSON.stringify(MillasResponse.getCookieDefaults()));
       console.log('  ✓ Global rate limit: ', globalRateLimit ? `${config.rateLimit?.global?.max || 100} req/window` : 'disabled');
@@ -69,6 +79,7 @@ class SecurityBootstrap {
       if (err.code === 'EVALIDATION' || err.name === 'ValidationError') {
         return res.status(422).json({ message: 'Validation failed', errors: err.errors || {} });
       }
+      // Pass all other errors (including EINVALIDHOST) to the main error handler
       next(err);
     });
   }

package/src/http/middleware/AllowedHostsMiddleware.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * AllowedHostsMiddleware
+ *
+ * Django-style ALLOWED_HOSTS protection.
+ * Validates the Host header against a whitelist to prevent Host header attacks.
+ *
+ * Usage in config/app.js:
+ *   module.exports = {
+ *     allowedHosts: ['example.com', 'www.example.com', 'localhost', '127.0.0.1'],
+ *     // or use wildcard:
+ *     allowedHosts: ['*.example.com', 'localhost'],
+ *   };
+ *
+ * Default behavior:
+ *   - Development (APP_ENV=development): allows localhost, 127.0.0.1, and any host
+ *   - Production: requires explicit allowedHosts configuration
+ */
+class AllowedHostsMiddleware {
+  constructor(config = {}) {
+    this._allowedHosts = config.allowedHosts;
+    this._env = config.env || 'production';
+    
+    // In development, allow localhost and 127.0.0.1 by default
+    if (this._allowedHosts === undefined) {
+      this._allowedHosts = this._env === 'development' 
+        ? ['localhost', '127.0.0.1', '[::1]']
+        : [];
+    }
+  }
+
+  /**
+   * Check if a host is allowed
+   */
+  _isAllowed(host) {
+    if (!host) return false;
+    
+    // Remove port from host
+    const hostname = host.split(':')[0];
+    
+    // Check exact match
+    if (this._allowedHosts.includes(hostname)) {
+      return true;
+    }
+    
+    // Check wildcard match (*.example.com)
+    for (const allowed of this._allowedHosts) {
+      if (allowed.startsWith('*.')) {
+        const domain = allowed.slice(2);
+        if (hostname.endsWith('.' + domain) || hostname === domain) {
+          return true;
+        }
+      }
+    }
+    
+    return false;
+  }
+
+  /**
+   * Express middleware
+   */
+  middleware() {
+    return (req, res, next) => {
+      const host = req.get('host');
+      
+      if (!this._isAllowed(host)) {
+        const hostname = host.split(':')[0];
+        const message = `Invalid HTTP_HOST header: "${host}". You may need to add "${hostname}" to allowedHosts.`;
+        
+        const error = new Error(message);
+        error.status = 400;
+        error.statusCode = 400;
+        error.code = 'EINVALIDHOST';
+        error._forceDebug = true;
+        error._hostDetails = {
+          receivedHost: host,
+          allowedHosts: this._allowedHosts,
+          environment: this._env,
+          suggestion: `Add "${hostname}" to the allowedHosts array in config/app.js`
+        };
+        return next(error);
+      }
+      
+      next();
+    };
+  }
+
+  /**
+   * Static factory
+   */
+  static from(config) {
+    return new AllowedHostsMiddleware(config || {});
+  }
+}
+
+module.exports = AllowedHostsMiddleware;

package/src/logger/formatters/JsonFormatter.js

@@ -30,7 +30,7 @@ class JsonFormatter {
     const { level, tag, message, context, error, timestamp } = entry;
 
     const record = {
-      ts:    timestamp || new Date().toISOString(),
+      ts:    timestamp instanceof Date ? timestamp.toISOString() : (timestamp || new Date().toISOString()),
       level: LEVEL_NAMES[level] || String(level),
       ...this.extra,
     };

package/src/logger/formatters/PrettyFormatter.js

@@ -135,8 +135,9 @@ class PrettyFormatter {
 
   _timestamp() {
     const now = new Date();
-    if (this.tsFormat === 'iso') return now.toISOString();
-    return now.toISOString().replace('T', ' ').slice(0, 19);
+    const isoStr = now.toISOString();
+    if (this.tsFormat === 'iso') return isoStr;
+    return isoStr.replace('T', ' ').slice(0, 19);
   }
 }
 

package/src/logger/formatters/SimpleFormatter.js

@@ -26,7 +26,8 @@ class SimpleFormatter {
   format(entry) {
     const { level, tag, message, context, error, timestamp } = entry;
 
-    const ts      = (timestamp || new Date().toISOString()).replace('T', ' ').slice(0, 23);
+    const isoStr  = timestamp instanceof Date ? timestamp.toISOString() : (timestamp || new Date().toISOString());
+    const ts      = isoStr.replace('T', ' ').slice(0, 23);
     const lvlName = (LEVEL_NAMES[level] || String(level)).padEnd(7);
     const tagPart = tag ? `${tag}: ` : '';
 

package/src/migrations/system/0004_scheduler_locks.js

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * System Migration: Scheduler Locks
+ *
+ * Creates the scheduler_locks table for distributed locking.
+ * Prevents duplicate task execution across multiple app instances.
+ *
+ * This is a system migration - it runs automatically when you run `millas migrate`.
+ */
+
+module.exports = {
+  async up(db) {
+    await db.schema.createTable('scheduler_locks', (table) => {
+      table.string('task_id', 255).primary();
+      table.timestamp('locked_at').notNullable();
+      table.timestamp('expires_at').notNullable();
+      table.integer('instance_id').notNullable();
+      
+      // Index for cleanup queries
+      table.index('expires_at', 'idx_scheduler_locks_expires');
+    });
+
+    console.log('  ✓ Created scheduler_locks table');
+  },
+
+  async down(db) {
+    await db.schema.dropTableIfExists('scheduler_locks');
+    console.log('  ✓ Dropped scheduler_locks table');
+  },
+};

package/src/orm/drivers/DatabaseManager.js

@@ -51,6 +51,88 @@ class DatabaseManager {
     return this.connection();
   }
 
+  /**
+   * Query builder for a table (Laravel: DB::table('users'))
+   */
+  table(tableName) {
+    return this.db(tableName);
+  }
+
+  /**
+   * Execute raw SQL SELECT (Laravel: DB::select())
+   */
+  async select(sql, bindings = []) {
+    const result = await this.db.raw(sql, bindings);
+    // Normalize across dialects
+    if (result && result.rows) return result.rows;
+    if (Array.isArray(result)) return result[0] ?? result;
+    return result;
+  }
+
+  /**
+   * Execute INSERT (Laravel: DB::insert())
+   */
+  async insert(sql, bindings = []) {
+    return this.db.raw(sql, bindings);
+  }
+
+  /**
+   * Execute UPDATE (Laravel: DB::update())
+   */
+  async update(sql, bindings = []) {
+    return this.db.raw(sql, bindings);
+  }
+
+  /**
+   * Execute DELETE (Laravel: DB::delete())
+   */
+  async delete(sql, bindings = []) {
+    return this.db.raw(sql, bindings);
+  }
+
+  /**
+   * Execute raw SQL (Laravel: DB::raw())
+   */
+  async raw(sql, bindings = []) {
+    return this.db.raw(sql, bindings);
+  }
+
+  /**
+   * Run queries in a transaction (Laravel: DB::transaction())
+   */
+  async transaction(callback) {
+    return this.db.transaction(callback);
+  }
+
+  /**
+   * Begin a transaction manually (Laravel: DB::beginTransaction())
+   */
+  async beginTransaction() {
+    const trx = await this.db.transaction();
+    return trx;
+  }
+
+  /**
+   * Execute a statement (Laravel: DB::statement())
+   */
+  async statement(sql, bindings = []) {
+    return this.db.raw(sql, bindings);
+  }
+
+  /**
+   * Execute unprepared statement (Laravel: DB::unprepared())
+   */
+  async unprepared(sql) {
+    return this.db.raw(sql);
+  }
+
+  /**
+   * Get schema builder (Laravel: DB::getSchemaBuilder())
+   */
+  get schema() {
+    return this.db.schema;
+  }
+
   /**
    * Close all connections.
    */
@@ -124,7 +206,21 @@ class DatabaseManager {
             'Run: npm install pg'
           );
         }
-        return knex({
+        
+        // Configure pg to parse timestamps as UTC
+        const types = require('pg').types;
+        const TIMESTAMP_OID = 1114; // timestamp without timezone
+        const TIMESTAMPTZ_OID = 1184; // timestamp with timezone
+        
+        // Override pg's default timestamp parser to always return UTC
+        types.setTypeParser(TIMESTAMP_OID, (val) => {
+          return val === null ? null : new Date(val + 'Z'); // Treat as UTC
+        });
+        types.setTypeParser(TIMESTAMPTZ_OID, (val) => {
+          return val === null ? null : new Date(val); // Already has timezone
+        });
+        
+        const pgConnection = knex({
           client:     'pg',
           connection: {
             host:     conf.host,
@@ -133,8 +229,15 @@ class DatabaseManager {
             user:     conf.username,
             password: conf.password,
           },
-          pool: { min: 2, max: 10 },
+          pool: { 
+            min: 2, 
+            max: 10,
+            afterCreate: (conn, done) => {
+              conn.query('SET timezone = "UTC";', (err) => done(err, conn));
+            },
+          },
         });
+        return pgConnection;
 
       default:
         throw new Error(`Unsupported database driver: "${conf.driver}"`);

package/src/orm/model/Model.js

@@ -967,6 +967,15 @@ class Model {
           const d = new Date(val.valueOf?.() ?? val);
           return isNaN(d.getTime()) ? null : d;
         }
+        // Django-style USE_TZ: if enabled, treat naive DB timestamps as UTC
+        if (this._isUseTzEnabled()) {
+          // Parse as UTC by appending 'Z' if no timezone info present
+          const str = String(val);
+          if (!str.includes('Z') && !str.includes('+') && !str.includes('-', 10)) {
+            const d = new Date(str + 'Z');
+            return isNaN(d.getTime()) ? null : d;
+          }
+        }
         const d = new Date(val);
         return isNaN(d.getTime()) ? null : d;
       }
@@ -1038,6 +1047,15 @@ class Model {
     } catch { return false; }
   }
 
+  static _isUseTzEnabled() {
+    try {
+      const appConfig = require(process.cwd() + '/config/app.js');
+      return appConfig.useTz !== false; // Default to true (Django-style)
+    } catch {
+      return true;
+    }
+  }
+
   /**
    * Insert a row and return the inserted primary key — dialect-aware.
    * SQLite: insert returns [lastId]

package/src/orm/query/QueryBuilder.js

@@ -274,6 +274,21 @@ class QueryBuilder {
     return this;
   }
 
+  joinRaw(sql, bindings = []) {
+    this._query = this._query.joinRaw(sql, bindings);
+    return this;
+  }
+
+  leftJoinRaw(sql, bindings = []) {
+    this._query = this._query.leftJoinRaw(sql, bindings);
+    return this;
+  }
+
+  crossJoin(table) {
+    this._query = this._query.crossJoin(table);
+    return this;
+  }
+
   having(column, operatorOrValue, value) {
     if (value !== undefined) {
       this._query = this._query.having(column, operatorOrValue, value);

package/src/providers/DatabaseServiceProvider.js

@@ -15,8 +15,8 @@ const SchemaBuilder   = require('../orm/migration/SchemaBuilder');
  */
 class DatabaseServiceProvider extends ServiceProvider {
   register(container) {
-    // Make DatabaseManager available as a singleton in the container
-    container.instance('db',              DatabaseManager);
+    // Register DatabaseManager singleton (provides Laravel-style DB methods)
+    container.instance('db', DatabaseManager);
     container.instance('DatabaseManager', DatabaseManager);
   }
 

package/src/scheduler/SchedulerLock.js

@@ -0,0 +1,93 @@
+'use strict';
+
+/**
+ * SchedulerLock
+ *
+ * Distributed locking mechanism to prevent duplicate task execution
+ * across multiple app instances (PM2 cluster, Docker replicas, etc.)
+ *
+ * Uses database-based locks with automatic expiration.
+ * The scheduler_locks table is created automatically by system migration 0004.
+ */
+class SchedulerLock {
+  constructor(db) {
+    this._db = db;
+    this._tableName = 'scheduler_locks';
+  }
+
+  /**
+   * Try to acquire a lock for a specific task
+   * Returns true if lock acquired, false if another instance has it
+   */
+  async acquire(taskId, ttlSeconds = 300) {
+    if (!this._db) return true; // No DB = no locking (single instance mode)
+
+    const db = this._db.db || this._db;
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + ttlSeconds * 1000);
+
+    try {
+      // Try to insert or update lock (upsert)
+      const result = await db.raw(`
+        INSERT INTO ${this._tableName} (task_id, locked_at, expires_at, instance_id)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT (task_id) DO UPDATE
+        SET locked_at = EXCLUDED.locked_at,
+            expires_at = EXCLUDED.expires_at,
+            instance_id = EXCLUDED.instance_id
+        WHERE ${this._tableName}.expires_at < ?
+        RETURNING instance_id
+      `, [taskId, now, expiresAt, process.pid, now]);
+
+      // Check if we got the lock (our PID is in the result)
+      if (result.rows && result.rows.length > 0) {
+        return result.rows[0].instance_id === process.pid;
+      }
+
+      // If no rows returned, lock is held by another instance
+      return false;
+
+    } catch (error) {
+      console.error('[SchedulerLock] Failed to acquire lock:', error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Release a lock
+   */
+  async release(taskId) {
+    if (!this._db) return;
+
+    const db = this._db.db || this._db;
+
+    try {
+      await db.raw(`
+        DELETE FROM ${this._tableName}
+        WHERE task_id = ? AND instance_id = ?
+      `, [taskId, process.pid]);
+    } catch (error) {
+      console.error('[SchedulerLock] Failed to release lock:', error.message);
+    }
+  }
+
+  /**
+   * Clean up expired locks
+   */
+  async cleanup() {
+    if (!this._db) return;
+
+    const db = this._db.db || this._db;
+
+    try {
+      await db.raw(`
+        DELETE FROM ${this._tableName}
+        WHERE expires_at < ?
+      `, [new Date()]);
+    } catch (error) {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+module.exports = SchedulerLock;

package/src/scheduler/SchedulerServiceProvider.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const ServiceProvider = require('../providers/ServiceProvider');
+const TaskScheduler = require('./TaskScheduler');
+
+/**
+ * SchedulerServiceProvider
+ *
+ * Registers the task scheduler in the DI container and starts it automatically.
+ * Integrates with the existing queue system and provides graceful shutdown.
+ */
+class SchedulerServiceProvider extends ServiceProvider {
+  register(container) {
+    container.singleton('scheduler', () => {
+      const queue = container.has('queue') ? container.make('queue') : null;
+      return new TaskScheduler(container, queue);
+    });
+  }
+
+  async boot(container, app) {
+    const scheduler = container.make('scheduler');
+    
+    // Load configuration
+    const config = this._loadConfig(container);
+    scheduler.configure(config);
+
+    // Load scheduled tasks from routes/schedule.js
+    const basePath = container.make('basePath');
+    const schedulePath = require('path').join(basePath, 'routes', 'schedule.js');
+    scheduler.loadSchedules(schedulePath);
+
+    // Start the scheduler
+    scheduler.start();
+
+    // Register shutdown handler
+    if (app && typeof app.onShutdown === 'function') {
+      app.onShutdown(async () => {
+        await scheduler.stop();
+      });
+    }
+  }
+
+  _loadConfig(container) {
+    const basePath = container.make('basePath');
+    
+    try {
+      const appConfig = require(require('path').join(basePath, 'config', 'app'));
+      return appConfig.scheduler || {};
+    } catch {
+      return {};
+    }
+  }
+}
+
+module.exports = SchedulerServiceProvider;