millas 0.1.0

package/src/queue/drivers/DatabaseDriver.js

@@ -0,0 +1,194 @@
+'use strict';
+
+/**
+ * DatabaseDriver
+ *
+ * Stores jobs in the `millas_jobs` database table.
+ * Requires a database connection configured in config/database.js.
+ *
+ * Run migration to create the table:
+ *   millas migrate
+ *
+ * Start the worker:
+ *   millas queue:work
+ *   millas queue:work --queue emails,notifications
+ *   millas queue:work --sleep 3
+ */
+class DatabaseDriver {
+  constructor(config = {}) {
+    this._config     = config;
+    this._connection = config.connection || null;
+    this._db         = null;
+    this._table      = config.table || 'millas_jobs';
+    this._failedTable = config.failedTable || 'millas_failed_jobs';
+  }
+
+  // ─── Push ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Push a serialized job onto the queue.
+   */
+  async push(job) {
+    const db      = this._getDb();
+    const record  = job.serialize();
+    const runAt   = record.delay
+      ? new Date(Date.now() + record.delay * 1000).toISOString()
+      : new Date().toISOString();
+
+    const [id] = await db(this._table).insert({
+      queue:      record.queue,
+      payload:    JSON.stringify(record),
+      attempts:   0,
+      max_tries:  record.tries,
+      status:     'pending',
+      run_at:     runAt,
+      created_at: new Date().toISOString(),
+    });
+
+    return { id, status: 'queued', queue: record.queue };
+  }
+
+  // ─── Pop (used by worker) ─────────────────────────────────────────────────
+
+  /**
+   * Fetch the next available job from the queue.
+   * Marks it as 'processing' atomically.
+   */
+  async pop(queue = 'default') {
+    const db  = this._getDb();
+    const now = new Date().toISOString();
+
+    const row = await db(this._table)
+      .where('queue',   queue)
+      .where('status',  'pending')
+      .where('run_at',  '<=', now)
+      .orderBy('run_at', 'asc')
+      .first();
+
+    if (!row) return null;
+
+    await db(this._table).where('id', row.id).update({
+      status:       'processing',
+      started_at:   now,
+      attempts:     row.attempts + 1,
+    });
+
+    return { ...row, attempts: row.attempts + 1 };
+  }
+
+  // ─── Complete / Fail ──────────────────────────────────────────────────────
+
+  async complete(id) {
+    await this._getDb()(this._table).where('id', id).update({
+      status:      'completed',
+      finished_at: new Date().toISOString(),
+    });
+  }
+
+  async fail(id, error, record) {
+    const db       = this._getDb();
+    const row      = await db(this._table).where('id', id).first();
+    const maxTries = row?.max_tries || 3;
+    const attempts = row?.attempts  || 1;
+
+    if (attempts < maxTries) {
+      // Schedule retry with backoff
+      const backoff = this._backoff(record?.backoff || 'exponential', attempts);
+      const runAt   = new Date(Date.now() + backoff * 1000).toISOString();
+
+      await db(this._table).where('id', id).update({
+        status:  'pending',
+        run_at:  runAt,
+        last_error: error.message,
+      });
+    } else {
+      // Move to failed jobs table
+      await db(this._failedTable).insert({
+        queue:      row?.queue,
+        payload:    row?.payload,
+        error:      error.message,
+        failed_at:  new Date().toISOString(),
+      });
+      await db(this._table).where('id', id).delete();
+    }
+  }
+
+  async release(id) {
+    await this._getDb()(this._table).where('id', id).update({ status: 'pending' });
+  }
+
+  // ─── Stats ────────────────────────────────────────────────────────────────
+
+  async size(queue = 'default') {
+    const result = await this._getDb()(this._table)
+      .where('queue', queue).where('status', 'pending').count('* as count').first();
+    return Number(result?.count || 0);
+  }
+
+  async clear(queue = 'default') {
+    return this._getDb()(this._table)
+      .where('queue', queue).where('status', 'pending').delete();
+  }
+
+  async stats() {
+    const db = this._getDb();
+    const rows = await db(this._table)
+      .select('queue', 'status')
+      .count('* as count')
+      .groupBy('queue', 'status');
+    return rows;
+  }
+
+  // ─── Schema ───────────────────────────────────────────────────────────────
+
+  /**
+   * Create the jobs tables. Called by migrate.
+   */
+  async createTables() {
+    const db = this._getDb();
+
+    const jobsExists = await db.schema.hasTable(this._table);
+    if (!jobsExists) {
+      await db.schema.createTable(this._table, (t) => {
+        t.increments('id');
+        t.string('queue', 100).notNullable().defaultTo('default').index();
+        t.text('payload').notNullable();
+        t.integer('attempts').defaultTo(0);
+        t.integer('max_tries').defaultTo(3);
+        t.string('status', 20).defaultTo('pending').index();
+        t.string('last_error').nullable();
+        t.timestamp('run_at').nullable().index();
+        t.timestamp('started_at').nullable();
+        t.timestamp('finished_at').nullable();
+        t.timestamp('created_at').nullable();
+      });
+    }
+
+    const failedExists = await db.schema.hasTable(this._failedTable);
+    if (!failedExists) {
+      await db.schema.createTable(this._failedTable, (t) => {
+        t.increments('id');
+        t.string('queue', 100).nullable();
+        t.text('payload').nullable();
+        t.text('error').nullable();
+        t.timestamp('failed_at').nullable();
+      });
+    }
+  }
+
+  // ─── Internal ─────────────────────────────────────────────────────────────
+
+  _getDb() {
+    if (this._db) return this._db;
+    const DatabaseManager = require('../orm/drivers/DatabaseManager');
+    this._db = DatabaseManager.connection(this._connection);
+    return this._db;
+  }
+
+  _backoff(strategy, attempt) {
+    if (strategy === 'exponential') return Math.min(Math.pow(2, attempt), 3600);
+    return 60; // fixed: 60 seconds
+  }
+}
+
+module.exports = DatabaseDriver;

