webspresso 0.0.90 → 0.0.93

package/core/queue/adapters/memory.js

@@ -0,0 +1,176 @@
+/**
+ * In-Memory Queue Adapter
+ * @module core/queue/adapters/memory
+ */
+
+'use strict';
+
+const { Job } = require('../job');
+
+class MemoryQueueAdapter {
+  constructor() {
+    /** @type {Map<string|number, Job>} */
+    this.jobs = new Map();
+  }
+
+  /**
+   * Enqueue a job into memory
+   * @param {Job} job
+   * @returns {Promise<Job>}
+   */
+  async enqueue(job) {
+    const jobInstance = job instanceof Job ? job : new Job(job);
+    this.jobs.set(jobInstance.id, jobInstance);
+    return jobInstance;
+  }
+
+  /**
+   * Dequeue the highest priority pending job matching registered job names
+   * @param {string[]} [jobNames]
+   * @returns {Promise<Job|null>}
+   */
+  async dequeue(jobNames = []) {
+    const now = Date.now();
+    let candidate = null;
+
+    for (const job of this.jobs.values()) {
+      if (job.status !== 'pending') continue;
+      if (job.runAt && job.runAt.getTime() > now) continue;
+      if (jobNames.length > 0 && !jobNames.includes(job.name)) continue;
+
+      if (!candidate) {
+        candidate = job;
+      } else {
+        // Priority (higher first) then runAt (earlier first)
+        if (job.priority > candidate.priority) {
+          candidate = job;
+        } else if (job.priority === candidate.priority && job.runAt.getTime() < candidate.runAt.getTime()) {
+          candidate = job;
+        }
+      }
+    }
+
+    if (candidate) {
+      candidate.status = 'running';
+      candidate.attempts += 1;
+      candidate.updatedAt = new Date();
+      return candidate;
+    }
+
+    return null;
+  }
+
+  /**
+   * Dequeue multiple pending jobs up to limit
+   * @param {string[]} [jobNames]
+   * @param {number} [limit=1]
+   * @returns {Promise<Job[]>}
+   */
+  async dequeueMany(jobNames = [], limit = 1) {
+    if (limit <= 1) {
+      const single = await this.dequeue(jobNames);
+      return single ? [single] : [];
+    }
+
+    const jobs = [];
+    for (let i = 0; i < limit; i++) {
+      const job = await this.dequeue(jobNames);
+      if (!job) break;
+      jobs.push(job);
+    }
+    return jobs;
+  }
+
+  /**
+   * Mark job as completed
+   * @param {string|number} jobId
+   * @param {any} [result]
+   * @returns {Promise<Job|null>}
+   */
+  async complete(jobId, result = null) {
+    const job = this.jobs.get(jobId);
+    if (!job) return null;
+    job.status = 'completed';
+    job.result = result;
+    job.progressValue = 100;
+    job.updatedAt = new Date();
+    return job;
+  }
+
+  /**
+   * Mark job as permanently failed
+   * @param {string|number} jobId
+   * @param {any} [error]
+   * @returns {Promise<Job|null>}
+   */
+  async fail(jobId, error = null) {
+    const job = this.jobs.get(jobId);
+    if (!job) return null;
+    job.status = 'failed';
+    job.error = error;
+    job.updatedAt = new Date();
+    return job;
+  }
+
+  /**
+   * Re-schedule job for retry
+   * @param {string|number} jobId
+   * @param {number} delayMs
+   * @param {any} [error]
+   * @returns {Promise<Job|null>}
+   */
+  async retry(jobId, delayMs, error = null) {
+    const job = this.jobs.get(jobId);
+    if (!job) return null;
+    job.status = 'pending';
+    job.runAt = new Date(Date.now() + Math.max(0, delayMs));
+    job.error = error;
+    job.updatedAt = new Date();
+    return job;
+  }
+
+  /**
+   * Get job by ID
+   * @param {string|number} jobId
+   * @returns {Promise<Job|null>}
+   */
+  async getJob(jobId) {
+    return this.jobs.get(jobId) || null;
+  }
+
+  /**
+   * Get queue statistics
+   * @returns {Promise<{ pending: number, running: number, completed: number, failed: number, total: number }>}
+   */
+  async getStats() {
+    let pending = 0;
+    let running = 0;
+    let completed = 0;
+    let failed = 0;
+
+    for (const job of this.jobs.values()) {
+      if (job.status === 'pending') pending++;
+      else if (job.status === 'running') running++;
+      else if (job.status === 'completed') completed++;
+      else if (job.status === 'failed') failed++;
+    }
+
+    return {
+      pending,
+      running,
+      completed,
+      failed,
+      total: this.jobs.size,
+    };
+  }
+
+  /**
+   * Clear all jobs
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    this.jobs.clear();
+  }
+}
+
+module.exports = { MemoryQueueAdapter };

package/core/queue/adapters/redis.js

@@ -0,0 +1,357 @@
+/**
+ * Distributed Redis Queue Adapter
+ * @module core/queue/adapters/redis
+ */
+
+'use strict';
+
+const { Job } = require('../job');
+
+class RedisQueueAdapter {
+  /**
+   * @param {Object} options
+   * @param {any} options.client - ioredis or @redis/client instance
+   * @param {string} [options.prefix='webspresso:queue:'] - Key prefix
+   */
+  constructor(options = {}) {
+    if (!options.client) {
+      throw new Error('RedisQueueAdapter requires a Redis client in options.client');
+    }
+    this.client = options.client;
+    this.prefix = options.prefix || 'webspresso:queue:';
+  }
+
+  _key(name) {
+    return this.prefix + name;
+  }
+
+  /**
+   * Enqueue a job into Redis
+   * @param {Job} job
+   * @returns {Promise<Job>}
+   */
+  async enqueue(job) {
+    const jobInstance = job instanceof Job ? job : new Job(job);
+    const jobKey = this._key('job:' + jobInstance.id);
+    const delayedKey = this._key('delayed');
+    const waitingKey = this._key('waiting');
+
+    const jobData = JSON.stringify(jobInstance.toJSON());
+
+    // Save job payload
+    if (typeof this.client.set === 'function') {
+      await this.client.set(jobKey, jobData);
+    }
+
+    const now = Date.now();
+    const runAt = jobInstance.runAt ? jobInstance.runAt.getTime() : now;
+
+    if (runAt > now) {
+      // Delayed job
+      if (typeof this.client.zadd === 'function') {
+        await this.client.zadd(delayedKey, runAt, String(jobInstance.id));
+      } else if (typeof this.client.zAdd === 'function') {
+        await this.client.zAdd(delayedKey, [{ score: runAt, value: String(jobInstance.id) }]);
+      }
+    } else {
+      // Ready to process (score is negative priority to sort highest priority first)
+      const score = (100 - (jobInstance.priority || 10)) * 1000000000000 + runAt;
+      if (typeof this.client.zadd === 'function') {
+        await this.client.zadd(waitingKey, score, String(jobInstance.id));
+      } else if (typeof this.client.zAdd === 'function') {
+        await this.client.zAdd(waitingKey, [{ score, value: String(jobInstance.id) }]);
+      }
+    }
+
+    return jobInstance;
+  }
+
+  /**
+   * Move due delayed jobs into waiting queue
+   * @private
+   */
+  async _promoteDelayed() {
+    const delayedKey = this._key('delayed');
+    const waitingKey = this._key('waiting');
+    const now = Date.now();
+
+    try {
+      let dueIds = [];
+      if (typeof this.client.zrangebyscore === 'function') {
+        dueIds = await this.client.zrangebyscore(delayedKey, 0, now);
+      } else if (typeof this.client.zRangeByScore === 'function') {
+        dueIds = await this.client.zRangeByScore(delayedKey, 0, now);
+      }
+
+      if (dueIds && dueIds.length > 0) {
+        for (const id of dueIds) {
+          const job = await this.getJob(id);
+          if (job) {
+            const score = (100 - (job.priority || 10)) * 1000000000000 + now;
+            if (typeof this.client.zadd === 'function') {
+              await this.client.zadd(waitingKey, score, String(id));
+              await this.client.zrem(delayedKey, String(id));
+            } else if (typeof this.client.zAdd === 'function') {
+              await this.client.zAdd(waitingKey, [{ score, value: String(id) }]);
+              await this.client.zRem(delayedKey, String(id));
+            }
+          }
+        }
+      }
+    } catch {}
+  }
+
+  /**
+   * Dequeue next pending job
+   * @param {string[]} [jobNames]
+   * @returns {Promise<Job|null>}
+   */
+  async dequeue(jobNames = []) {
+    await this._promoteDelayed();
+
+    const waitingKey = this._key('waiting');
+    const activeKey = this._key('active');
+
+    let ids = [];
+    if (typeof this.client.zrange === 'function') {
+      ids = await this.client.zrange(waitingKey, 0, 50);
+    } else if (typeof this.client.zRange === 'function') {
+      ids = await this.client.zRange(waitingKey, 0, 50);
+    }
+
+    if (!ids || ids.length === 0) return null;
+
+    for (const id of ids) {
+      const job = await this.getJob(id);
+      if (!job) {
+        if (typeof this.client.zrem === 'function') await this.client.zrem(waitingKey, String(id));
+        else if (typeof this.client.zRem === 'function') await this.client.zRem(waitingKey, String(id));
+        continue;
+      }
+
+      if (jobNames.length > 0 && !jobNames.includes(job.name)) {
+        continue;
+      }
+
+      // Pop from waiting and add to active
+      if (typeof this.client.zrem === 'function') {
+        await this.client.zrem(waitingKey, String(id));
+        await this.client.sadd(activeKey, String(id));
+      } else if (typeof this.client.zRem === 'function') {
+        await this.client.zRem(waitingKey, String(id));
+        await this.client.sAdd(activeKey, String(id));
+      }
+
+      job.status = 'running';
+      job.attempts += 1;
+      job.updatedAt = new Date();
+
+      const jobKey = this._key('job:' + job.id);
+      if (typeof this.client.set === 'function') {
+        await this.client.set(jobKey, JSON.stringify(job.toJSON()));
+      }
+
+      return job;
+    }
+
+    return null;
+  }
+
+  /**
+   * Dequeue multiple pending jobs up to limit
+   * @param {string[]} [jobNames]
+   * @param {number} [limit=1]
+   * @returns {Promise<Job[]>}
+   */
+  async dequeueMany(jobNames = [], limit = 1) {
+    if (limit <= 1) {
+      const single = await this.dequeue(jobNames);
+      return single ? [single] : [];
+    }
+
+    const jobs = [];
+    for (let i = 0; i < limit; i++) {
+      const job = await this.dequeue(jobNames);
+      if (!job) break;
+      jobs.push(job);
+    }
+    return jobs;
+  }
+
+  /**
+   * Mark job as completed
+   * @param {string|number} jobId
+   * @param {any} [result]
+   * @returns {Promise<Job|null>}
+   */
+  async complete(jobId, result = null) {
+    const job = await this.getJob(jobId);
+    if (!job) return null;
+
+    const activeKey = this._key('active');
+    const completedKey = this._key('completed');
+    const jobKey = this._key('job:' + jobId);
+
+    if (typeof this.client.srem === 'function') {
+      await this.client.srem(activeKey, String(jobId));
+      await this.client.sadd(completedKey, String(jobId));
+    } else if (typeof this.client.sRem === 'function') {
+      await this.client.sRem(activeKey, String(jobId));
+      await this.client.sAdd(completedKey, String(jobId));
+    }
+
+    job.status = 'completed';
+    job.result = result;
+    job.progressValue = 100;
+    job.updatedAt = new Date();
+
+    if (typeof this.client.set === 'function') {
+      await this.client.set(jobKey, JSON.stringify(job.toJSON()));
+    }
+
+    return job;
+  }
+
+  /**
+   * Mark job as failed
+   * @param {string|number} jobId
+   * @param {any} [error]
+   * @returns {Promise<Job|null>}
+   */
+  async fail(jobId, error = null) {
+    const job = await this.getJob(jobId);
+    if (!job) return null;
+
+    const activeKey = this._key('active');
+    const failedKey = this._key('failed');
+    const jobKey = this._key('job:' + jobId);
+
+    if (typeof this.client.srem === 'function') {
+      await this.client.srem(activeKey, String(jobId));
+      await this.client.sadd(failedKey, String(jobId));
+    } else if (typeof this.client.sRem === 'function') {
+      await this.client.sRem(activeKey, String(jobId));
+      await this.client.sAdd(failedKey, String(jobId));
+    }
+
+    job.status = 'failed';
+    job.error = error;
+    job.updatedAt = new Date();
+
+    if (typeof this.client.set === 'function') {
+      await this.client.set(jobKey, JSON.stringify(job.toJSON()));
+    }
+
+    return job;
+  }
+
+  /**
+   * Re-enqueue job for retry
+   * @param {string|number} jobId
+   * @param {number} delayMs
+   * @param {any} [error]
+   * @returns {Promise<Job|null>}
+   */
+  async retry(jobId, delayMs, error = null) {
+    const job = await this.getJob(jobId);
+    if (!job) return null;
+
+    const activeKey = this._key('active');
+    if (typeof this.client.srem === 'function') {
+      await this.client.srem(activeKey, String(jobId));
+    } else if (typeof this.client.sRem === 'function') {
+      await this.client.sRem(activeKey, String(jobId));
+    }
+
+    job.status = 'pending';
+    job.runAt = new Date(Date.now() + Math.max(0, delayMs));
+    job.error = error;
+    job.updatedAt = new Date();
+
+    await this.enqueue(job);
+    return job;
+  }
+
+  /**
+   * Get job by ID
+   * @param {string|number} jobId
+   * @returns {Promise<Job|null>}
+   */
+  async getJob(jobId) {
+    const jobKey = this._key('job:' + jobId);
+    let raw = null;
+    if (typeof this.client.get === 'function') {
+      raw = await this.client.get(jobKey);
+    }
+    if (!raw) return null;
+
+    try {
+      const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+      return new Job(parsed);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get stats
+   * @returns {Promise<{ pending: number, running: number, completed: number, failed: number, total: number }>}
+   */
+  async getStats() {
+    const waitingKey = this._key('waiting');
+    const delayedKey = this._key('delayed');
+    const activeKey = this._key('active');
+    const completedKey = this._key('completed');
+    const failedKey = this._key('failed');
+
+    let pending = 0;
+    let delayed = 0;
+    let running = 0;
+    let completed = 0;
+    let failed = 0;
+
+    try {
+      if (typeof this.client.zcard === 'function') {
+        pending = (await this.client.zcard(waitingKey)) || 0;
+        delayed = (await this.client.zcard(delayedKey)) || 0;
+        running = (await this.client.scard(activeKey)) || 0;
+        completed = (await this.client.scard(completedKey)) || 0;
+        failed = (await this.client.scard(failedKey)) || 0;
+      } else if (typeof this.client.zCard === 'function') {
+        pending = (await this.client.zCard(waitingKey)) || 0;
+        delayed = (await this.client.zCard(delayedKey)) || 0;
+        running = (await this.client.sCard(activeKey)) || 0;
+        completed = (await this.client.sCard(completedKey)) || 0;
+        failed = (await this.client.sCard(failedKey)) || 0;
+      }
+    } catch {}
+
+    const totalPending = pending + delayed;
+    return {
+      pending: totalPending,
+      running,
+      completed,
+      failed,
+      total: totalPending + running + completed + failed,
+    };
+  }
+
+  /**
+   * Clear all queue keys
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    const keys = [
+      this._key('waiting'),
+      this._key('delayed'),
+      this._key('active'),
+      this._key('completed'),
+      this._key('failed'),
+    ];
+    for (const k of keys) {
+      if (typeof this.client.del === 'function') await this.client.del(k);
+    }
+  }
+}
+
+module.exports = { RedisQueueAdapter };

package/core/queue/index.js

@@ -0,0 +1,21 @@
+/**
+ * Webspresso Core Background Job Queue Engine
+ * @module core/queue
+ */
+
+'use strict';
+
+const { Job } = require('./job');
+const { QueueManager, createQueueManager } = require('./manager');
+const { MemoryQueueAdapter } = require('./adapters/memory');
+const { DatabaseQueueAdapter } = require('./adapters/database');
+const { RedisQueueAdapter } = require('./adapters/redis');
+
+module.exports = {
+  Job,
+  QueueManager,
+  createQueueManager,
+  MemoryQueueAdapter,
+  DatabaseQueueAdapter,
+  RedisQueueAdapter,
+};

package/core/queue/job.js

@@ -0,0 +1,103 @@
+/**
+ * Background Job Entity
+ * @module core/queue/job
+ */
+
+'use strict';
+
+class Job {
+  /**
+   * @param {Object} options
+   * @param {string|number} options.id
+   * @param {string} options.name
+   * @param {any} [options.data={}]
+   * @param {'pending'|'running'|'completed'|'failed'} [options.status='pending']
+   * @param {number} [options.attempts=0]
+   * @param {number} [options.maxAttempts=3]
+   * @param {number|Object} [options.backoff={ type: 'exponential', delay: 1000 }]
+   * @param {number} [options.priority=10]
+   * @param {number} [options.timeout=30000]
+   * @param {number} [options.progress=0]
+   * @param {any} [options.result=null]
+   * @param {any} [options.error=null]
+   * @param {Date|number|string} [options.runAt]
+   * @param {Date|number|string} [options.createdAt]
+   * @param {Date|number|string} [options.updatedAt]
+   * @param {Function} [options.onProgress]
+   */
+  constructor(options = {}) {
+    this.id = options.id || ('job_' + Math.random().toString(36).slice(2, 11) + Date.now().toString(36));
+    this.name = options.name || 'default';
+    this.data = options.data !== undefined ? options.data : {};
+    this.status = options.status || 'pending';
+    this.attempts = options.attempts || 0;
+    this.maxAttempts = options.maxAttempts !== undefined ? options.maxAttempts : 3;
+    this.backoff = options.backoff !== undefined ? options.backoff : { type: 'exponential', delay: 1000 };
+    this.priority = options.priority !== undefined ? options.priority : 10;
+    this.timeout = options.timeout !== undefined ? options.timeout : 30000;
+    this.progressValue = options.progress || 0;
+    this.result = options.result || null;
+    this.error = options.error || null;
+    this.createdAt = options.createdAt ? new Date(options.createdAt) : new Date();
+    this.updatedAt = options.updatedAt ? new Date(options.updatedAt) : new Date();
+    this.runAt = options.runAt ? new Date(options.runAt) : new Date();
+    this._onProgress = options.onProgress || null;
+  }
+
+  /**
+   * Update progress of a running job
+   * @param {number} percent - 0 to 100
+   * @param {string} [message]
+   */
+  progress(percent, message) {
+    this.progressValue = Math.min(100, Math.max(0, percent));
+    this.updatedAt = new Date();
+    if (typeof this._onProgress === 'function') {
+      this._onProgress(this, this.progressValue, message);
+    }
+  }
+
+  /**
+   * Compute next retry delay in milliseconds based on backoff config
+   * @returns {number}
+   */
+  getNextRetryDelay() {
+    if (typeof this.backoff === 'number') {
+      return this.backoff;
+    }
+    const baseDelay = (this.backoff && this.backoff.delay) || 1000;
+    const type = (this.backoff && this.backoff.type) || 'exponential';
+
+    if (type === 'fixed') {
+      return baseDelay;
+    }
+    // Exponential: baseDelay * 2^(attempts - 1)
+    const factor = Math.max(1, Math.pow(2, Math.max(0, this.attempts - 1)));
+    return Math.min(baseDelay * factor, 3600000); // Cap at 1 hour
+  }
+
+  /**
+   * Plain object serialization
+   */
+  toJSON() {
+    return {
+      id: this.id,
+      name: this.name,
+      data: this.data,
+      status: this.status,
+      attempts: this.attempts,
+      maxAttempts: this.maxAttempts,
+      backoff: this.backoff,
+      priority: this.priority,
+      timeout: this.timeout,
+      progress: this.progressValue,
+      result: this.result,
+      error: this.error ? (this.error.message || String(this.error)) : null,
+      createdAt: this.createdAt.toISOString(),
+      updatedAt: this.updatedAt.toISOString(),
+      runAt: this.runAt.toISOString(),
+    };
+  }
+}
+
+module.exports = { Job };