queasy 0.2.0 → 0.3.1

package/src/client.ts

@@ -0,0 +1,246 @@
+import EventEmitter from 'node:events';
+import { readFileSync } from 'node:fs';
+import os from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getEnvironmentData } from 'node:worker_threads';
+import { createClient, createCluster } from 'redis';
+import { HEARTBEAT_INTERVAL, HEARTBEAT_TIMEOUT, LUA_FUNCTIONS_VERSION } from './constants.ts';
+import { Manager } from './manager.ts';
+import { Pool } from './pool.ts';
+import { Queue } from './queue.ts';
+import type { Job, RedisOptions } from './types.ts';
+import { compareSemver, generateId, parseVersion } from './utils.ts';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const luaScript = readFileSync(join(__dirname, 'queasy.lua'), 'utf8').replace(
+    '__QUEASY_VERSION__',
+    LUA_FUNCTIONS_VERSION
+);
+
+type RedisConnection = ReturnType<typeof createClient> | ReturnType<typeof createCluster>;
+
+async function installLuaFunctions(redis: RedisConnection): Promise<boolean> {
+    const installedVersionString = (await (redis as ReturnType<typeof createClient>)
+        .fCall('queasy_version', { keys: [], arguments: [] })
+        .catch(() => null)) as string | null;
+    const installedVersion = parseVersion(installedVersionString);
+    const availableVersion = parseVersion(LUA_FUNCTIONS_VERSION);
+
+    if (compareSemver(availableVersion, installedVersion) > 0) {
+        await (redis as ReturnType<typeof createClient>).sendCommand([
+            'FUNCTION',
+            'LOAD',
+            'REPLACE',
+            luaScript,
+        ]);
+        return false;
+    }
+
+    return installedVersion[0] > availableVersion[0];
+}
+
+function buildRedisConnection(options: RedisOptions): RedisConnection {
+    if ('rootNodes' in options) {
+        return createCluster(options);
+    }
+    return createClient(options);
+}
+
+interface QueueEntry {
+    queue: Queue;
+    bumpTimer?: NodeJS.Timeout;
+}
+
+export function parseJob(jobArray: string[]): Job | null {
+    if (!jobArray || jobArray.length === 0) return null;
+
+    const job: Record<string, string> = {};
+    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 extends EventEmitter {
+    redis: RedisConnection;
+    clientId: string;
+    queues: Record<string, QueueEntry>;
+    disconnected: boolean;
+    pool: Pool | undefined;
+    manager: Manager | undefined;
+
+    constructor(
+        options: RedisOptions = {},
+        workerCount: number = os.cpus().length,
+        callback?: (client: Client) => unknown
+    ) {
+        super();
+        this.redis = buildRedisConnection(options);
+        this.clientId = generateId();
+        this.queues = {};
+        this.disconnected = false;
+
+        const inWorker = getEnvironmentData('queasy_worker_context');
+        this.pool = !inWorker && workerCount !== 0 ? new Pool(workerCount) : undefined;
+        if (this.pool) this.manager = new Manager(this.pool);
+
+        this.redis
+            .connect()
+            .then(() => installLuaFunctions(this.redis))
+            .then((disconnect) => {
+                this.disconnected = disconnect;
+                if (disconnect) this.emit('disconnected', 'Redis has incompatible queasy version.');
+                else {
+                    this.emit('connected');
+                    if (callback) callback(this);
+                }
+            })
+            .catch((err: Error) => {
+                this.disconnected = true;
+                this.emit('disconnected', err.message);
+            });
+    }
+
+    queue(name: string, isKey = false): Queue {
+        if (this.disconnected) throw new Error("Can't add queue: client disconnected");
+
+        const key = isKey ? name : `{${name}}`;
+        if (!this.queues[key]) {
+            this.queues[key] = {
+                queue: new Queue(key, this, this.pool, this.manager),
+            };
+        }
+        return this.queues[key].queue;
+    }
+
+    scheduleBump(key: string): void {
+        const queueEntry = this.queues[key];
+        if (queueEntry.bumpTimer) clearTimeout(queueEntry.bumpTimer);
+        queueEntry.bumpTimer = setTimeout(() => this.bump(key), HEARTBEAT_INTERVAL);
+    }
+
+    async bump(key: string): Promise<void> {
+        if (this.disconnected) return;
+        this.scheduleBump(key);
+        const now = Date.now();
+        const expiry = now + HEARTBEAT_TIMEOUT;
+        const bumped = await (this.redis as ReturnType<typeof createClient>).fCall('queasy_bump', {
+            keys: [key],
+            arguments: [this.clientId, String(now), String(expiry)],
+        });
+
+        if (!bumped) {
+            await this.close();
+            this.emit('disconnected', 'Lost locks, possible main thread freeze');
+        }
+    }
+
+    async close(): Promise<void> {
+        if (this.pool) await this.pool.close();
+        if (this.manager) await this.manager.close();
+        this.queues = {};
+        this.pool = undefined;
+        this.disconnected = true;
+        await this.redis.quit().catch(() => {});
+    }
+
+    async dispatch(
+        key: string,
+        id: string,
+        runAt: number,
+        // biome-ignore lint/suspicious/noExplicitAny: Data is any serializable value
+        data: any,
+        updateData: boolean,
+        updateRunAt: boolean | string,
+        resetCounts: boolean
+    ): Promise<void> {
+        await (this.redis as ReturnType<typeof createClient>).fCall('queasy_dispatch', {
+            keys: [key],
+            arguments: [
+                id,
+                String(runAt),
+                JSON.stringify(data),
+                String(updateData),
+                String(updateRunAt),
+                String(resetCounts),
+            ],
+        });
+        this.emit('dispatch', key, { id, runAt, data, updateData, updateRunAt, resetCounts });
+    }
+
+    async cancel(key: string, id: string): Promise<boolean> {
+        const result = await (this.redis as ReturnType<typeof createClient>).fCall(
+            'queasy_cancel',
+            {
+                keys: [key],
+                arguments: [id],
+            }
+        );
+        this.emit('cancel', key, id);
+        return result === 1;
+    }
+
+    async dequeue(key: string, count: number): Promise<Job[]> {
+        const now = Date.now();
+        const expiry = now + HEARTBEAT_TIMEOUT;
+        const result = (await (this.redis as ReturnType<typeof createClient>).fCall(
+            'queasy_dequeue',
+            {
+                keys: [key],
+                arguments: [this.clientId, String(now), String(expiry), String(count)],
+            }
+        )) as string[][];
+
+        this.scheduleBump(key);
+
+        const jobs = result.map((jobArray) => parseJob(jobArray)).filter(Boolean) as Job[];
+        for (const job of jobs) this.emit('dequeue', key, job);
+        return jobs;
+    }
+
+    async finish(key: string, jobId: string): Promise<void> {
+        await (this.redis as ReturnType<typeof createClient>).fCall('queasy_finish', {
+            keys: [key],
+            arguments: [jobId, this.clientId, String(Date.now())],
+        });
+        this.emit('finish', key, jobId);
+    }
+
+    async fail(
+        key: string,
+        failkey: string,
+        jobId: string,
+        // biome-ignore lint/suspicious/noExplicitAny: Fail job data is any serializable value
+        failJobData: any
+    ): Promise<void> {
+        await (this.redis as ReturnType<typeof createClient>).fCall('queasy_fail', {
+            keys: [key, failkey],
+            arguments: [
+                jobId,
+                this.clientId,
+                generateId(),
+                JSON.stringify(failJobData),
+                String(Date.now()),
+            ],
+        });
+        this.emit('fail', key, jobId);
+    }
+
+    async retry(key: string, jobId: string, retryAt: number): Promise<void> {
+        await (this.redis as ReturnType<typeof createClient>).fCall('queasy_retry', {
+            keys: [key],
+            arguments: [jobId, this.clientId, String(retryAt), String(Date.now())],
+        });
+        this.emit('retry', key, jobId);
+    }
+}

package/src/constants.ts

@@ -0,0 +1,33 @@
+import type { HandlerOptions, JobUpdateOptions } from './types.ts';
+
+export const DEFAULT_RETRY_OPTIONS: Required<HandlerOptions> = {
+    maxRetries: 10,
+    maxStalls: 3,
+    minBackoff: 2_000,
+    maxBackoff: 300_000, // 5 minutes
+    size: 10,
+    timeout: 60_000, // 1 minute
+    priority: 100,
+};
+
+export const DEFAULT_UPDATE_OPTIONS: Required<JobUpdateOptions> = {
+    updateData: true,
+    updateRunAt: true,
+    resetCounts: false,
+};
+
+export const FAILJOB_RETRY_OPTIONS: Required<HandlerOptions> = {
+    maxRetries: 100,
+    maxStalls: 3,
+    minBackoff: 10_000,
+    maxBackoff: 900_000, // 15 minutes
+    size: 2,
+    timeout: 60_000,
+    priority: 100,
+};
+
+export const LUA_FUNCTIONS_VERSION = '1.0.1';
+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.ts

@@ -0,0 +1,13 @@
+export class PermanentError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'PermanentError';
+    }
+}
+
+export class StallError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'StallError';
+    }
+}

