@gravito/zenith 1.1.2 → 1.1.3

package/src/server/services/QueueService.ts

@@ -6,15 +6,33 @@ import { LogStreamProcessor } from './LogStreamProcessor'
 import { MaintenanceScheduler } from './MaintenanceScheduler'
 import { QueueMetricsCollector } from './QueueMetricsCollector'
 
+/**
+ * Snapshot of queue statistics.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface QueueStats {
+  /** Name of the queue. */
   name: string
+  /** Number of jobs waiting in the queue. */
   waiting: number
+  /** Number of jobs delayed. */
   delayed: number
+  /** Number of jobs that failed. */
   failed: number
+  /** Number of jobs currently being processed. */
   active: number
+  /** Whether the queue is currently paused. */
   paused: boolean
 }
 
+/**
+ * Health report from a worker instance.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface WorkerReport {
   id: string
   hostname: string
@@ -31,6 +49,12 @@ export interface WorkerReport {
   loadAvg: number[]
 }
 
+/**
+ * A standard system log message.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface SystemLog {
   level: 'info' | 'warn' | 'error' | 'success'
   message: string
@@ -39,12 +63,34 @@ export interface SystemLog {
   timestamp: string
 }
 
+/**
+ * Aggregated global statistics.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface GlobalStats {
   queues: QueueStats[]
   throughput: { timestamp: string; count: number }[]
   workers: WorkerReport[]
 }
 
+/**
+ * QueueService acts as the central orchestrator for all queue-related operations.
+ *
+ * It bridges the gap between the raw Redis data, the persistent SQL storage,
+ * and the real-time dashboard. It handles:
+ * - Direct queue manipulation (pause, resume, purge).
+ * - Job lifecycle management (retry, delete).
+ * - System-wide metric aggregation and alerting.
+ * - Log stream processing and archiving.
+ *
+ * This service is designed to be the single source of truth for the
+ * Zenith Console.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export class QueueService {
   private redis: Redis
   private subRedis: Redis
@@ -56,6 +102,13 @@ export class QueueService {
   private metricsCollector: QueueMetricsCollector
   private maintenanceScheduler: MaintenanceScheduler
 
+  /**
+   * Initializes the QueueService.
+   *
+   * @param redisUrl - The Redis connection string (e.g., redis://localhost:6379).
+   * @param prefix - Key prefix for all Redis keys used by the queues.
+   * @param persistence - Optional configuration for MySQL persistence.
+   */
   constructor(
     redisUrl: string,
     prefix = 'queue:',
@@ -95,6 +148,15 @@ export class QueueService {
     this.alerts = new AlertService(redisUrl)
   }
 
+  /**
+   * Connects to all required backing services.
+   *
+   * Establishes connections to Redis, the AlertService, and the LogStreamProcessor.
+   * Also starts the maintenance scheduler.
+   *
+   * @returns Promise resolving when all connections are ready.
+   * @throws {Error} If Redis or AlertService fails to connect.
+   */
   async connect() {
     await Promise.all([
       this.redis.connect(),
@@ -106,6 +168,21 @@ export class QueueService {
     this.maintenanceScheduler.start(30000)
   }
 
+  /**
+   * Subscribes to real-time system logs.
+   *
+   * @param callback - Function to be called when a new log arrives.
+   * @returns Unsubscribe function.
+   *
+   * @example
+   * ```typescript
+   * const unsub = queueService.onLog((log) => {
+   *   console.log('New log:', log.message);
+   * });
+   * // Later...
+   * unsub();
+   * ```
+   */
   onLog(callback: (msg: SystemLog) => void): () => void {
     const unsub = this.logProcessor.onLog(callback)
     const emitterUnsub = () => {
@@ -117,25 +194,58 @@ export class QueueService {
     }
   }
 
+  /**
+   * Retrieves current statistics for all known queues.
+   *
+   * @returns List of queue statistics.
+   */
   async listQueues(): Promise<QueueStats[]> {
     return this.metricsCollector.listQueues()
   }
 
+  /**
+   * Pauses a specific queue, preventing it from processing jobs.
+   *
+   * @param queueName - The name of the queue to pause.
+   * @returns True if successful.
+   * @throws {Error} If Redis operation fails.
+   */
   async pauseQueue(queueName: string): Promise<boolean> {
     await this.redis.set(`${this.prefix}${queueName}:paused`, '1')
     return true
   }
 
+  /**
+   * Resumes a paused queue.
+   *
+   * @param queueName - The name of the queue to resume.
+   * @returns True if successful.
+   * @throws {Error} If Redis operation fails.
+   */
   async resumeQueue(queueName: string): Promise<boolean> {
     await this.redis.del(`${this.prefix}${queueName}:paused`)
     return true
   }
 
+  /**
+   * Checks if a queue is currently paused.
+   *
+   * @param queueName - The name of the queue.
+   * @returns True if paused, false otherwise.
+   */
   async isQueuePaused(queueName: string): Promise<boolean> {
     const paused = await this.redis.get(`${this.prefix}${queueName}:paused`)
     return paused === '1'
   }
 
+  /**
+   * Moves all delayed jobs in a queue back to the waiting list immediately.
+   *
+   * Useful for manually forcing retries or clearing backlogs.
+   *
+   * @param queueName - The name of the queue.
+   * @returns The number of jobs moved.
+   */
   async retryDelayedJob(queueName: string): Promise<number> {
     const key = `${this.prefix}${queueName}`
     const delayKey = `${key}:delayed`
@@ -157,6 +267,15 @@ export class QueueService {
     return movedCount
   }
 
+  /**
+   * Retrieves a paginated list of jobs from a specific queue and state.
+   *
+   * @param queueName - The queue to query.
+   * @param type - The state to filter by (waiting, delayed, failed).
+   * @param start - Start index (0-based).
+   * @param stop - Stop index (inclusive).
+   * @returns List of job objects.
+   */
   async getJobs(
     queueName: string,
     type: 'waiting' | 'delayed' | 'failed' = 'waiting',
@@ -210,6 +329,14 @@ export class QueueService {
     }
   }
 
+  /**
+   * Records a snapshot of system metrics and triggers alerts if needed.
+   *
+   * Called periodically by the metrics collector.
+   *
+   * @param nodes - Current state of nodes (from PulseService).
+   * @param injectedWorkers - Optional worker data (for testing).
+   */
   async recordStatusMetrics(
     nodes: Record<string, any> = {},
     injectedWorkers?: any[]
@@ -253,6 +380,12 @@ export class QueueService {
       .catch((err) => console.error('[AlertService] Rule Evaluation Error:', err))
   }
 
+  /**
+   * Subscribes to global stats updates.
+   *
+   * @param callback - Function called with new stats.
+   * @returns Unsubscribe function.
+   */
   onStats(callback: (stats: GlobalStats) => void): () => void {
     this.logEmitter.on('stats', callback)
     return () => {
@@ -260,6 +393,13 @@ export class QueueService {
     }
   }
 
+  /**
+   * Retrieves historical data for a specific metric.
+   *
+   * @param metric - The metric name (waiting, delayed, failed, workers).
+   * @param limit - Number of data points to return (minutes).
+   * @returns Array of values.
+   */
   async getMetricHistory(metric: string, limit = 15): Promise<number[]> {
     const now = Math.floor(Date.now() / 60000)
     const keys = []
@@ -271,6 +411,11 @@ export class QueueService {
     return values.map((v) => parseInt(v || '0', 10))
   }
 
+  /**
+   * Calculates system throughput (jobs per minute).
+   *
+   * @returns Array of { timestamp, count } objects for the last 15 minutes.
+   */
   async getThroughputData(): Promise<{ timestamp: string; count: number }[]> {
     const now = Math.floor(Date.now() / 60000)
     const results = []
@@ -288,10 +433,23 @@ export class QueueService {
     return results
   }
 
+  /**
+   * Lists all active workers.
+   *
+   * @returns Array of worker reports.
+   */
   async listWorkers(): Promise<WorkerReport[]> {
     return this.metricsCollector.listWorkers()
   }
 
+  /**
+   * Deletes a specific job from a queue.
+   *
+   * @param queueName - The queue name.
+   * @param type - The list to remove from (waiting, delayed, failed).
+   * @param jobRaw - The raw JSON string of the job to remove.
+   * @returns True if removed, false otherwise.
+   */
   async deleteJob(
     queueName: string,
     type: 'waiting' | 'delayed' | 'failed',
@@ -310,6 +468,13 @@ export class QueueService {
     return result > 0
   }
 
+  /**
+   * Retries a specific failed or delayed job immediately.
+   *
+   * @param queueName - The queue name.
+   * @param jobRaw - The raw JSON string of the job.
+   * @returns True if successfully moved to waiting list.
+   */
   async retryJob(queueName: string, jobRaw: string): Promise<boolean> {
     const key = `${this.prefix}${queueName}`
     const delayKey = `${key}:delayed`
@@ -330,6 +495,13 @@ export class QueueService {
     return result === 1
   }
 
+  /**
+   * Purges all jobs from a queue (waiting, delayed, failed, active).
+   *
+   * ⚠️ Destructive operation. Irreversible.
+   *
+   * @param queueName - The queue to purge.
+   */
   async purgeQueue(queueName: string): Promise<void> {
     const pipe = this.redis.pipeline()
     pipe.del(`${this.prefix}${queueName}`)
@@ -339,14 +511,32 @@ export class QueueService {
     await pipe.exec()
   }
 
+  /**
+   * Retries all failed jobs in a queue.
+   *
+   * @param queueName - The queue name.
+   * @returns Number of jobs retried.
+   */
   async retryAllFailedJobs(queueName: string): Promise<number> {
     return await this.manager.retryFailed(queueName, 10000)
   }
 
+  /**
+   * Clears all failed jobs from a queue.
+   *
+   * @param queueName - The queue name.
+   */
   async clearFailedJobs(queueName: string): Promise<void> {
     await this.manager.clearFailed(queueName)
   }
 
+  /**
+   * Gets the count of jobs in a specific state.
+   *
+   * @param queueName - Queue name.
+   * @param type - Job state.
+   * @returns Count of jobs.
+   */
   async getJobCount(queueName: string, type: 'waiting' | 'delayed' | 'failed'): Promise<number> {
     const key =
       type === 'delayed'
@@ -358,6 +548,13 @@ export class QueueService {
     return type === 'delayed' ? await this.redis.zcard(key) : await this.redis.llen(key)
   }
 
+  /**
+   * Deletes all jobs in a specific state from a queue.
+   *
+   * @param queueName - Queue name.
+   * @param type - Job state to clear.
+   * @returns Number of jobs deleted.
+   */
   async deleteAllJobs(queueName: string, type: 'waiting' | 'delayed' | 'failed'): Promise<number> {
     const key =
       type === 'delayed'
@@ -371,6 +568,13 @@ export class QueueService {
     return count
   }
 
+  /**
+   * Retries all jobs in a specific state (delayed or failed).
+   *
+   * @param queueName - Queue name.
+   * @param type - Job state.
+   * @returns Number of jobs retried.
+   */
   async retryAllJobs(queueName: string, type: 'delayed' | 'failed'): Promise<number> {
     if (type === 'delayed') {
       return await this.retryDelayedJob(queueName)
@@ -379,6 +583,14 @@ export class QueueService {
     }
   }
 
+  /**
+   * Deletes a specific set of jobs.
+   *
+   * @param queueName - Queue name.
+   * @param type - Job state.
+   * @param jobRaws - Array of raw job strings.
+   * @returns Number of jobs deleted.
+   */
   async deleteJobs(
     queueName: string,
     type: 'waiting' | 'delayed' | 'failed',
@@ -403,6 +615,14 @@ export class QueueService {
     return results?.reduce((acc, [_, res]) => acc + ((res as number) || 0), 0) || 0
   }
 
+  /**
+   * Retries a specific set of jobs.
+   *
+   * @param queueName - Queue name.
+   * @param type - Job state.
+   * @param jobRaws - Array of raw job strings.
+   * @returns Number of jobs retried.
+   */
   async retryJobs(
     queueName: string,
     type: 'delayed' | 'failed',
@@ -434,6 +654,11 @@ export class QueueService {
     return count
   }
 
+  /**
+   * Publishes a log message to the stream and archives it.
+   *
+   * @param log - Log entry details.
+   */
   async publishLog(log: { level: string; message: string; workerId: string; queue?: string }) {
     const payload = {
       ...log,
@@ -462,11 +687,25 @@ export class QueueService {
     }
   }
 
+  /**
+   * Retrieves recent log history from Redis.
+   *
+   * @returns List of recent logs (max 100).
+   */
   async getLogHistory(): Promise<any[]> {
     const logs = await this.redis.lrange('flux_console:logs:history', 0, -1)
     return logs.map((l) => JSON.parse(l)).reverse()
   }
 
+  /**
+   * Searches for jobs across all queues and states.
+   *
+   * Scans Redis structures in real-time. Note: This can be expensive on large queues.
+   *
+   * @param query - Search term (ID, name, or data).
+   * @param options - Search options (limit, type).
+   * @returns List of matching jobs.
+   */
   async searchJobs(
     query: string,
     options: { limit?: number; type?: 'all' | 'waiting' | 'delayed' | 'failed' } = {}
@@ -520,6 +759,16 @@ export class QueueService {
     return results
   }
 
+  /**
+   * Retrieves archived jobs from persistent storage (MySQL).
+   *
+   * @param queue - Queue name.
+   * @param page - Page number.
+   * @param limit - Page size.
+   * @param status - Filter by status.
+   * @param filter - Additional filters (jobId, time range).
+   * @returns Paginated list of jobs.
+   */
   async getArchiveJobs(
     queue: string,
     page = 1,
@@ -544,6 +793,13 @@ export class QueueService {
     }
   }
 
+  /**
+   * Searches archived jobs in persistent storage.
+   *
+   * @param query - Search term.
+   * @param options - Pagination options.
+   * @returns Matching jobs.
+   */
   async searchArchive(
     query: string,
     options: { limit?: number; page?: number; queue?: string } = {}
@@ -563,6 +819,12 @@ export class QueueService {
     }
   }
 
+  /**
+   * Retrieves archived logs from persistent storage.
+   *
+   * @param options - Filters and pagination.
+   * @returns Paginated logs.
+   */
   async getArchivedLogs(
     options: {
       page?: number
@@ -591,6 +853,12 @@ export class QueueService {
     return { logs, total }
   }
 
+  /**
+   * Cleans up old archived data based on retention policy.
+   *
+   * @param days - Retention period in days.
+   * @returns Number of records deleted.
+   */
   async cleanupArchive(days: number): Promise<number> {
     const persistence = this.manager.getPersistence()
     if (!persistence) {
@@ -599,11 +867,21 @@ export class QueueService {
     return await persistence.cleanup(days)
   }
 
+  /**
+   * Lists all registered Cron schedules.
+   *
+   * @returns List of schedules.
+   */
   async listSchedules(): Promise<any[]> {
     const scheduler = this.manager.getScheduler()
     return await scheduler.list()
   }
 
+  /**
+   * Registers a new Cron schedule.
+   *
+   * @param config - Schedule configuration.
+   */
   async registerSchedule(config: {
     id: string
     cron: string
@@ -614,16 +892,31 @@ export class QueueService {
     await scheduler.register(config)
   }
 
+  /**
+   * Removes a Cron schedule.
+   *
+   * @param id - Schedule ID.
+   */
   async removeSchedule(id: string): Promise<void> {
     const scheduler = this.manager.getScheduler()
     await scheduler.remove(id)
   }
 
+  /**
+   * Manually triggers a scheduled job immediately.
+   *
+   * @param id - Schedule ID.
+   */
   async runScheduleNow(id: string): Promise<void> {
     const scheduler = this.manager.getScheduler()
     await scheduler.runNow(id)
   }
 
+  /**
+   * Processes schedule ticks.
+   *
+   * Should be called periodically to check for due schedules.
+   */
   async tickScheduler(): Promise<void> {
     const scheduler = this.manager.getScheduler()
     await scheduler.tick()

package/src/shared/types.ts

@@ -1,6 +1,8 @@
 /**
  * Metrics representing CPU usage for a specific node/process.
  *
+ * Used to visualize load distribution and identify CPU-bound workers.
+ *
  * @public
  * @since 3.0.0
  */
@@ -9,13 +11,15 @@ export interface PulseCpu {
   system: number
   /** Process-specific CPU usage percentage (0-100). */
   process: number
-  /** Number of CPU cores available. */
+  /** Number of CPU cores available on the host. */
   cores: number
 }
 
 /**
  * Metrics representing memory usage for a specific node/process.
  *
+ * Critical for detecting memory leaks and capacity planning.
+ *
  * @public
  * @since 3.0.0
  */
@@ -43,6 +47,9 @@ export interface PulseMemory {
 /**
  * Runtime metadata for a monitored process.
  *
+ * Provides context about the environment (Node.js version, platform)
+ * and current health status.
+ *
  * @public
  * @since 3.0.0
  */
@@ -53,13 +60,16 @@ export interface PulseRuntime {
   framework: string
   /** Current process status (e.g., 'online', 'maintenance'). */
   status?: string
-  /** Last few error messages from the process. */
+  /** Last few error messages captured from the process stderr/logs. */
   errors?: string[]
 }
 
 /**
  * Statistics snapshot for a specific queue.
  *
+ * Represents the state of a queue at a specific point in time, including
+ * job counts and throughput metrics. Used for dashboard graphs.
+ *
  * @public
  * @since 3.0.0
  */
@@ -75,7 +85,7 @@ export interface QueueSnapshot {
     failed: number
     delayed: number
   }
-  /** Historical throughput data. */
+  /** Historical throughput data (jobs processed per minute). */
   throughput?: {
     in: number
     out: number
@@ -85,23 +95,26 @@ export interface QueueSnapshot {
 /**
  * Represents a single application instance (node) monitored by Zenith.
  *
+ * A PulseNode corresponds to a running process (e.g., a worker, API server)
+ * that emits heartbeats. These nodes form the cluster topology.
+ *
  * @public
  * @since 3.0.0
  */
 export interface PulseNode {
-  /** Unique execution ID for the node. */
+  /** Unique execution ID for the node (usually UUID). */
   id: string
-  /** Service group name. */
+  /** Service group name (e.g., "payment-worker", "api-gateway"). */
   service: string
   /** Programming language or runtime type. */
   language: 'node' | 'bun' | 'deno' | 'php' | 'go' | 'python' | 'other'
-  /** Application version. */
+  /** Application version (from package.json). */
   version: string
-  /** Process identifier. */
+  /** Process identifier (PID). */
   pid: number
   /** Hostname of the machine. */
   hostname: string
-  /** Operating system platform. */
+  /** Operating system platform (darwin, linux, win32). */
   platform: string
   /** CPU metrics. */
   cpu: PulseCpu
@@ -113,13 +126,16 @@ export interface PulseNode {
   runtime: PulseRuntime
   /** Unstructured metadata (e.g., framework-specific details). */
   meta?: any
-  /** Epoch timestamp of the last heartbeat. */
+  /** Epoch timestamp of the last heartbeat received. */
   timestamp: number
 }
 
 /**
  * Definition of an alert rule for monitoring health.
  *
+ * Alert rules define conditions that trigger notifications, such as
+ * high queue backlogs or worker failures.
+ *
  * @public
  * @since 3.0.0
  */
@@ -130,17 +146,19 @@ export interface AlertRule {
   name: string
   /** The metric type to monitor. */
   type: 'backlog' | 'failure' | 'worker_lost' | 'node_cpu' | 'node_ram'
-  /** The value that triggers the alert. */
+  /** The value that triggers the alert (e.g., > 100 jobs). */
   threshold: number
-  /** Optional queue name (if applicable). */
+  /** Optional queue name to scope the rule to. */
   queue?: string
-  /** Minutes to wait before re-triggering the alert. */
+  /** Minutes to wait before re-triggering the alert (debounce). */
   cooldownMinutes: number
 }
 
 /**
  * Configuration for alert notification channels.
  *
+ * Defines where alerts should be sent when triggered.
+ *
  * @public
  * @since 3.0.0
  */
@@ -170,13 +188,15 @@ export interface AlertConfig {
 /**
  * Configuration for automated system maintenance.
  *
+ * Controls data retention policies and auto-cleanup tasks.
+ *
  * @public
  * @since 3.0.0
  */
 export interface MaintenanceConfig {
   /** Whether to automatically delete old data. */
   autoCleanup: boolean
-  /** Number of days to retain records. */
+  /** Number of days to retain records (logs, metrics). */
   retentionDays: number
   /** Timestamp of the last maintenance run. */
   lastRun?: number
@@ -184,6 +204,11 @@ export interface MaintenanceConfig {
 
 /**
  * Represents a historical alert event.
+ *
+ * Stored in the database/log to track system health history.
+ *
+ * @public
+ * @since 3.0.0
  */
 export interface AlertEvent {
   id?: string