millas 0.2.21 → 0.2.24

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/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.
    */

package/src/orm/fields/index.js

@@ -101,6 +101,24 @@ const fields = {
         return new FieldDefinition('json', options);
     },
 
+    /**
+     * Array field — stores an ordered list of values.
+     *
+     * On PostgreSQL: uses native ARRAY type (text[], integer[], etc.)
+     * On SQLite/MySQL: falls back to JSON column (same as fields.json())
+     *
+     * @param {string} [of='text']  — item type: 'text' | 'integer' | 'float' | 'boolean'
+     *
+     * @example
+     *   tags:      fields.array()              // text[] on PG, json on SQLite
+     *   scores:    fields.array('integer')     // integer[] on PG
+     *   media_ids: fields.array('integer', { nullable: true, default: [] })
+     */
+    array(of = 'text', options = {}) {
+        if (typeof of === 'object') { options = of; of = 'text'; }
+        return new FieldDefinition('array', { arrayOf: of, nullable: true, default: [], ...options });
+    },
+
     date(options = {}) {
         return new FieldDefinition('date', options);
     },

package/src/orm/migration/MigrationWriter.js

@@ -408,6 +408,12 @@ ${opsCode},
       case 'id':
         return 'fields.id()';
 
+      case 'array': {
+        const of_ = def.arrayOf || 'text';
+        const optsStr = Object.keys(opts).length ? `, ${this._renderOpts(opts)}` : '';
+        return `fields.array('${of_}'${optsStr})`;
+      }
+
       case 'enum': {
         const vals = JSON.stringify(def.enumValues || []);
         const optsStr = Object.keys(opts).length

package/src/orm/migration/ModelInspector.js

@@ -523,6 +523,10 @@ ${this._renderColumn('      ', diff.column, diff.previous, '.alter()')}
                 line = `t.json('${name}')`;
                 break;
 
+            case 'array':
+                line = `t.specificType('${name}', '${field.arrayOf || 'text'}[]')`;
+                break;
+
             case 'date':
                 line = `t.date('${name}')`;
                 break;

package/src/orm/migration/operations/column.js

@@ -93,6 +93,24 @@ function _buildColumn(t, name, def, opts = {}) {
     case 'json':
       return t.json(name);
 
+    case 'array': {
+      const client = t.client?.config?.client || '';
+      if (client.includes('pg') || client.includes('postgres')) {
+        // Native Postgres ARRAY type
+        const pgTypeMap = {
+          text: 'text', string: 'text',
+          integer: 'integer', int: 'integer',
+          float: 'float', decimal: 'decimal',
+          boolean: 'boolean',
+          uuid: 'uuid',
+        };
+        const pgType = pgTypeMap[def.arrayOf || 'text'] || 'text';
+        return t.specificType(name, `${pgType}[]`);
+      }
+      // SQLite / MySQL — fall back to JSON
+      return t.json(name);
+    }
+
     case 'date':
       return t.date(name);
 

package/src/orm/model/Model.js

@@ -957,7 +957,8 @@ class Model {
       case 'bigInteger': return typeof val === 'bigint' ? val : parseInt(val, 10);
       case 'float':
       case 'decimal':    return typeof val === 'number' ? val : parseFloat(val);
-      case 'json':       return typeof val === 'string' ? JSON.parse(val) : val;
+      case 'json':
+      case 'array':      return typeof val === 'string' ? JSON.parse(val) : (Array.isArray(val) ? val : (val ?? []));
       case 'date':
       case 'timestamp':  {
         if (val instanceof Date) return isNaN(val.getTime()) ? null : val;
@@ -981,7 +982,7 @@ class Model {
 
   static _serializeValue(val, type) {
     if (val == null) return val;
-    if (type === 'json') return typeof val === 'string' ? val : JSON.stringify(val);
+    if (type === 'json' || type === 'array') return typeof val === 'string' ? val : JSON.stringify(val);
     if (type === 'boolean') return val ? 1 : 0;
     if ((type === 'date' || type === 'timestamp') && val instanceof Date) return val.toISOString();
     return val;

package/src/orm/query/QueryBuilder.js

@@ -253,6 +253,42 @@ class QueryBuilder {
     return this;
   }
 
+  join(table, col1, col2, col3) {
+    this._query = col3
+      ? this._query.join(table, col1, col2, col3)
+      : this._query.join(table, col1, col2);
+    return this;
+  }
+
+  leftJoin(table, col1, col2, col3) {
+    this._query = col3
+      ? this._query.leftJoin(table, col1, col2, col3)
+      : this._query.leftJoin(table, col1, col2);
+    return this;
+  }
+
+  rightJoin(table, col1, col2, col3) {
+    this._query = col3
+      ? this._query.rightJoin(table, col1, col2, col3)
+      : this._query.rightJoin(table, col1, col2);
+    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);
@@ -561,6 +597,38 @@ class QueryBuilder {
         continue;
       }
 
+      // -- Nested dot notation: 'documents.document_images'
+      // Matches Django's prefetch_related('documents__document_images')
+      if (name.includes('.')) {
+        const [parentRel, ...rest] = name.split('.');
+        const nestedName = rest.join('.');
+        const parentRelDef = relations[parentRel];
+        if (!parentRelDef) {
+          MillasLog.w('ORM', `Relation "${parentRel}" not defined on ${this._model.name} -- skipping nested eager load`);
+          continue;
+        }
+        const alreadyLoaded = instances[0]?.[parentRel] !== undefined &&
+          typeof instances[0]?.[parentRel] !== 'function';
+        if (!alreadyLoaded) {
+          await parentRelDef.eagerLoad(instances, parentRel, null);
+        }
+        const parentInstances = instances.flatMap(i => {
+          const val = i[parentRel];
+          if (!val) return [];
+          return Array.isArray(val) ? val : [val];
+        });
+        if (parentInstances.length) {
+          const RelatedModel = parentRelDef._related;
+          if (RelatedModel) {
+            const QB = require('./QueryBuilder');
+            const subQb = new QB(RelatedModel._db(), RelatedModel);
+            subQb._withs = [{ name: nestedName, constraint: null }];
+            await subQb._eagerLoad(parentInstances);
+          }
+        }
+        continue;
+      }
+
       // ── Normal eager load ─────────────────────────────────────────────────
       const rel = relations[name];
       if (!rel) {

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;