@elysiumjs/heracles 0.4.3 → 0.5.0

package/dist/transports/redis.transport.d.ts

@@ -0,0 +1,251 @@
+import type { JobStatusInfo, Transport, TransportEvent, TransportMode } from '../transport';
+import { InteractsWithConsole } from '@elysiumjs/core';
+/**
+ * Redis transport configuration options
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type RedisTransportOptions = {
+    /**
+     * Redis connection name.
+     * If not provided, uses the default connection.
+     */
+    connection?: string;
+    /**
+     * Prefix for all Redis keys used by this transport.
+     * @default 'elysium:heracles'
+     */
+    keyPrefix?: string;
+    /**
+     * Group name for Redis consumer groups.
+     * @default 'workers'
+     */
+    consumerGroup?: string;
+    /**
+     * Consumer name for this instance in the consumer group.
+     * If not provided, a random name will be generated.
+     */
+    consumerName?: string;
+    /**
+     * How often to poll Redis for new messages (in milliseconds).
+     * @default 1000
+     */
+    pollInterval?: number;
+    /**
+     * Maximum number of messages to read in a single poll.
+     * @default 10
+     */
+    batchSize?: number;
+    /**
+     * Time to live for job status information (in seconds).
+     * @default 86400 (24 hours)
+     */
+    statusTTL?: number;
+    /**
+     * Whether to automatically clean up completed and failed jobs from streams.
+     * @default true
+     */
+    cleanupCompletedJobs?: boolean;
+    /**
+     * How long to retain completed jobs in the stream before cleanup (in seconds).
+     * @default 3600 (1 hour)
+     */
+    completedJobRetention?: number;
+    /**
+     * Maximum number of entries to keep in each stream.
+     * @default 1000
+     */
+    maxStreamSize?: number;
+};
+/**
+ * Transport implementation using Redis streams for distributed job processing.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class RedisTransport extends InteractsWithConsole implements Transport {
+    /**
+     * Redis client instance.
+     */
+    private client;
+    /**
+     * Options for this transport.
+     */
+    private options;
+    /**
+     * Mode this transport is operating in.
+     */
+    private mode;
+    /**
+     * Registered message handlers.
+     */
+    private messageHandlers;
+    /**
+     * Timer for polling Redis in consumer mode.
+     */
+    private pollTimer?;
+    /**
+     * Timer for stream cleanup.
+     */
+    private cleanupTimer?;
+    /**
+     * Last processed message IDs by stream.
+     */
+    private lastIds;
+    /**
+     * Whether to check the logs instead of new messages.
+     */
+    private checkLogs;
+    /**
+     * Consumer ID for this instance.
+     */
+    private consumerId;
+    /**
+     * Whether the consumer group has been created for each stream.
+     */
+    private consumerGroupCreated;
+    /**
+     * Map of message IDs to completed status for tracking completed jobs.
+     */
+    private completedMessageIds;
+    /**
+     * Map to track locks on job IDs for NO_OVERLAP jobs.
+     */
+    private jobLocks;
+    /**
+     * Create a new Redis transport.
+     */
+    constructor(mode: TransportMode, options?: RedisTransportOptions);
+    /**
+     * Helper method to execute Redis commands with proper type conversion
+     * @param command Redis command
+     * @param args Command arguments
+     * @returns Redis response
+     */
+    private redisCommand;
+    /**
+     * Finds job message ID in the stream by job ID
+     * @param jobId The job ID to find
+     * @param queueName The queue to search in
+     * @returns The message ID if found, null otherwise
+     */
+    private findJobMessageId;
+    /**
+     * Start the transport
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the transport
+     */
+    stop(): Promise<void>;
+    /**
+     * Send a message through the transport
+     */
+    send(message: TransportEvent): Promise<void>;
+    /**
+     * Register a callback to handle messages
+     */
+    onMessage(handler: (message: TransportEvent) => void | Promise<void>): void;
+    /**
+     * Gets the current status of a job.
+     */
+    getJobStatus(jobId: string, dispatchId: string, queueName: string): Promise<JobStatusInfo>;
+    /**
+     * Updates a job's status directly in Redis without creating a new message.
+     *
+     * @param jobId The ID of the job to update
+     * @param queueName The queue the job belongs to
+     * @param updates The status updates to apply
+     */
+    updateJobStatus(jobId: string, dispatchId: string, queueName: string, updates: Partial<JobStatusInfo>): Promise<void>;
+    /**
+     * Register a worker with this transport
+     */
+    registerWorker(workerId: string, queues: string[]): Promise<void>;
+    /**
+     * Unregister a worker from this transport
+     */
+    unregisterWorker(workerId: string): Promise<void>;
+    /**
+     * Start polling Redis for messages
+     */
+    private startPolling;
+    /**
+     * Poll for new messages
+     */
+    private pollMessages;
+    /**
+     * Process messages from Redis stream
+     */
+    private processMessages;
+    /**
+     * Get all registered queues
+     */
+    private getRegisteredQueues;
+    /**
+     * Ensure a stream exists
+     */
+    private ensureStreamExists;
+    /**
+     * Ensure a consumer group exists for a stream
+     */
+    private ensureConsumerGroupExists;
+    /**
+     * Store job status in Redis
+     */
+    private storeJobStatus;
+    /**
+     * Serialize a message for Redis
+     */
+    private serializeMessage;
+    /**
+     * Deserialize a message from Redis
+     */
+    private deserializeMessage;
+    /**
+     * Get Redis key for a stream
+     */
+    private getStreamKey;
+    /**
+     * Get Redis key for job status
+     */
+    private getJobStatusKey;
+    /**
+     * Get Redis key for worker status
+     */
+    private getWorkerKey;
+    /**
+     * Track completed message for later cleanup
+     */
+    private trackCompletedMessage;
+    /**
+     * Schedule periodic stream cleanup
+     */
+    private scheduleStreamCleanup;
+    /**
+     * Find expired message IDs for cleanup
+     */
+    private cleanupStreams;
+    /**
+     * Trim all streams to the maximum configured size
+     */
+    private trimStreamsToMaxSize;
+    /**
+     * Check if a job with the same ID is currently locked
+     * @param jobId The job ID to check
+     * @param queue The queue name
+     * @returns True if the job is locked, false otherwise
+     */
+    isJobLocked(jobId: string, queue: string): Promise<boolean>;
+    /**
+     * Acquire a lock for a job ID
+     * @param jobId The job ID to lock
+     * @param queue The queue name
+     * @param duration Duration in milliseconds to lock the job
+     * @returns True if lock was acquired, false otherwise
+     */
+    acquireJobLock(jobId: string, queue: string, duration?: number): Promise<boolean>;
+    /**
+     * Release a lock for a job ID
+     * @param jobId The job ID to unlock
+     * @param queue The queue name
+     */
+    releaseJobLock(jobId: string, queue: string): Promise<void>;
+}