package/src/index.ts

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

package/src/manager.ts

@@ -0,0 +1,78 @@
+import { DEQUEUE_INTERVAL } from './constants.ts';
+import type { Pool } from './pool.ts';
+import type { Queue } from './queue.ts';
+
+interface QueueEntry {
+    queue: Queue;
+    lastDequeuedAt: number;
+    isBusy: boolean;
+}
+
+export class Manager {
+    pool: Pool;
+    queues: QueueEntry[];
+    timer: NodeJS.Timeout | null;
+    busyCount: number;
+
+    constructor(pool: Pool) {
+        this.pool = pool;
+        this.queues = [];
+        this.timer = null;
+        this.busyCount = 0;
+    }
+
+    addQueue(queue: Queue): void {
+        this.queues.unshift({ queue, lastDequeuedAt: 0, isBusy: false });
+        this.busyCount += 1;
+        this.next();
+    }
+
+    async next(): Promise<void> {
+        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();
+        const { count } = await entry.queue.dequeue(batchSize);
+
+        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];
+            const delay = isBusy ? 0 : Math.max(0, lastDequeuedAt - Date.now() + DEQUEUE_INTERVAL);
+            this.timer = setTimeout(() => this.next(), delay);
+        }
+    }
+
+    close(): void {
+        if (this.timer) clearTimeout(this.timer);
+    }
+}
+
+function compareQueueEntries(a: QueueEntry, b: QueueEntry): -1 | 0 | 1 {
+    if (a.isBusy > b.isBusy) return -1;
+    if (a.isBusy < b.isBusy) return 1;
+
+    if (a.queue.handlerOptions!.priority > b.queue.handlerOptions!.priority) return 1;
+    if (a.queue.handlerOptions!.priority < b.queue.handlerOptions!.priority) return -1;
+
+    if (a.lastDequeuedAt > b.lastDequeuedAt) return -1;
+    if (a.lastDequeuedAt < b.lastDequeuedAt) return 1;
+
+    if (a.queue.handlerOptions!.size > b.queue.handlerOptions!.size) return 1;
+    if (a.queue.handlerOptions!.size < b.queue.handlerOptions!.size) return -1;
+
+    return 0;
+}

