bunqueue 2.8.53 → 2.8.56

package/dist/application/queueManager.d.ts

@@ -1,381 +1,5 @@
-/**
- * Queue Manager
- * Core orchestrator for all queue operations
- */
-import type { Job, JobId, JobInput, JobLock, LockToken } from '../domain/types/job';
-import type { AtomicFlowBatchInput, AtomicFlowBatchResult } from '../domain/types/flow';
-import type { JobLocation, JobEvent } from '../domain/types/queue';
-import type { CronJob, CronJobInput } from '../domain/types/cron';
-import type { JobLogEntry, CreateWorkerOptions } from '../domain/types/worker';
-import { type StallConfig } from '../domain/types/stall';
-import type { DlqConfig, DlqEntry, DlqFilter, DlqStats } from '../domain/types/dlq';
-import { Shard } from '../domain/queue/shard';
-import { WebhookManager } from './webhookManager';
-import { WorkerManager } from './workerManager';
-import { type OperationalMetrics } from './metricsExporter';
-import { type SetLike } from '../shared/lru';
-import type { QueueManagerConfig } from './types';
-import * as statsMgr from './statsManager';
-export type { QueueManagerConfig };
-/**
- * QueueManager - Central coordinator
- */
-export declare class QueueManager {
-    private readonly config;
-    private readonly storage;
-    private readonly shards;
-    private readonly shardLocks;
-    private readonly customIdLock;
-    private readonly processingShards;
-    private readonly processingLocks;
-    private readonly jobIndex;
-    private readonly completedJobs;
-    private readonly completedJobsData;
-    private readonly depCompletions;
-    private readonly timedOutJobs;
-    private readonly jobResults;
-    private readonly dependencyResults;
-    private readonly customIdMap;
-    private readonly jobLogs;
-    private readonly pendingDepChecks;
-    private readonly stalledCandidates;
-    private depFlushScheduled;
-    private depFlushRunning;
-    private readonly jobLocks;
-    private readonly clientJobs;
-    private readonly repeatChain;
-    /** Stores failed children values for continueParentOnFailure — parentId → { childKey: error } */
-    private readonly failedChildrenValues;
-    /** Stores ignored children failures for ignoreDependencyOnFailure — parentId → { childKey: error } */
-    private readonly ignoredChildrenFailures;
-    private readonly cronScheduler;
-    readonly webhookManager: WebhookManager;
-    readonly workerManager: WorkerManager;
-    private readonly eventsManager;
-    private dashboardEmit;
-    private recoveryStats;
-    private readonly maxLogsPerJob;
-    private readonly metrics;
-    private operationalMetricsProvider;
-    private readonly perQueueMetrics;
-    private readonly startTime;
-    private readonly backgroundTaskHandles;
-    private readonly queueNamesCache;
-    private readonly monitoringState;
-    private readonly contextFactory;
-    constructor(config?: QueueManagerConfig);
-    private getContextDependencies;
-    private getContextCallbacks;
-    private handleRepeat;
-    push(queue: string, input: JobInput): Promise<Job>;
-    pushBatch(queue: string, inputs: JobInput[]): Promise<JobId[]>;
-    pushFlow(batch: AtomicFlowBatchInput): Promise<AtomicFlowBatchResult>;
-    pull(queue: string, timeoutMs?: number, signal?: AbortSignal): Promise<Job | null>;
-    pullWithLock(queue: string, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal): Promise<{
-        job: Job | null;
-        token: string | null;
-    }>;
-    pullBatch(queue: string, count: number, timeoutMs?: number, signal?: AbortSignal): Promise<Job[]>;
-    pullBatchWithLock(queue: string, count: number, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal): Promise<{
-        jobs: Job[];
-        tokens: string[];
-    }>;
-    ack(jobId: JobId, result?: unknown, token?: string): Promise<void>;
-    ackBatch(jobIds: JobId[], tokens?: string[]): Promise<void>;
-    ackBatchWithResults(items: Array<{
-        id: JobId;
-        result: unknown;
-        token?: string;
-    }>): Promise<void>;
-    fail(jobId: JobId, error?: string, token?: string, unrecoverable?: boolean, stack?: string[]): Promise<void>;
-    /**
-     * Check if a failed lock verification is a genuine ownership conflict.
-     * If the job is still in processing with a different lock, throw.
-     * If the job was already requeued by the background lock expiration task, return silently.
-     */
-    private throwIfOwnershipConflict;
-    /**
-     * Issue #101 grace window: decide whether an ACK whose lock failed
-     * verification (because the TTL expired) should still be honored.
-     *
-     * Returns true ONLY when ALL hold:
-     *   1. the job is still in `processing`,
-     *   2. the lock entry's token still matches the presenting worker, and
-     *   3. the lock belongs to the CURRENT processing instance — its `createdAt`
-     *      is not older than the job's `startedAt`.
-     *
-     * Condition 3 is the re-lease guard. A lock-expiry re-lease (checkExpiredLocks)
-     * deletes the stale lock, so a new lease installs a NEW token and condition 2
-     * already fails. But the STALL path (stallDetection retry/moveToDlq) requeues
-     * the job WITHOUT deleting the lock — the original (now-expired) lock lingers
-     * with the original token. If another worker then re-pulls the job, its
-     * `startedAt` is reset to a newer time than the lingering lock's `createdAt`,
-     * so condition 3 fails and the timed-out worker's late ack is rejected
-     * (preventing a double-completion the skeptic confirmed). In the genuine #101
-     * case — the same worker finishing just after its lock expired, no re-pull —
-     * `startedAt` is unchanged and `createdAt >= startedAt`, so the grace is granted
-     * and the successful completion is recorded instead of being lost to a stall.
-     *
-     * Without this, a successful completion arriving just after lock expiry is
-     * rejected as "Invalid or expired lock token", the client drops it, and the
-     * job stalls to `failed` despite having been processed correctly.
-     */
-    private isExpiredButOwned;
-    /** Check if a queued job was stall-retried (has been processed before). */
-    private isStallRetried;
-    /**
-     * Complete a job that stall detection moved back to the queue while still processing.
-     * Removes from queue and marks completed to prevent duplicate execution (Issue #33).
-     */
-    private completeStallRetriedJob;
-    jobHeartbeat(jobId: JobId, token?: string): boolean;
-    jobHeartbeatBatch(jobIds: JobId[], tokens?: string[]): number;
-    /** Remove a lock unconditionally (used by worker dedup to clear stale locks) */
-    removeLock(jobId: JobId): void;
-    createLock(jobId: JobId, owner: string, ttl?: number): LockToken | null;
-    verifyLock(jobId: JobId, token: string): boolean;
-    renewJobLock(jobId: JobId, token: string, newTtl?: number): boolean;
-    renewJobLockBatch(items: Array<{
-        id: JobId;
-        token: string;
-        ttl?: number;
-    }>): string[];
-    releaseLock(jobId: JobId, token?: string): boolean;
-    getLockInfo(jobId: JobId): JobLock | null;
-    registerClientJob(clientId: string, jobId: JobId): void;
-    unregisterClientJob(clientId: string | undefined, jobId: JobId): void;
-    releaseClientJobs(clientId: string): Promise<number>;
-    /**
-     * Force-release client tracking without acquiring queue locks. Last-resort
-     * fallback when releaseClientJobs has exhausted its retry budget — clears
-     * the clientJobs map entry to prevent leaks and resets job heartbeats so
-     * the stall detector recovers orphaned active jobs on its next tick.
-     */
-    forceReleaseClientJobs(clientId: string): number;
-    getJob(jobId: JobId): Promise<Job | null>;
-    getJobState(jobId: JobId): Promise<string>;
-    getResult(jobId: JobId): unknown;
-    /**
-     * Get return values from all children of a parent job.
-     * Returns a Record where keys are job keys (queueName:jobId) and values are return values.
-     * BullMQ v5 compatible.
-     */
-    getChildrenValues(parentJobId: JobId): Promise<Record<string, unknown>>;
-    /**
-     * Update a job's parent reference.
-     * Used by FlowProducer when creating flows where children need to reference parent.
-     */
-    updateJobParent(childJobId: JobId, parentJobId: JobId): Promise<void>;
-    getJobByCustomId(customId: string): Job | null;
-    getProgress(jobId: JobId): {
-        progress: number;
-        message: string | null;
-    } | null;
-    count(queue: string): number;
-    pause(queue: string): void;
-    resume(queue: string): void;
-    isPaused(queue: string): boolean;
-    drain(queue: string): number;
-    obliterate(queue: string): void;
-    /**
-     * Drop per-queue metadata that obliterate is responsible for reclaiming:
-     * cumulative metrics (keyed by name, never self-expiring) and the persisted
-     * control-state row (#100 — so a stale pause/limit can't resurrect on the
-     * next restart).
-     */
-    private purgeQueueMetadata;
-    listQueues(): string[];
-    private registerQueueName;
-    private unregisterQueueName;
-    private releaseCompletionPins;
-    private reconcileCompletionPins;
-    clean(queue: string, graceMs: number, state?: string, limit?: number): JobId[];
-    getCountsPerPriority(queue: string): Record<number, number>;
-    getJobs(queue: string, options?: {
-        state?: string | string[];
-        start?: number;
-        end?: number;
-        asc?: boolean;
-    }): Job[];
-    getDlq(queue: string, count?: number): Job[];
-    getDlqEntries(queue: string, filter?: DlqFilter): DlqEntry[];
-    getDlqCount(queue: string): number;
-    getDlqStats(queue: string): DlqStats;
-    retryDlq(queue: string, jobId?: JobId, limit?: number): number;
-    purgeDlq(queue: string): number;
-    retryCompleted(queue: string, jobId?: JobId): number;
-    setRateLimit(queue: string, limit: number, durationMs?: number, ttlMs?: number): void;
-    clearRateLimit(queue: string): void;
-    setConcurrency(queue: string, limit: number): void;
-    clearConcurrency(queue: string): void;
-    /**
-     * Issue #100: write-through the current control-state (paused / rate-limit /
-     * concurrency) to the `queue_state` table so it survives a server restart.
-     * Reads the post-mutation state from the owning shard and UPSERTs the row.
-     */
-    private persistQueueState;
-    /** Get rate limit and concurrency limit for a queue */
-    getQueueLimits(queue: string): {
-        rateLimit: number | null;
-        concurrencyLimit: number | null;
-    };
-    /** Get all job results (for cloud telemetry) */
-    getAllJobResults(): Map<JobId, unknown>;
-    /** Get all job logs (for cloud telemetry) */
-    getAllJobLogs(): Map<JobId, JobLogEntry[]>;
-    /** Get all active job locks (for cloud telemetry) */
-    getAllJobLocks(): Map<JobId, JobLock>;
-    setStallConfig(queue: string, config: Record<string, unknown>): void;
-    getStallConfig(queue: string): StallConfig;
-    setDlqConfig(queue: string, config: Record<string, unknown>): void;
-    getDlqConfig(queue: string): DlqConfig;
-    /** Get extended telemetry data for cloud snapshot */
-    getCloudTelemetry(queueNames: string[]): {
-        perQueue: Record<string, {
-            uniqueKeys: number;
-            activeGroups: number;
-            waitingDeps: number;
-            waitingChildren: number;
-        }>;
-        eventSubscribers: number;
-        pendingDepChecks: number;
-    };
-    cancel(jobId: JobId): Promise<boolean>;
-    updateProgress(jobId: JobId, progress: number, message?: string): Promise<boolean>;
-    updateJobData(jobId: JobId, data: unknown): Promise<boolean>;
-    changePriority(jobId: JobId, priority: number, lifo?: boolean): Promise<boolean>;
-    promote(jobId: JobId): Promise<boolean>;
-    promoteJobs(queue: string, count?: number): Promise<number>;
-    moveToDelayed(jobId: JobId, delay: number): Promise<boolean>;
-    changeDelay(jobId: JobId, delay: number): Promise<boolean>;
-    moveActiveToWait(jobId: JobId): Promise<boolean>;
-    changeWaitingDelay(jobId: JobId, delay: number): Promise<boolean>;
-    moveToWaitingChildren(jobId: JobId): Promise<boolean>;
-    extendLock(jobId: JobId | string, token: string | null, duration: number): Promise<boolean>;
-    discard(jobId: JobId): Promise<boolean>;
-    addLog(jobId: JobId, message: string, level?: 'info' | 'warn' | 'error'): boolean;
-    getLogs(jobId: JobId): JobLogEntry[];
-    clearLogs(jobId: JobId, keepLogs?: number): void;
-    getPerQueueStats(): Map<string, statsMgr.PerQueueStats>;
-    getPrometheusMetrics(): string;
-    /** Attach metrics owned by server components outside the queue state machine. */
-    setOperationalMetricsProvider(provider: () => OperationalMetrics): void;
-    addCron(input: CronJobInput): CronJob;
-    /** Remove an orphaned cron job from the queue by its uniqueKey */
-    private removeOrphanedCronJob;
-    removeCron(name: string): boolean;
-    getCron(name: string): CronJob | undefined;
-    listCrons(): CronJob[];
-    /** Register dashboard event emitter (for WS pub/sub) */
-    setDashboardEmit(fn: (event: string, data: Record<string, unknown>) => void): void;
-    /** Emit a dashboard event (callable from handlers) */
-    emitDashboardEvent(event: string, data: Record<string, unknown>): void;
-    subscribe(callback: (event: JobEvent) => void): () => void;
-    waitForJobCompletion(jobId: JobId, timeoutMs: number): Promise<boolean>;
-    /** Register worker with dashboard event */
-    registerWorker(name: string, queues: string[], concurrency?: number, opts?: CreateWorkerOptions): import("../domain/types/worker").Worker;
-    /** Unregister worker with dashboard event */
-    unregisterWorker(workerId: string): boolean;
-    /** Unregister all workers associated with a TCP client ID */
-    unregisterWorkersByClientId(clientId: string): number;
-    getJobIndex(): Map<JobId, JobLocation>;
-    getCompletedJobs(): SetLike<JobId>;
-    getDepCompletions(): SetLike<JobId>;
-    getShards(): Shard[];
-    private onJobCompleted;
-    /** Release failure metadata owned by a parent that reached terminal failure. */
-    private onJobFailed;
-    /** Check if completing this job completes an entire flow */
-    private checkFlowCompleted;
-    /**
-     * BullMQ v5: failParentOnFailure — when a child terminally fails
-     * and has failParentOnFailure: true, also fail the parent job.
-     */
-    private failParentOnChildFailure;
-    /** Move a parent job to DLQ/failed state because a child failed */
-    private moveParentToFailed;
-    /**
-     * Handle child dependency options: removeDependencyOnFailure, ignoreDependencyOnFailure, continueParentOnFailure
-     */
-    private onChildDependencyOption;
-    /**
-     * continueParentOnFailure: move parent to queue when a child fails.
-     * Stores the failure info for getFailedChildrenValues().
-     */
-    private continueParentOnChildFailure;
-    /**
-     * Move a flow parent from its waiting state into the run queue after a child failure
-     * (continueParentOnFailure / last-dependency resolution). Deferred to the next tick
-     * so the failed child's worker batch drains first — the parent is then picked up on
-     * a subsequent poll rather than racing to completion in the same synchronous cascade.
-     */
-    private promoteParentAfterChildFailure;
-    /**
-     * removeDependencyOnFailure / ignoreDependencyOnFailure:
-     * Remove child from parent's pending deps. If last dep, promote parent.
-     * If ignoreDependencyOnFailure, also store failure reason.
-     */
-    private removeChildFromParentDeps;
-    /**
-     * Get failed children values for a parent job (populated by continueParentOnFailure).
-     */
-    getFailedChildrenValues(parentJobId: JobId): Promise<Record<string, string>>;
-    /**
-     * Get ignored children failures for a parent job (populated by ignoreDependencyOnFailure).
-     */
-    getIgnoredChildrenFailures(parentJobId: JobId): Promise<Record<string, string>>;
-    /**
-     * Remove a child job's dependency from its parent.
-     * If this was the last pending child, promotes parent to queue.
-     * Throws if the job has no parent.
-     */
-    removeChildDependency(childJobId: JobId): Promise<boolean>;
-    /**
-     * Remove all unprocessed (waiting/delayed) children of a parent job.
-     * Active, completed, and failed children are not affected.
-     */
-    removeUnprocessedChildren(parentJobId: JobId): Promise<void>;
-    private onJobsCompleted;
-    /**
-     * Schedule dependency flush on next microtask.
-     * Coalesces multiple onJobCompleted calls in the same tick.
-     */
-    private scheduleDependencyFlush;
-    /**
-     * Run dependency flush with reentrancy loop.
-     * The while-loop handles new completions arriving during async lock waits.
-     */
-    private runDependencyFlush;
-    private hasPendingDeps;
-    getStats(): statsMgr.QueueStats;
-    /** Get summary of all queues: name, paused, counts */
-    getQueuesSummary(): Array<{
-        name: string;
-        paused: boolean;
-        counts: {
-            waiting: number;
-            prioritized: number;
-            active: number;
-            completed: number;
-            failed: number;
-            delayed: number;
-        };
-    }>;
-    /** Get counts for every registered queue with one global aggregation pass. */
-    getAllQueueJobCounts(): Map<string, statsMgr.QueueJobCounts>;
-    /** Aggregate a selected group of queues without repeating global scans. */
-    getQueueJobCountsBatch(queueNames: Iterable<string>): Map<string, statsMgr.QueueJobCounts>;
-    /** Get job counts for a specific queue */
-    getQueueJobCounts(queueName: string): statsMgr.QueueJobCounts;
-    getMemoryStats(): statsMgr.MemoryStats;
-    /** Get storage health status (disk full detection) */
-    getStorageStatus(): {
-        diskFull: boolean;
-        error: string | null;
-        since: number | null;
-    };
-    /** Persist pending buffered writes before an external SQLite snapshot. */
-    flushPersistence(): number;
-    compactMemory(): void;
-    shutdown(): void;
+/** Public QueueManager façade. Implementation lives in queue-manager/. */
+import { QueueManagerLifecycle } from './queue-manager/lifecycle';
+export type { QueueManagerConfig } from './types';
+export declare class QueueManager extends QueueManagerLifecycle {
 }