package/dist/utils.d.ts

@@ -0,0 +1,34 @@
+import type { Job, JobClass, JobMetadata } from './job';
+export declare namespace Symbols {
+    /**
+     * Symbol for job metadata
+     */
+    const job: unique symbol;
+    /**
+     * Symbol for queue metadata
+     */
+    const queue: unique symbol;
+    /**
+     * Symbol for worker metadata
+     */
+    const worker: unique symbol;
+    /**
+     * Symbol for transport metadata
+     */
+    const transport: unique symbol;
+    /**
+     * Symbol for job transaction data
+     */
+    const jobTransaction: unique symbol;
+    /**
+     * Symbol for worker pool metadata
+     */
+    const workerPool: unique symbol;
+}
+/**
+ * Get job metadata from a job class
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param jobClass The job class
+ * @returns The job metadata or null if not found
+ */
+export declare const getJobMetadata: <T extends Job>(jobClass: JobClass<T>) => JobMetadata | null;

package/dist/worker.d.ts

@@ -0,0 +1,250 @@
+import type { Job, JobOverlapBehavior } from './job';
+import type { QueueOptions } from './queue';
+/**
+ * Represents a job in the queue with its metadata.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type QueuedJob = {
+    /**
+     * The job instance.
+     */
+    job: Job;
+    /**
+     * The number of times this job has been retried.
+     */
+    retries: number;
+    /**
+     * The queue this job belongs to.
+     */
+    queueName: string;
+    /**
+     * When the job was added to the queue.
+     */
+    enqueuedAt: Date;
+    /**
+     * When the job is scheduled to be processed.
+     * This is used for delayed jobs or retry scheduling.
+     */
+    scheduledFor?: Date;
+    /**
+     * Priority of this job (lower number = higher priority).
+     * @see JobDispatchOptions.priority
+     */
+    priority?: number;
+    /**
+     * Maximum number of retries for this specific job.
+     * Overrides queue-level setting if specified.
+     * @see JobDispatchOptions.maxRetries
+     */
+    maxRetries?: number;
+    /**
+     * Delay between retries in milliseconds for this specific job.
+     * Overrides queue-level setting if specified.
+     * @see JobDispatchOptions.retryDelay
+     */
+    retryDelay?: number;
+    /**
+     * Defines how the job handles overlap with other instances of the same job ID.
+     * @see JobOverlapBehavior
+     */
+    overlapBehavior?: JobOverlapBehavior;
+    /**
+     * When using NO_OVERLAP behavior, specifies the delay in milliseconds
+     * between sequential executions of jobs with the same ID.
+     */
+    overlapDelay?: number;
+};
+/**
+ * Options for worker queues.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WorkerQueueOptions = Omit<QueueOptions, 'transport'>;
+/**
+ * State associated with a job queue managed by a worker.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type QueueState = {
+    /**
+     * The queue configuration options.
+     */
+    options: WorkerQueueOptions;
+    /**
+     * The jobs waiting to be processed.
+     */
+    jobs: QueuedJob[];
+    /**
+     * The jobs currently being processed.
+     */
+    activeJobs: Map<string, QueuedJob>;
+    /**
+     * The number of jobs currently being processed.
+     */
+    processing: number;
+    /**
+     * Whether the queue is currently paused.
+     */
+    paused: boolean;
+    /**
+     * Whether the queue is currently being drained (completing existing jobs but not accepting new ones).
+     */
+    draining: boolean;
+};
+/**
+ * Worker status information.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare enum WorkerStatus {
+    /**
+     * Worker is idle - no jobs are being processed.
+     */
+    IDLE = "idle",
+    /**
+     * Worker is active - processing jobs.
+     */
+    ACTIVE = "active",
+    /**
+     * Worker is paused - not accepting new jobs.
+     */
+    PAUSED = "paused",
+    /**
+     * Worker is draining - completing current jobs but not accepting new ones.
+     */
+    DRAINING = "draining",
+    /**
+     * Worker is stopping - gracefully shutting down.
+     */
+    STOPPING = "stopping",
+    /**
+     * Worker is stopped - no longer processing jobs.
+     */
+    STOPPED = "stopped",
+    /**
+     * Worker is disconnected - lost connection.
+     */
+    DISCONNECTED = "disconnected"
+}
+/**
+ * Worker information used by the worker pool.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WorkerInfo = {
+    /**
+     * The worker ID.
+     */
+    id: string;
+    /**
+     * The worker status.
+     */
+    status: WorkerStatus;
+    /**
+     * The queues handled by this worker.
+     */
+    queues: string[];
+    /**
+     * The jobs being processed by this worker.
+     */
+    activeJobs: number;
+    /**
+     * The transport used by this worker.
+     */
+    transport: string;
+    /**
+     * Start time of this worker.
+     */
+    startedAt: Date;
+    /**
+     * Add a job to this worker.
+     */
+    addJob(job: Job, queueName?: string): Promise<boolean>;
+    /**
+     * Cancel a job on this worker.
+     */
+    cancelJob(jobId: string, queueName?: string): Promise<boolean>;
+    /**
+     * Cancel all jobs on this worker.
+     */
+    cancelAllJobs(queueName?: string): Promise<number>;
+};
+/**
+ * Standardized interface for a worker managing job queues.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface Worker {
+    /**
+     * The worker ID.
+     */
+    id: string;
+    /**
+     * The worker status.
+     */
+    status: WorkerStatus;
+    /**
+     * Create a new queue with the specified options.
+     */
+    createQueue(options: QueueOptions): Promise<Worker>;
+    /**
+     * Add a job to a queue.
+     */
+    addJob(job: Job, queueName?: string): Promise<Worker>;
+    /**
+     * Pause a queue to stop processing new jobs.
+     */
+    pause(queueName?: string): Promise<Worker>;
+    /**
+     * Resume a paused queue.
+     */
+    resume(queueName?: string): Promise<Worker>;
+    /**
+     * Drain a queue - complete current jobs but don't accept new ones.
+     */
+    drain(queueName?: string): Promise<Worker>;
+    /**
+     * Clear all jobs from a queue.
+     */
+    clear(queueName?: string): Promise<Worker>;
+    /**
+     * Get the number of jobs in a queue.
+     */
+    size(queueName?: string): Promise<number>;
+    /**
+     * Get the total number of jobs across all queues.
+     */
+    totalSize(): Promise<number>;
+    /**
+     * Get statistics about all queues.
+     */
+    getStats(): Promise<Record<string, {
+        waiting: number;
+        processing: number;
+        paused: boolean;
+        draining: boolean;
+    }>>;
+    /**
+     * Get information about this worker for the worker pool.
+     */
+    getInfo(): WorkerInfo;
+    /**
+     * Cancel a job.
+     */
+    cancelJob(jobId: string, queueName?: string): Promise<boolean>;
+    /**
+     * Cancel all jobs.
+     */
+    cancelAllJobs(queueName?: string): Promise<number>;
+    /**
+     * Get the job with the given ID.
+     */
+    getJob(jobId: string, queueName?: string): Promise<Job | null>;
+    /**
+     * Start the worker.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the worker.
+     */
+    stop(force?: boolean): Promise<void>;
+    /**
+     * Set the concurrency for a queue.
+     */
+    setConcurrency(queueName: string, concurrency: number): Promise<void>;
+}