queasy 0.1.0

package/src/client.js

@@ -0,0 +1,218 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getEnvironmentData } from 'node:worker_threads';
+import { HEARTBEAT_INTERVAL, HEARTBEAT_TIMEOUT } from './constants.js';
+import { Manager } from './manager.js';
+import { Pool } from './pool.js';
+import { Queue } from './queue.js';
+import { generateId } from './utils.js';
+
+// Load Lua script
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const luaScript = readFileSync(join(__dirname, 'queasy.lua'), 'utf8');
+
+/** @typedef {import('redis').RedisClientType} RedisClient */
+/** @typedef {import('./types').Job} Job */
+
+/** @typedef {{ queue: Queue, bumpTimer?: NodeJS.Timeout }} QueueEntry */
+
+/**
+ * Parse job data from Redis response
+ * @param {string[]} jobArray - Flat array from HGETALL
+ * @returns {Job | null}
+ */
+export function parseJob(jobArray) {
+    if (!jobArray || jobArray.length === 0) return null;
+
+    /** @type {Record<string, string>} */
+    const job = {};
+    for (let i = 0; i < jobArray.length; i += 2) {
+        const key = jobArray[i];
+        const value = jobArray[i + 1];
+        job[key] = value;
+    }
+
+    return {
+        id: job.id,
+        data: job.data ? JSON.parse(job.data) : undefined,
+        runAt: job.run_at ? Number(job.run_at) : 0,
+        retryCount: Number(job.retry_count || 0),
+        stallCount: Number(job.stall_count || 0),
+    };
+}
+
+export class Client {
+    /**
+     * @param {RedisClient} redis - Redis client
+     * @param {number?} workerCount - Allow this client to dequeue jobs.
+     */
+    constructor(redis, workerCount) {
+        this.redis = redis;
+        this.clientId = generateId();
+
+        /** @type {Record<string, QueueEntry>} */
+        this.queues = {};
+
+        const inWorker = getEnvironmentData('queasy_worker_context');
+        this.pool = !inWorker && workerCount !== 0 ? new Pool(workerCount) : undefined;
+        if (this.pool) this.manager = new Manager(this.pool);
+
+        // We are not awaiting this; we rely on Redis’ single-threaded blocking
+        // nature to ensure that this load completes before other Redis commands
+        // are processed.
+        this.redis.sendCommand(['FUNCTION', 'LOAD', 'REPLACE', luaScript]);
+    }
+
+    /**
+     * Create a queue object for interacting with a named queue
+     * @param {string} name - Queue name (without braces - they will be added automatically)
+     * @returns {Queue} Queue object with dispatch, cancel, and listen methods
+     */
+    queue(name, isKey = false) {
+        const key = isKey ? name : `{${name}}`;
+        if (!this.queues[key]) {
+            this.queues[key] = /** @type {QueueEntry} */ ({
+                queue: new Queue(key, this, this.pool, this.manager),
+            });
+        }
+        return this.queues[key].queue;
+    }
+
+    /**
+     * This helps tests exit cleanly.
+     */
+    close() {
+        for (const name in this.queues) {
+            this.queues[name].queue.close();
+            clearTimeout(this.queues[name].bumpTimer);
+        }
+        if (this.pool) this.pool.close();
+        if (this.manager) this.manager.close();
+        this.queues = {};
+        this.pool = undefined;
+    }
+
+    /**
+     * Schedule the next bump timer
+     * @param {string} key
+     */
+    scheduleBump(key) {
+        const queueEntry = this.queues[key];
+        if (queueEntry.bumpTimer) clearTimeout(queueEntry.bumpTimer);
+        queueEntry.bumpTimer = setTimeout(() => this.bump(key), HEARTBEAT_INTERVAL);
+    }
+
+    /**
+     * @param {string} key
+     */
+    async bump(key) {
+        // Set up the next bump first, in case this
+        this.scheduleBump(key);
+        const now = Date.now();
+        const expiry = now + HEARTBEAT_TIMEOUT;
+        await this.redis.fCall('queasy_bump', {
+            keys: [key],
+            arguments: [this.clientId, String(now), String(expiry)],
+        });
+    }
+
+    /**
+     * @param {string} key
+     * @param {string} id
+     * @param {number} runAt
+     * @param {any} data
+     * @param {boolean} updateData
+     * @param {boolean | string} updateRunAt
+     * @param {boolean} resetCounts
+     */
+    async dispatch(key, id, runAt, data, updateData, updateRunAt, resetCounts) {
+        await this.redis.fCall('queasy_dispatch', {
+            keys: [key],
+            arguments: [
+                id,
+                String(runAt),
+                JSON.stringify(data),
+                String(updateData),
+                String(updateRunAt),
+                String(resetCounts),
+            ],
+        });
+    }
+
+    /**
+     * @param {string} key
+     * @param {string} id
+     * @returns {Promise<boolean>}
+     */
+    async cancel(key, id) {
+        const result = await this.redis.fCall('queasy_cancel', {
+            keys: [key],
+            arguments: [id],
+        });
+        return result === 1;
+    }
+
+    /**
+     * @param {string} key
+     * @param {number} count
+     * @returns {Promise<Job[]>}
+     */
+    async dequeue(key, count) {
+        const now = Date.now();
+        const expiry = now + HEARTBEAT_TIMEOUT;
+        const result = /** @type {string[][]} */ (
+            await this.redis.fCall('queasy_dequeue', {
+                keys: [key],
+                arguments: [this.clientId, String(now), String(expiry), String(count)],
+            })
+        );
+
+        // Heartbeats should start with the first dequeue.
+        this.scheduleBump(key);
+
+        return /** @type Job[] */ (result.map((jobArray) => parseJob(jobArray)).filter(Boolean));
+    }
+
+    /**
+     * @param {string} key
+     * @param {string} jobId
+     */
+    async finish(key, jobId) {
+        await this.redis.fCall('queasy_finish', {
+            keys: [key],
+            arguments: [jobId, this.clientId, String(Date.now())],
+        });
+    }
+
+    /**
+     * @param {string} key
+     * @param {string} failkey
+     * @param {string} jobId
+     * @param {any} failJobData
+     */
+    async fail(key, failkey, jobId, failJobData) {
+        await this.redis.fCall('queasy_fail', {
+            keys: [key, failkey],
+            arguments: [
+                jobId,
+                this.clientId,
+                generateId(),
+                JSON.stringify(failJobData),
+                String(Date.now()),
+            ],
+        });
+    }
+
+    /**
+     * @param {string} key
+     * @param {string} jobId
+     * @param {number} retryAt
+     */
+    async retry(key, jobId, retryAt) {
+        await this.redis.fCall('queasy_retry', {
+            keys: [key],
+            arguments: [jobId, this.clientId, String(retryAt), String(Date.now())],
+        });
+    }
+}