package/src/pool.ts

@@ -0,0 +1,129 @@
+import { availableParallelism } from 'node:os';
+import { Worker } from 'node:worker_threads';
+import { WORKER_CAPACITY } from './constants.ts';
+import type { DoneMessage, Job } from './types.ts';
+import { generateId } from './utils.ts';
+
+interface WorkerEntry {
+    worker: Worker;
+    capacity: number;
+    id: string;
+    jobCount: number;
+    stalledJobs: Set<string>;
+}
+
+interface JobEntry {
+    resolve: (value: DoneMessage) => void;
+    reject: (reason: DoneMessage) => void;
+    size: number;
+    timer: NodeJS.Timeout;
+}
+
+export class Pool {
+    workers: Set<WorkerEntry>;
+    activeJobs: Map<string, JobEntry>;
+    capacity: number;
+
+    constructor(targetCount?: number | null) {
+        this.workers = new Set();
+        this.activeJobs = new Map();
+        this.capacity = 0;
+
+        const count = targetCount ?? availableParallelism();
+        for (let i = 0; i < count; i++) this.createWorker();
+    }
+
+    createWorker(): void {
+        // Copy file extension from current file so it works in src and dist.
+        const workerFilename = `./worker${import.meta.url.slice(-3)}`;
+        const worker = new Worker(new URL(workerFilename, import.meta.url));
+        const entry: WorkerEntry = {
+            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);
+    }
+
+    handleWorkerMessage(workerEntry: WorkerEntry, message: DoneMessage): void {
+        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 (workerEntry.stalledJobs.has(jobId)) workerEntry.stalledJobs.delete(jobId);
+
+        this.activeJobs.delete(jobId);
+        jobEntry[error ? 'reject' : 'resolve'](message);
+
+        if (!this.workers.has(workerEntry)) this.terminateIfEmpty(workerEntry);
+    }
+
+    handleTimeout(workerEntry: WorkerEntry, jobId: string): void {
+        workerEntry.stalledJobs.add(jobId);
+
+        if (this.workers.delete(workerEntry)) this.createWorker();
+        this.capacity -= workerEntry.capacity;
+
+        this.terminateIfEmpty(workerEntry);
+    }
+
+    async terminateIfEmpty({ stalledJobs, jobCount, worker }: WorkerEntry): Promise<void> {
+        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' },
+            });
+        }
+    }
+
+    process(handlerPath: string, job: Job, size: number, timeout: number): Promise<DoneMessage> {
+        let workerEntry: WorkerEntry | null = 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 });
+        });
+    }
+
+    async close(): Promise<void> {
+        await Promise.all([...this.workers].map(async ({ worker }) => 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();
+    }
+}

package/src/queasy.lua

@@ -226,9 +226,8 @@ local function dequeue(queue_key, client_id, now, expiry, limit)
         table.insert(result, job)
     end
 
-    if #result > 0 then
-        redis.call('ZADD', expiry_key, expiry, client_id)
-    end
+    -- Add this client to queue and bump its expiry
+    redis.call('ZADD', expiry_key, expiry, client_id)
 
     -- Sweep stalled clients
     sweep(queue_key, now)

package/src/queue.ts

@@ -0,0 +1,108 @@
+import type { Client } from './client.ts';
+import { DEFAULT_RETRY_OPTIONS, FAILJOB_RETRY_OPTIONS } from './constants.ts';
+import type { Manager } from './manager.ts';
+import type { Pool } from './pool.ts';
+import type { DoneMessage, HandlerOptions, Job, JobOptions, ListenOptions } from './types.ts';
+import { generateId } from './utils.ts';
+
+export class Queue {
+    key: string;
+    client: Client;
+    pool: Pool | undefined;
+    manager: Manager | undefined;
+    handlerOptions: Required<HandlerOptions> | undefined;
+    handlerPath: string | undefined;
+    failKey: string | undefined;
+
+    constructor(key: string, client: Client, pool: Pool | undefined, manager: Manager | undefined) {
+        this.key = key;
+        this.client = client;
+        this.pool = pool;
+        this.manager = manager;
+        this.handlerOptions = undefined;
+        this.handlerPath = undefined;
+        this.failKey = undefined;
+    }
+
+    async listen(handlerPath: string, options: ListenOptions = {}): Promise<void> {
+        const { failHandler, failRetryOptions, ...retryOptions } = options;
+        if (this.client.disconnected) throw new Error("Can't listen: client disconnected");
+        if (!this.pool || !this.manager) throw new Error("Can't listen: non-processing client");
+
+        this.handlerPath = handlerPath;
+        this.handlerOptions = { ...DEFAULT_RETRY_OPTIONS, ...retryOptions };
+
+        if (failHandler) {
+            this.failKey = `${this.key}-fail`;
+            const failQueue = this.client.queue(this.failKey, true);
+            failQueue.listen(failHandler, { ...FAILJOB_RETRY_OPTIONS, ...failRetryOptions });
+        }
+
+        this.manager.addQueue(this);
+    }
+
+    async dispatch(
+        // biome-ignore lint/suspicious/noExplicitAny: Data is any serializable value
+        data: any,
+        options: JobOptions = {}
+    ): Promise<string> {
+        if (this.client.disconnected) throw new Error("Can't dispatch: client disconnected");
+        const {
+            id = generateId(),
+            runAt = 0,
+            updateData = false,
+            updateRunAt = false,
+            resetCounts = false,
+        } = options;
+
+        await this.client.dispatch(this.key, id, runAt, data, updateData, updateRunAt, resetCounts);
+        return id;
+    }
+
+    async cancel(id: string): Promise<boolean> {
+        if (this.client.disconnected) throw new Error("Can't cancel: client disconnected");
+        return await this.client.cancel(this.key, id);
+    }
+
+    async dequeue(count: number): Promise<{ count: number; promise: Promise<unknown[]> }> {
+        const pool = this.pool!;
+        const handlerPath = this.handlerPath!;
+        const { maxRetries, maxStalls, maxBackoff, minBackoff, size, timeout } =
+            this.handlerOptions!;
+
+        const jobs = await this.client.dequeue(this.key, count);
+
+        const promise = Promise.all(
+            jobs.map(async (job: Job) => {
+                if (job.stallCount >= maxStalls) {
+                    if (!this.failKey) return this.client.finish(this.key, job.id);
+
+                    const failJobData = [job.id, job.data, { message: 'Max stalls exceeded' }];
+                    return this.client.fail(this.key, this.failKey, job.id, failJobData);
+                }
+
+                try {
+                    await pool.process(handlerPath, job, size, timeout);
+                    await this.client.finish(this.key, job.id);
+                } catch (message) {
+                    const { error } = message as Required<DoneMessage>;
+                    const { retryAt = 0, kind } = error;
+
+                    if (kind === 'permanent' || job.retryCount >= maxRetries) {
+                        if (!this.failKey) return this.client.finish(this.key, job.id);
+
+                        const failJobData = [job.id, job.data, error];
+                        return this.client.fail(this.key, this.failKey, job.id, failJobData);
+                    }
+
+                    const backoffUntil =
+                        Date.now() + Math.min(maxBackoff, minBackoff * 2 ** job.retryCount);
+
+                    await this.client.retry(this.key, job.id, Math.max(retryAt, backoffUntil));
+                }
+            })
+        );
+
+        return { count: jobs.length, promise };
+    }
+}

package/src/types.ts

@@ -1,3 +1,18 @@
+import type { RedisClientOptions, RedisClusterOptions } from 'redis';
+
+type SingleNodeOptions = Pick<
+    RedisClientOptions,
+    'url' | 'socket' | 'username' | 'password' | 'database'
+>;
+
+export type RedisOptions =
+    | SingleNodeOptions
+    | {
+          rootNodes: SingleNodeOptions[];
+          defaults?: Partial<SingleNodeOptions>;
+          nodeAddressMap?: RedisClusterOptions['nodeAddressMap'];
+      };
+
 /**
  * Core job identification and data
  */
@@ -77,6 +92,7 @@ export interface ListenOptions extends HandlerOptions {
 export type ExecMessage = {
     op: 'exec';
     queue: string;
+    handlerPath: string;
     job: Job;
 };
 

package/src/{utils.js → utils.ts}

@@ -1,9 +1,4 @@
-/**
- * Generate a random alphanumeric ID
- * @param {number} length - Length of the ID
- * @returns {string}
- */
-export function generateId(length = 20) {
+export function generateId(length = 20): string {
     const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
     let id = '';
     for (let i = 0; i < length; i++) {
@@ -12,25 +7,13 @@ export function generateId(length = 20) {
     return id;
 }
 
-/**
- * Parse a semver string like '1.0' into { major, minor }
- * Used by compareSemver
- * @param {string?} version
- * @returns {number[]}
- */
-export function parseVersion(version) {
+export function parseVersion(version: string | null | undefined): number[] {
     const parsed = String(version).split('.').map(Number);
     if (parsed.some((n) => Number.isNaN(n))) return [0];
     return parsed;
 }
 
-/**
- * Compare two semver strings. Returns -1 if a < b, 0 if equal, 1 if a > b.
- * @param {number[]} a
- * @param {number[]} b
- * @returns {-1 | 0 | 1}
- */
-export function compareSemver(a, b) {
+export function compareSemver(a: number[], b: number[]): -1 | 0 | 1 {
     for (let i = 0; i < Math.min(a.length, b.length); i++) {
         if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
     }