package/src/queue/drivers/SyncDriver.js

@@ -0,0 +1,72 @@
+'use strict';
+
+/**
+ * SyncDriver
+ *
+ * Executes jobs immediately and synchronously in the current process.
+ * Default driver — no Redis or DB required.
+ *
+ * Perfect for:
+ *   - Local development
+ *   - Testing
+ *   - Simple apps that don't need background processing
+ *
+ * Set QUEUE_DRIVER=sync in .env
+ */
+class SyncDriver {
+  constructor() {
+    this._processed = [];
+    this._failed    = [];
+  }
+
+  /**
+   * Push and immediately execute a job.
+   */
+  async push(job) {
+    const record = {
+      id:         this._id(),
+      job:        job.constructor.name,
+      queue:      job._queue || job.constructor.queue || 'default',
+      payload:    job._getPayload(),
+      attempts:   0,
+      status:     'processing',
+      createdAt:  new Date().toISOString(),
+    };
+
+    try {
+      await job.handle();
+      record.status     = 'completed';
+      record.finishedAt = new Date().toISOString();
+      this._processed.push(record);
+      return { id: record.id, status: 'completed' };
+    } catch (error) {
+      record.status    = 'failed';
+      record.error     = error.message;
+      record.failedAt  = new Date().toISOString();
+      this._failed.push(record);
+
+      if (typeof job.failed === 'function') {
+        await job.failed(error).catch(() => {});
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * SyncDriver has no persistent queue — nothing to work.
+   */
+  async work() {
+    return { processed: 0, message: 'SyncDriver: jobs run immediately on dispatch.' };
+  }
+
+  async size(queue = 'default') { return 0; }
+  async clear(queue = 'default') { return 0; }
+
+  processed() { return [...this._processed]; }
+  failed()    { return [...this._failed]; }
+
+  _id() { return `sync_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`; }
+}
+
+module.exports = SyncDriver;

package/src/queue/index.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const Queue        = require('./Queue');
+const Job          = require('./Job');
+const QueueWorker  = require('./workers/QueueWorker');
+const SyncDriver   = require('./drivers/SyncDriver');
+const DatabaseDriver = require('./drivers/DatabaseDriver');
+
+module.exports = {
+  Queue,
+  Job,
+  QueueWorker,
+  SyncDriver,
+  DatabaseDriver,
+  dispatch: Queue.dispatch,
+};

package/src/queue/workers/QueueWorker.js

@@ -0,0 +1,140 @@
+'use strict';
+
+/**
+ * QueueWorker
+ *
+ * Polls the queue driver and executes pending jobs.
+ * Started by: millas queue:work
+ *
+ * Usage:
+ *   const worker = new QueueWorker(driver, registry, options);
+ *   await worker.start();
+ */
+class QueueWorker {
+  constructor(driver, jobRegistry, options = {}) {
+    this._driver        = driver;
+    this._registry      = jobRegistry;
+    this._queues        = options.queues       || ['default'];
+    this._sleep         = options.sleep        || 3;
+    this._maxJobs       = options.maxJobs      || Infinity;
+    this._handleSignals = options.handleSignals !== false && options.maxJobs === undefined;
+    this._silent        = options.silent       || options.maxJobs !== undefined;
+    this._running       = false;
+    this._processed     = 0;
+    this._failed        = 0;
+  }
+
+  /**
+   * Start the worker loop.
+   */
+  async start() {
+    this._running = true;
+
+    if (!this._silent) {
+      console.log(`\n  ⚡ Queue worker started`);
+      console.log(`  Queues: ${this._queues.join(', ')}`);
+      console.log(`  Sleep:  ${this._sleep}s between polls\n`);
+    }
+
+    // Only register signal handlers when running as main process
+    if (this._handleSignals) {
+      process.on('SIGINT',  () => this.stop('SIGINT'));
+      process.on('SIGTERM', () => this.stop('SIGTERM'));
+    }
+
+    while (this._running && this._processed < this._maxJobs) {
+      let worked = false;
+
+      for (const queue of this._queues) {
+        const record = await this._driver.pop(queue);
+        if (record) {
+          await this._process(record);
+          worked = true;
+          break;
+        }
+      }
+
+      if (!worked) {
+        // If maxJobs is finite and queue is empty, stop
+        if (this._maxJobs < Infinity) break;
+        await this._sleep_ms(this._sleep * 1000);
+      }
+    }
+
+    if (!this._silent) {
+      console.log(`\n  Worker stopped. Processed: ${this._processed}, Failed: ${this._failed}\n`);
+    }
+  }
+
+  stop(signal = 'manual') {
+    if (!this._silent) console.log(`\n  [${signal}] Stopping worker gracefully...`);
+    this._running = false;
+  }
+
+  stats() {
+    return { processed: this._processed, failed: this._failed };
+  }
+
+  // ─── Internal ─────────────────────────────────────────────────────────────
+
+  async _process(record) {
+    let payload;
+    try {
+      payload = JSON.parse(record.payload);
+    } catch {
+      console.error(`  ✖ Failed to parse job payload (id: ${record.id})`);
+      await this._driver.fail(record.id, new Error('Invalid payload'), {});
+      this._failed++;
+      return;
+    }
+
+    const JobClass = this._registry.get(payload.class);
+    if (!JobClass) {
+      console.error(`  ✖ Unknown job class: ${payload.class}`);
+      await this._driver.fail(record.id, new Error(`Unknown job: ${payload.class}`), payload);
+      this._failed++;
+      return;
+    }
+
+    const job = JobClass.deserialize
+      ? JobClass.deserialize({ ...record, payload: payload.payload || {} }, JobClass)
+      : Object.assign(new JobClass(), payload.payload || {});
+
+    const start = Date.now();
+    process.stdout.write(`  ⟳  ${payload.class} (id: ${record.id})... `);
+
+    try {
+      await Promise.race([
+        job.handle(),
+        this._timeout(payload.timeout || 60),
+      ]);
+
+      const ms = Date.now() - start;
+      console.log(`\x1b[32m✔\x1b[0m ${ms}ms`);
+      await this._driver.complete(record.id);
+      this._processed++;
+    } catch (error) {
+      const ms = Date.now() - start;
+      console.log(`\x1b[31m✖\x1b[0m ${ms}ms — ${error.message}`);
+      await this._driver.fail(record.id, error, payload);
+
+      if (typeof job.failed === 'function') {
+        await job.failed(error).catch(() => {});
+      }
+
+      this._failed++;
+    }
+  }
+
+  _timeout(seconds) {
+    return new Promise((_, reject) =>
+      setTimeout(() => reject(new Error(`Job timed out after ${seconds}s`)), seconds * 1000)
+    );
+  }
+
+  _sleep_ms(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+module.exports = QueueWorker;

package/src/router/MiddlewareRegistry.js

@@ -0,0 +1,82 @@
+'use strict';
+
+/**
+ * MiddlewareRegistry
+ *
+ * Maps string aliases → middleware handler classes or functions.
+ *
+ * Usage:
+ *   MiddlewareRegistry.register('auth', AuthMiddleware);
+ *   MiddlewareRegistry.register('throttle', ThrottleMiddleware);
+ *
+ * Registered automatically by AppServiceProvider (Phase 3+).
+ */
+class MiddlewareRegistry {
+  constructor() {
+    this._map = {};
+  }
+
+  /**
+   * Register a middleware alias.
+   * @param {string} alias
+   * @param {Function|object} handler  — class with handle() or raw Express fn
+   */
+  register(alias, handler) {
+    this._map[alias] = handler;
+  }
+
+  /**
+   * Resolve a single alias to an Express-compatible function.
+   * @param {string|Function} aliasOrFn
+   * @returns {Function}
+   */
+  resolve(aliasOrFn) {
+    if (typeof aliasOrFn === 'function') return aliasOrFn;
+
+    const Handler = this._map[aliasOrFn];
+    if (!Handler) {
+      throw new Error(`Middleware "${aliasOrFn}" is not registered.`);
+    }
+
+    // Pre-instantiated object with handle() method (e.g. new ThrottleMiddleware())
+    if (typeof Handler === 'object' && Handler !== null && typeof Handler.handle === 'function') {
+      return (req, res, next) => {
+        const result = Handler.handle(req, res, next);
+        if (result && typeof result.catch === 'function') result.catch(next);
+      };
+    }
+
+    // Class with handle() on prototype
+    if (typeof Handler === 'function' && Handler.prototype && typeof Handler.prototype.handle === 'function') {
+      const instance = new Handler();
+      return (req, res, next) => {
+        const result = instance.handle(req, res, next);
+        if (result && typeof result.catch === 'function') result.catch(next);
+      };
+    }
+
+    // Raw Express function
+    if (typeof Handler === 'function') return Handler;
+
+    throw new Error(`Middleware "${aliasOrFn}" must be a function or class with handle().`);
+  }
+
+  /**
+   * Resolve an array of aliases/functions.
+   * @param {Array} list
+   * @returns {Function[]}
+   */
+  resolveAll(list = []) {
+    return list.map(m => this.resolve(m));
+  }
+
+  has(alias) {
+    return Object.prototype.hasOwnProperty.call(this._map, alias);
+  }
+
+  all() {
+    return { ...this._map };
+  }
+}
+
+module.exports = MiddlewareRegistry;