package/src/constants.js

@@ -0,0 +1,34 @@
+/** @typedef {import('./types').HandlerOptions} HandlerOptions */
+/** @typedef {import('./types').JobUpdateOptions} JobUpdateOptions */
+
+/** @type {Required<HandlerOptions>} */
+export const DEFAULT_RETRY_OPTIONS = {
+    maxRetries: 10,
+    maxStalls: 3,
+    minBackoff: 2_000,
+    maxBackoff: 300_000, // 5 minutes
+    size: 10,
+    timeout: 60_000, // 1 minute
+};
+
+/** @type {Required<JobUpdateOptions>} */
+export const DEFAULT_UPDATE_OPTIONS = {
+    updateData: true,
+    updateRunAt: true,
+    resetCounts: false,
+};
+
+/** @type {Required<HandlerOptions>} */
+export const FAILJOB_RETRY_OPTIONS = {
+    maxRetries: 100,
+    maxStalls: 3,
+    minBackoff: 10_000,
+    maxBackoff: 900_000, // 15 minutes
+    size: 2,
+    timeout: 60_000,
+};
+
+export const HEARTBEAT_INTERVAL = 5000; // 5 seconds
+export const HEARTBEAT_TIMEOUT = 10000; // 10 seconds
+export const WORKER_CAPACITY = 10;
+export const DEQUEUE_INTERVAL = 100; // ms

package/src/errors.js

