@platformatic/job-queue 0.0.1 → 0.1.0-alpha.3

package/dist/storage/redis.js

@@ -0,0 +1,317 @@
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { EventEmitter } from 'node:events';
+import { Redis } from 'iovalkey';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Redis/Valkey storage implementation
+ */
+export class RedisStorage {
+    #url;
+    #keyPrefix;
+    #client = null;
+    #blockingClient = null; // Single blocking client for BLMOVE
+    #subscriber = null;
+    #scriptSHAs = null;
+    #eventEmitter = new EventEmitter({ captureRejections: true });
+    #notifyEmitter = new EventEmitter({ captureRejections: true });
+    #eventSubscription = false;
+    constructor(config = {}) {
+        this.#url = config.url ?? process.env.REDIS_URL ?? 'redis://localhost:6379';
+        this.#keyPrefix = config.keyPrefix ?? 'jq:';
+        // Disable max listeners warning for high-throughput scenarios
+        this.#eventEmitter.setMaxListeners(0);
+        this.#notifyEmitter.setMaxListeners(0);
+    }
+    // Key helpers
+    #key(name) {
+        return `${this.#keyPrefix}${name}`;
+    }
+    #jobsKey() {
+        return this.#key('jobs');
+    }
+    #queueKey() {
+        return this.#key('queue');
+    }
+    #processingKey(workerId) {
+        return this.#key(`processing:${workerId}`);
+    }
+    #resultsKey() {
+        return this.#key('results');
+    }
+    #errorsKey() {
+        return this.#key('errors');
+    }
+    #workersKey() {
+        return this.#key('workers');
+    }
+    #reaperLockKey() {
+        return this.#key('reaper:lock');
+    }
+    async connect() {
+        if (this.#client)
+            return;
+        this.#client = new Redis(this.#url);
+        this.#subscriber = new Redis(this.#url);
+        this.#blockingClient = new Redis(this.#url);
+        // Load Lua scripts
+        await this.#loadScripts();
+        // Set up pub/sub message handler
+        this.#subscriber.on('message', (channel, message) => {
+            this.#handlePubSubMessage(channel, message);
+        });
+        this.#subscriber.on('pmessage', (_pattern, channel, message) => {
+            this.#handlePubSubMessage(channel, message);
+        });
+    }
+    async disconnect() {
+        if (this.#subscriber) {
+            this.#subscriber.disconnect();
+            this.#subscriber = null;
+        }
+        if (this.#blockingClient) {
+            this.#blockingClient.disconnect();
+            this.#blockingClient = null;
+        }
+        if (this.#client) {
+            this.#client.disconnect();
+            this.#client = null;
+        }
+        this.#eventEmitter.removeAllListeners();
+        this.#notifyEmitter.removeAllListeners();
+        this.#eventSubscription = false;
+    }
+    async #loadScripts() {
+        const scriptsDir = join(__dirname, '..', '..', 'redis-scripts');
+        const enqueueScript = readFileSync(join(scriptsDir, 'enqueue.lua'), 'utf8');
+        const completeScript = readFileSync(join(scriptsDir, 'complete.lua'), 'utf8');
+        const failScript = readFileSync(join(scriptsDir, 'fail.lua'), 'utf8');
+        const retryScript = readFileSync(join(scriptsDir, 'retry.lua'), 'utf8');
+        const cancelScript = readFileSync(join(scriptsDir, 'cancel.lua'), 'utf8');
+        const renewLeaderLockScript = readFileSync(join(scriptsDir, 'renew-leader-lock.lua'), 'utf8');
+        const releaseLeaderLockScript = readFileSync(join(scriptsDir, 'release-leader-lock.lua'), 'utf8');
+        const [enqueue, complete, fail, retry, cancel, renewLeaderLock, releaseLeaderLock] = await Promise.all([
+            this.#client.script('LOAD', enqueueScript),
+            this.#client.script('LOAD', completeScript),
+            this.#client.script('LOAD', failScript),
+            this.#client.script('LOAD', retryScript),
+            this.#client.script('LOAD', cancelScript),
+            this.#client.script('LOAD', renewLeaderLockScript),
+            this.#client.script('LOAD', releaseLeaderLockScript)
+        ]);
+        this.#scriptSHAs = { enqueue, complete, fail, retry, cancel, renewLeaderLock, releaseLeaderLock };
+    }
+    #notifyChannelPrefix() {
+        return `${this.#keyPrefix}notify:`;
+    }
+    #eventsChannel() {
+        return `${this.#keyPrefix}events`;
+    }
+    #handlePubSubMessage(channel, message) {
+        const notifyPrefix = this.#notifyChannelPrefix();
+        const eventsChannel = this.#eventsChannel();
+        // Job notification (prefix:notify:jobId)
+        if (channel.startsWith(notifyPrefix)) {
+            const jobId = channel.substring(notifyPrefix.length);
+            this.#notifyEmitter.emit(`notify:${jobId}`, message);
+            return;
+        }
+        // Job events (prefix:events)
+        if (channel === eventsChannel) {
+            const [id, event] = message.split(':');
+            this.#eventEmitter.emit('event', id, event);
+        }
+    }
+    async enqueue(id, message, timestamp) {
+        const state = `queued:${timestamp}`;
+        const result = await this.#client.evalsha(this.#scriptSHAs.enqueue, 2, this.#jobsKey(), this.#queueKey(), id, message, state);
+        // If this is a new job (not duplicate), publish the queued event
+        if (result === null) {
+            await this.publishEvent(id, 'queued');
+        }
+        return result;
+    }
+    async dequeue(workerId, timeout) {
+        // BLMOVE: blocking move from queue to processing queue
+        // A single blocking client can handle multiple concurrent BLMOVE calls -
+        // iovalkey multiplexes them and Redis queues them internally.
+        const result = await this.#blockingClient.blmove(this.#queueKey(), this.#processingKey(workerId), 'LEFT', 'RIGHT', timeout);
+        return result ? Buffer.from(result) : null;
+    }
+    async requeue(id, message, workerId) {
+        // Remove from processing queue and add to front of main queue
+        await this.#client.lrem(this.#processingKey(workerId), 1, message);
+        await this.#client.lpush(this.#queueKey(), message);
+    }
+    async ack(id, message, workerId) {
+        await this.#client.lrem(this.#processingKey(workerId), 1, message);
+    }
+    async getJobState(id) {
+        const state = await this.#client.hget(this.#jobsKey(), id);
+        return state;
+    }
+    async setJobState(id, state) {
+        await this.#client.hset(this.#jobsKey(), id, state);
+    }
+    async deleteJob(id) {
+        const result = await this.#client.evalsha(this.#scriptSHAs.cancel, 1, this.#jobsKey(), id);
+        return result === 1;
+    }
+    async getJobStates(ids) {
+        if (ids.length === 0) {
+            return new Map();
+        }
+        const states = await this.#client.hmget(this.#jobsKey(), ...ids);
+        const result = new Map();
+        for (let i = 0; i < ids.length; i++) {
+            result.set(ids[i], states[i]);
+        }
+        return result;
+    }
+    async setResult(id, result, ttlMs) {
+        await this.#client.hset(this.#resultsKey(), id, result);
+        // Note: HEXPIRE is not widely supported, so we set TTL on the whole hash
+        // For production, consider using separate keys per result
+    }
+    async getResult(id) {
+        const result = await this.#client.hgetBuffer(this.#resultsKey(), id);
+        return result;
+    }
+    async setError(id, error, ttlMs) {
+        await this.#client.hset(this.#errorsKey(), id, error);
+    }
+    async getError(id) {
+        const result = await this.#client.hgetBuffer(this.#errorsKey(), id);
+        return result;
+    }
+    async registerWorker(workerId, ttlMs) {
+        await this.#client.hset(this.#workersKey(), workerId, Date.now().toString());
+        // Set expiry on the worker entry
+        await this.#client.pexpire(this.#workersKey(), ttlMs);
+    }
+    async refreshWorker(workerId, ttlMs) {
+        await this.registerWorker(workerId, ttlMs);
+    }
+    async unregisterWorker(workerId) {
+        if (!this.#client)
+            return;
+        await this.#client.hdel(this.#workersKey(), workerId);
+        // Also clear the processing queue
+        await this.#client.del(this.#processingKey(workerId));
+    }
+    async getWorkers() {
+        const workers = await this.#client.hkeys(this.#workersKey());
+        return workers;
+    }
+    async getProcessingJobs(workerId) {
+        const jobs = await this.#client.lrangeBuffer(this.#processingKey(workerId), 0, -1);
+        return jobs;
+    }
+    async subscribeToJob(id, handler) {
+        const eventName = `notify:${id}`;
+        this.#notifyEmitter.on(eventName, handler);
+        // Subscribe to the job notification channel
+        const channel = `${this.#notifyChannelPrefix()}${id}`;
+        await this.#subscriber.subscribe(channel);
+        return async () => {
+            this.#notifyEmitter.off(eventName, handler);
+            await this.#subscriber.unsubscribe(channel);
+        };
+    }
+    async notifyJobComplete(id, status) {
+        const channel = `${this.#notifyChannelPrefix()}${id}`;
+        await this.#client.publish(channel, status);
+    }
+    async subscribeToEvents(handler) {
+        this.#eventEmitter.on('event', handler);
+        if (!this.#eventSubscription) {
+            await this.#subscriber.subscribe(this.#eventsChannel());
+            this.#eventSubscription = true;
+        }
+        return async () => {
+            this.#eventEmitter.off('event', handler);
+        };
+    }
+    async publishEvent(id, event) {
+        await this.#client.publish(this.#eventsChannel(), `${id}:${event}`);
+    }
+    async completeJob(id, message, workerId, result, resultTtlMs) {
+        const timestamp = Date.now();
+        const state = `completed:${timestamp}`;
+        await this.#client.evalsha(this.#scriptSHAs.complete, 3, this.#jobsKey(), this.#resultsKey(), this.#processingKey(workerId), id, message, state, result, resultTtlMs.toString());
+        // Notify subscribers and publish event
+        await this.notifyJobComplete(id, 'completed');
+        await this.publishEvent(id, 'completed');
+    }
+    async failJob(id, message, workerId, error, errorTtlMs) {
+        const timestamp = Date.now();
+        const state = `failed:${timestamp}`;
+        await this.#client.evalsha(this.#scriptSHAs.fail, 3, this.#jobsKey(), this.#errorsKey(), this.#processingKey(workerId), id, message, state, error, errorTtlMs.toString());
+        // Notify subscribers and publish event
+        await this.notifyJobComplete(id, 'failed');
+        await this.publishEvent(id, 'failed');
+    }
+    async retryJob(id, message, workerId, attempts) {
+        const timestamp = Date.now();
+        const state = `failing:${timestamp}:${attempts}`;
+        // Get the old message from processing queue to remove it
+        const processingJobs = await this.getProcessingJobs(workerId);
+        let oldMessage = null;
+        // Find the message with matching job id
+        for (const job of processingJobs) {
+            try {
+                const parsed = JSON.parse(job.toString());
+                if (parsed.id === id) {
+                    oldMessage = job;
+                    break;
+                }
+            }
+            catch {
+                // Ignore parse errors
+            }
+        }
+        if (oldMessage) {
+            await this.#client.evalsha(this.#scriptSHAs.retry, 3, this.#jobsKey(), this.#queueKey(), this.#processingKey(workerId), id, message, oldMessage, state);
+        }
+        else {
+            // Fallback: just set state and push new message
+            await this.setJobState(id, state);
+            await this.#client.lpush(this.#queueKey(), message);
+            await this.notifyJobComplete(id, 'failing');
+            await this.publishEvent(id, 'failing');
+        }
+    }
+    /**
+     * Clear all data (useful for testing)
+     */
+    async clear() {
+        // If not connected, nothing to clear
+        if (!this.#client) {
+            return;
+        }
+        const keys = await this.#client.keys(`${this.#keyPrefix}*`);
+        if (keys.length > 0) {
+            await this.#client.del(...keys);
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════
+    // LEADER ELECTION
+    // ═══════════════════════════════════════════════════════════════════
+    async acquireLeaderLock(lockKey, ownerId, ttlMs) {
+        // SET NX PX: Set only if Not eXists, with PX milliseconds expiry
+        const result = await this.#client.set(this.#key(lockKey), ownerId, 'PX', ttlMs, 'NX');
+        return result === 'OK';
+    }
+    async renewLeaderLock(lockKey, ownerId, ttlMs) {
+        const result = await this.#client.evalsha(this.#scriptSHAs.renewLeaderLock, 1, this.#key(lockKey), ownerId, ttlMs.toString());
+        return result === 1;
+    }
+    async releaseLeaderLock(lockKey, ownerId) {
+        if (!this.#client)
+            return false;
+        const result = await this.#client.evalsha(this.#scriptSHAs.releaseLeaderLock, 1, this.#key(lockKey), ownerId);
+        return result === 1;
+    }
+}
+//# sourceMappingURL=redis.js.map

package/dist/storage/redis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.js","sourceRoot":"","sources":["../../src/storage/redis.ts"],"names":[],"mappings":"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"}

package/dist/storage/types.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Storage interface for pluggable backends
+ */
+export interface Storage {
+    /**
+     * Initialize the storage connection.
+     * Called once when Queue.start() is invoked.
+     */
+    connect(): Promise<void>;
+    /**
+     * Close the storage connection gracefully.
+     * Called when Queue.stop() is invoked.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Atomically enqueue a job if not already present.
+     * Must check for duplicates and set initial state in one atomic operation.
+     *
+     * @returns null if job was enqueued, existing state string if duplicate
+     */
+    enqueue(id: string, message: Buffer, timestamp: number): Promise<string | null>;
+    /**
+     * Blocking dequeue: move a job from main queue to worker's processing queue.
+     * Should block up to `timeout` seconds if queue is empty.
+     *
+     * @returns The job message, or null if timeout
+     */
+    dequeue(workerId: string, timeout: number): Promise<Buffer | null>;
+    /**
+     * Move a job from worker's processing queue back to main queue.
+     * Used for retries and stall recovery.
+     */
+    requeue(id: string, message: Buffer, workerId: string): Promise<void>;
+    /**
+     * Remove a job from worker's processing queue (after completion or failure).
+     */
+    ack(id: string, message: Buffer, workerId: string): Promise<void>;
+    /**
+     * Get the current state of a job.
+     * State format: "status:timestamp[:workerId]"
+     *
+     * @returns State string, or null if job doesn't exist
+     */
+    getJobState(id: string): Promise<string | null>;
+    /**
+     * Set the state of a job.
+     * Should also publish a notification for state changes.
+     */
+    setJobState(id: string, state: string): Promise<void>;
+    /**
+     * Delete a job from the jobs registry.
+     * Used for cancellation.
+     *
+     * @returns true if job existed and was deleted
+     */
+    deleteJob(id: string): Promise<boolean>;
+    /**
+     * Get multiple job states in one call (batch operation).
+     */
+    getJobStates(ids: string[]): Promise<Map<string, string | null>>;
+    /**
+     * Store a job result with TTL.
+     */
+    setResult(id: string, result: Buffer, ttlMs: number): Promise<void>;
+    /**
+     * Retrieve a stored job result.
+     *
+     * @returns Result buffer, or null if not found/expired
+     */
+    getResult(id: string): Promise<Buffer | null>;
+    /**
+     * Store a job error with TTL.
+     */
+    setError(id: string, error: Buffer, ttlMs: number): Promise<void>;
+    /**
+     * Retrieve a stored job error.
+     */
+    getError(id: string): Promise<Buffer | null>;
+    /**
+     * Register a worker as active.
+     * Should set a TTL so crashed workers are automatically removed.
+     */
+    registerWorker(workerId: string, ttlMs: number): Promise<void>;
+    /**
+     * Refresh worker registration (heartbeat).
+     */
+    refreshWorker(workerId: string, ttlMs: number): Promise<void>;
+    /**
+     * Unregister a worker (graceful shutdown).
+     */
+    unregisterWorker(workerId: string): Promise<void>;
+    /**
+     * Get list of all registered workers.
+     */
+    getWorkers(): Promise<string[]>;
+    /**
+     * Get all jobs in a worker's processing queue.
+     * Used by reaper to find stalled jobs.
+     */
+    getProcessingJobs(workerId: string): Promise<Buffer[]>;
+    /**
+     * Subscribe to notifications for a specific job.
+     * Used by enqueueAndWait to receive completion notification.
+     *
+     * @param id - Job ID to subscribe to
+     * @param handler - Called when notification received
+     * @returns Unsubscribe function
+     */
+    subscribeToJob(id: string, handler: (status: 'completed' | 'failed' | 'failing') => void): Promise<() => Promise<void>>;
+    /**
+     * Publish a job completion/failure notification.
+     * Called by worker after job finishes or is retried.
+     */
+    notifyJobComplete(id: string, status: 'completed' | 'failed' | 'failing'): Promise<void>;
+    /**
+     * Subscribe to all job state change events.
+     * Used by reaper and monitoring.
+     *
+     * @returns Unsubscribe function
+     */
+    subscribeToEvents(handler: (id: string, event: string) => void): Promise<() => Promise<void>>;
+    /**
+     * Publish a job state change event.
+     */
+    publishEvent(id: string, event: string): Promise<void>;
+    /**
+     * Try to acquire the reaper leader lock.
+     * Uses SET NX PX pattern for atomic acquisition.
+     *
+     * @param lockKey - The lock key name
+     * @param ownerId - Unique identifier for this reaper instance
+     * @param ttlMs - Lock TTL in milliseconds
+     * @returns true if lock was acquired, false if already held by another
+     */
+    acquireLeaderLock?(lockKey: string, ownerId: string, ttlMs: number): Promise<boolean>;
+    /**
+     * Renew the leader lock if still owned by this reaper.
+     * Extends the TTL atomically only if the current owner matches.
+     *
+     * @param lockKey - The lock key name
+     * @param ownerId - Unique identifier for this reaper instance
+     * @param ttlMs - New TTL in milliseconds
+     * @returns true if lock was renewed, false if not owned
+     */
+    renewLeaderLock?(lockKey: string, ownerId: string, ttlMs: number): Promise<boolean>;
+    /**
+     * Release the leader lock if owned by this reaper.
+     * Deletes the lock atomically only if the current owner matches.
+     *
+     * @param lockKey - The lock key name
+     * @param ownerId - Unique identifier for this reaper instance
+     * @returns true if lock was released, false if not owned
+     */
+    releaseLeaderLock?(lockKey: string, ownerId: string): Promise<boolean>;
+    /**
+     * Atomically complete a job:
+     * - Set state to completed
+     * - Store result
+     * - Remove from processing queue
+     * - Publish notification
+     */
+    completeJob(id: string, message: Buffer, workerId: string, result: Buffer, resultTtlMs: number): Promise<void>;
+    /**
+     * Atomically fail a job:
+     * - Set state to failed
+     * - Store error
+     * - Remove from processing queue
+     * - Publish notification
+     */
+    failJob(id: string, message: Buffer, workerId: string, error: Buffer, errorTtlMs: number): Promise<void>;
+    /**
+     * Atomically retry a job:
+     * - Set state to failing
+     * - Move from processing queue to main queue
+     * - Publish event
+     */
+    retryJob(id: string, message: Buffer, workerId: string, attempts: number): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/storage/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"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"}

package/dist/storage/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/storage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -0,0 +1,126 @@
+import type { Storage } from './storage/types.ts';
+import type { Serde } from './serde/index.ts';
+/**
+ * Message stored in the queue
+ */
+export interface QueueMessage<TPayload> {
+    id: string;
+    payload: TPayload;
+    createdAt: number;
+    attempts: number;
+    maxAttempts: number;
+    correlationId?: string;
+}
+/**
+ * Job state in the jobs registry
+ */
+export type MessageState = 'queued' | 'processing' | 'failing' | 'completed' | 'failed';
+/**
+ * Serialized error information
+ */
+export interface SerializedError {
+    message: string;
+    code?: string;
+    stack?: string;
+}
+/**
+ * Job status with metadata
+ */
+export interface MessageStatus<TResult = unknown> {
+    id: string;
+    state: MessageState;
+    createdAt: number;
+    attempts: number;
+    result?: TResult;
+    error?: SerializedError;
+}
+/**
+ * Options for enqueue operation
+ */
+export interface EnqueueOptions {
+    maxAttempts?: number;
+}
+/**
+ * Options for enqueueAndWait operation
+ */
+export interface EnqueueAndWaitOptions extends EnqueueOptions {
+    timeout?: number;
+}
+/**
+ * Result of enqueue operation
+ */
+export type EnqueueResult<TResult = unknown> = {
+    status: 'queued';
+} | {
+    status: 'duplicate';
+    existingState: MessageState;
+} | {
+    status: 'completed';
+    result: TResult;
+};
+/**
+ * Result of cancel operation
+ */
+export type CancelResult = {
+    status: 'cancelled';
+} | {
+    status: 'not_found';
+} | {
+    status: 'processing';
+} | {
+    status: 'completed';
+};
+/**
+ * Job passed to the handler
+ */
+export interface Job<TPayload> {
+    id: string;
+    payload: TPayload;
+    attempts: number;
+    signal: AbortSignal;
+}
+/**
+ * Job handler function
+ */
+export type JobHandler<TPayload, TResult> = ((job: Job<TPayload>) => Promise<TResult>) | ((job: Job<TPayload>, callback: (err: Error | null, result?: TResult) => void) => void);
+/**
+ * Queue configuration
+ */
+export interface QueueConfig<TPayload, TResult> {
+    /** Storage backend (required) */
+    storage: Storage;
+    /** Payload serializer (default: JSON) */
+    payloadSerde?: Serde<TPayload>;
+    /** Result serializer (default: JSON) */
+    resultSerde?: Serde<TResult>;
+    /** Unique worker ID (default: random UUID) */
+    workerId?: string;
+    /** Parallel job processing (default: 1) */
+    concurrency?: number;
+    /** Blocking dequeue timeout in seconds (default: 5) */
+    blockTimeout?: number;
+    /** Default max retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Max processing time before job is considered stalled in ms (default: 30000) */
+    visibilityTimeout?: number;
+    /** TTL for processing queue keys in ms (default: 604800000 = 7 days) */
+    processingQueueTTL?: number;
+    /** TTL for stored results and errors in ms (default: 3600000 = 1 hour) */
+    resultTTL?: number;
+}
+/**
+ * Queue events (tuple format for EventEmitter)
+ */
+export interface QueueEvents<TResult> {
+    started: [];
+    stopped: [];
+    error: [error: Error];
+    enqueued: [id: string];
+    completed: [id: string, result: TResult];
+    failed: [id: string, error: Error];
+    failing: [id: string, error: Error, attempt: number];
+    requeued: [id: string];
+    cancelled: [id: string];
+    stalled: [id: string];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map