@@ -0,0 +1,25 @@
+/**
+ * Error thrown to indicate a job should not be retried
+ */
+export class PermanentError extends Error {
+    /**
+     * @param {string} message - Error message
+     */
+    constructor(message) {
+        super(message);
+        this.name = 'PermanentError';
+    }
+}
+
+/**
+ * Error indicating a job stalled (worker stopped sending heartbeats)
+ */
+export class StallError extends Error {
+    /**
+     * @param {string} message - Error message
+     */
+    constructor(message) {
+        super(message);
+        this.name = 'StallError';
+    }
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { Client } from './client.js';
+export { PermanentError, StallError } from './errors.js';

package/src/manager.js

@@ -0,0 +1,94 @@
+/**
+ * This class manages resource allocation between
+ * different queues based on the size of the queue
+ */
+
+import { DEQUEUE_INTERVAL } from './constants.js';
+
+/** @typedef {import('./pool').Pool} Pool */
+/** @typedef {import('./queue').ProcessingQueue} Queue */
+/** @typedef {{ queue: Queue, lastDequeuedAt: number, isBusy: boolean }} QueueEntry */
+
+export class Manager {
+    /** @param {Pool} pool */
+    constructor(pool) {
+        this.pool = pool;
+
+        /** @type {Array<QueueEntry>} */
+        this.queues = [];
+
+        /** @type {NodeJS.Timeout?} */
+        this.timer = null;
+
+        this.busyCount = 0;
+    }
+
+    /** @param {Queue} queue */
+    addQueue(queue) {
+        // Add this at the beginning so we dequeue it at the next available opportunity.
+        this.queues.unshift({ queue, lastDequeuedAt: 0, isBusy: false });
+        this.busyCount += 1;
+
+        // This delay is required for queue listen tests
+        // as they need to be able to control dequeueing
+        this.next();
+    }
+
+    async next() {
+        // If this function is called while the previous execution is in progress,
+        // we do not want both executions to use the same queue.
+        const entry = this.queues.shift();
+        if (!entry) return;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+
+        const size = entry.queue.handlerOptions.size;
+        if (this.pool.capacity < size) return;
+
+        const batchSize = Math.max(1, Math.floor(this.pool.capacity / this.busyCount / size));
+        entry.lastDequeuedAt = Date.now(); // We store the time just before the call to dequeue.
+        const { count } = await entry.queue.dequeue(batchSize);
+
+        // Update
+        const nowBusy = count >= batchSize;
+        this.busyCount += Number(nowBusy) - Number(entry.isBusy);
+        entry.isBusy = nowBusy;
+
+        this.queues.push(entry);
+        this.queues.sort(compareQueueEntries);
+
+        if (!this.timer && this.queues.length) {
+            const { isBusy, lastDequeuedAt } = this.queues[0];
+            // If the current top queue is busy, retry now.
+            const delay = isBusy ? 0 : Math.max(0, lastDequeuedAt - Date.now() + DEQUEUE_INTERVAL);
+            this.timer = setTimeout(() => this.next(), delay);
+        }
+    }
+
+    close() {
+        if (this.timer) clearTimeout(this.timer);
+    }
+}
+
+/**
+ * @param {QueueEntry} a
+ * @param {QueueEntry} b
+ * @returns -1 | 0 | 1
+ */
+function compareQueueEntries(a, b) {
+    if (a.isBusy > b.isBusy) return -1; // a busy, b not -> a first
+    if (a.isBusy < b.isBusy) return 1; // a free, b busy -> b first
+
+    if (a.queue.handlerOptions.priority > b.queue.handlerOptions.priority) return 1; // a higher -> a first
+    if (a.queue.handlerOptions.priority < b.queue.handlerOptions.priority) return -1; // b higher -> b first
+
+    if (a.lastDequeuedAt > b.lastDequeuedAt) return -1; // a newer -> b first
+    if (a.lastDequeuedAt < b.lastDequeuedAt) return 1; // a older -> a first
+
+    if (a.queue.handlerOptions.size > b.queue.handlerOptions.size) return 1; // a larger -> a first
+    if (a.queue.handlerOptions.size < b.queue.handlerOptions.size) return -1; // b larger -> b first
+
+    return 0;
+}

package/src/pool.js

@@ -0,0 +1,164 @@
+import { cpus } from 'node:os';
+import { Worker } from 'node:worker_threads';
+import { WORKER_CAPACITY } from './constants.js';
+import { generateId } from './utils.js';
+
+/** @typedef {import('./types').DoneMessage} DoneMessage */
+/** @typedef {import('./types').Job} Job */
+
+/** @typedef {{
+ *      worker: Worker,
+ *      capacity: number,
+ *      id: string,
+ *      jobCount: number,
+ *      stalledJobs: Set<string>
+ * }} WorkerEntry */
+
+/** @typedef {{
+ *      resolve: (value: DoneMessage) => void,
+ *      reject: (reason: DoneMessage) => void,
+ *      size: number,
+ *      timer: NodeJS.Timeout
+ *  }} JobEntry */
+
+export class Pool {
+    /** @param {number?} targetCount - Number of desired workers */
+    constructor(targetCount) {
+        /** @type {Set<WorkerEntry>} */
+        this.workers = new Set();
+        /** @type {Map<string, JobEntry>} */
+        this.activeJobs = new Map();
+
+        this.capacity = 0;
+
+        const count = targetCount ?? cpus().length;
+        for (let i = 0; i < count; i++) this.createWorker();
+    }
+
+    createWorker() {
+        const worker = new Worker(new URL('./worker.js', import.meta.url));
+        const entry = {
+            worker,
+            capacity: WORKER_CAPACITY,
+            id: generateId(),
+            jobCount: 0,
+            stalledJobs: new Set(),
+        };
+        this.capacity += WORKER_CAPACITY;
+        worker.on('message', (message) => this.handleWorkerMessage(entry, message));
+        this.workers.add(entry);
+    }
+
+    /**
+     * @param {WorkerEntry} workerEntry
+     * @param {DoneMessage} message
+     */
+    handleWorkerMessage(workerEntry, message) {
+        const { jobId, error } = message;
+        const jobEntry = this.activeJobs.get(jobId);
+        if (!jobEntry) {
+            console.warn('Worker message with unknown Job ID; Ignoring.');
+            return;
+        }
+        clearTimeout(jobEntry.timer);
+        workerEntry.capacity += jobEntry.size;
+        this.capacity += jobEntry.size;
+        workerEntry.jobCount -= 1;
+
+        // If this job was previously marked as stalled, unmark it.
+        if (workerEntry.stalledJobs.has(jobId)) workerEntry.stalledJobs.delete(jobId);
+
+        this.activeJobs.delete(jobId);
+        jobEntry[error ? 'reject' : 'resolve'](message);
+
+        // If this worker is no longer in the the pool, check if it can be terminated.
+        if (!this.workers.has(workerEntry)) this.terminateIfEmpty(workerEntry);
+    }
+
+    /**
+     *
+     * @param {WorkerEntry} workerEntry
+     * @param {string} jobId
+     */
+    handleTimeout(workerEntry, jobId) {
+        workerEntry.stalledJobs.add(jobId);
+
+        // Remove and replace this worker in the pool (if it wasn’t already).
+        if (this.workers.delete(workerEntry)) this.createWorker();
+        this.capacity -= workerEntry.capacity;
+
+        // If this is the last job in this worker, terminate it.
+        this.terminateIfEmpty(workerEntry);
+    }
+
+    /**
+     * Stops adding new jobs to a worker if it has stalled jobs.
+     * Terminates workers if all remaining jobs are stalled.
+     * @param {WorkerEntry} workerEntry
+     * @returns
+     */
+    async terminateIfEmpty({ stalledJobs, jobCount, worker }) {
+        // Don't destroy if there are still non-stalled jobs running.
+        if (jobCount > stalledJobs.size) return;
+        await worker.terminate();
+
+        for (const jobId of stalledJobs) {
+            const jobEntry = this.activeJobs.get(jobId);
+            this.activeJobs.delete(jobId);
+            jobEntry?.reject({
+                op: 'done',
+                jobId,
+                error: { name: 'StallError', message: 'Job stalled', kind: 'stall' },
+            });
+        }
+    }
+
+    /**
+     * Processes a job to the most free worker
+     * @param {string} handlerPath
+     * @param {Job} job
+     * @param {number} size
+     * @param {number} timeout - Maximum time in ms
+     * @returns {Promise<DoneMessage>}
+     */
+    process(handlerPath, job, size, timeout) {
+        // Find worker with most capacity
+        let workerEntry = null;
+        for (const entry of this.workers) {
+            if (!workerEntry || entry.capacity > workerEntry.capacity) workerEntry = entry;
+        }
+
+        if (!workerEntry) throw Error('Can’t process job without workers');
+
+        const timer = setTimeout(() => this.handleTimeout(workerEntry, job.id), timeout);
+
+        return new Promise((resolve, reject) => {
+            this.activeJobs.set(job.id, { resolve, reject, size, timer });
+            workerEntry.capacity -= size;
+            this.capacity -= size;
+            workerEntry.jobCount += 1;
+            workerEntry.worker.postMessage({ op: 'exec', handlerPath, job });
+        });
+    }
+
+    /**
+     * Terminates all workers
+     */
+    close() {
+        for (const { worker } of this.workers) {
+            worker.terminate();
+        }
+
+        for (const [jobId, { reject, timer }] of this.activeJobs.entries()) {
+            clearTimeout(timer);
+            reject({
+                op: 'done',
+                jobId,
+                error: { name: 'StallError', message: 'Pool is closing', kind: 'stall' },
+            });
+        }
+
+        this.workers = new Set();
+        this.activeJobs.clear();
+    }
+}