@juspay/neurolink 9.40.0 → 9.41.0

package/dist/tasks/backends/bullmqBackend.js

@@ -0,0 +1,188 @@
+/**
+ * BullMQ Backend — Production-grade task scheduling via Redis.
+ *
+ * - Cron tasks → BullMQ repeatable jobs with cron pattern
+ * - Interval tasks → BullMQ repeatable jobs with `every` option
+ * - One-shot tasks → BullMQ delayed jobs
+ * - Survives process restarts (Redis-persisted)
+ */
+import { Queue, Worker } from "bullmq";
+import { logger } from "../../utils/logger.js";
+import { TaskError } from "../errors.js";
+import { TASK_DEFAULTS, } from "../../types/taskTypes.js";
+const QUEUE_NAME = "neurolink-tasks";
+export class BullMQBackend {
+    name = "bullmq";
+    queue = null;
+    worker = null;
+    executors = new Map();
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async initialize() {
+        const connection = this.getConnectionConfig();
+        this.queue = new Queue(QUEUE_NAME, { connection });
+        this.worker = new Worker(QUEUE_NAME, async (job) => {
+            const taskId = job.data.taskId;
+            const task = job.data.task;
+            const executor = this.executors.get(taskId);
+            if (!executor) {
+                logger.warn("[BullMQ] No executor found for task", { taskId });
+                return;
+            }
+            logger.info("[BullMQ] Executing task", { taskId, name: task.name });
+            const result = await executor(task);
+            return result;
+        }, {
+            connection,
+            concurrency: this.config.maxConcurrentRuns ?? TASK_DEFAULTS.maxConcurrentRuns,
+        });
+        this.worker.on("failed", (job, err) => {
+            logger.error("[BullMQ] Job failed", {
+                taskId: job?.data?.taskId,
+                error: String(err),
+            });
+        });
+        this.worker.on("error", (err) => {
+            logger.error("[BullMQ] Worker error", { error: String(err) });
+        });
+        logger.info("[BullMQ] Backend initialized");
+    }
+    async shutdown() {
+        if (this.worker) {
+            await this.worker.close();
+            this.worker = null;
+        }
+        if (this.queue) {
+            await this.queue.close();
+            this.queue = null;
+        }
+        this.executors.clear();
+        logger.info("[BullMQ] Backend shut down");
+    }
+    async schedule(task, executor) {
+        this.ensureInitialized();
+        this.executors.set(task.id, executor);
+        const jobData = { taskId: task.id, task };
+        const schedule = task.schedule;
+        if (schedule.type === "cron") {
+            await this.queue.upsertJobScheduler(task.id, {
+                pattern: schedule.expression,
+                ...(schedule.timezone ? { tz: schedule.timezone } : {}),
+            }, { name: task.name, data: jobData });
+        }
+        else if (schedule.type === "interval") {
+            await this.queue.upsertJobScheduler(task.id, { every: schedule.every }, { name: task.name, data: jobData });
+        }
+        else if (schedule.type === "once") {
+            const at = typeof schedule.at === "string" ? new Date(schedule.at) : schedule.at;
+            const delay = Math.max(0, at.getTime() - Date.now());
+            await this.queue.add(task.name, jobData, {
+                jobId: task.id,
+                delay,
+            });
+        }
+        logger.info("[BullMQ] Task scheduled", {
+            taskId: task.id,
+            type: schedule.type,
+        });
+    }
+    async cancel(taskId) {
+        this.ensureInitialized();
+        this.executors.delete(taskId);
+        // Remove repeatable job scheduler
+        try {
+            await this.queue.removeJobScheduler(taskId);
+        }
+        catch {
+            // May not be a repeatable job — try removing by job ID
+        }
+        // Remove delayed/waiting job
+        try {
+            const job = await this.queue.getJob(taskId);
+            if (job) {
+                await job.remove();
+            }
+        }
+        catch {
+            // Job may already be processed/removed
+        }
+        logger.info("[BullMQ] Task cancelled", { taskId });
+    }
+    async pause(taskId) {
+        // BullMQ doesn't have per-job pause, so we fully cancel the job scheduler
+        // and executor. This is intentionally destructive — cancel() removes both
+        // the executor from the map and the job/scheduler from Redis.
+        //
+        // Resume flow (orchestrated by TaskManager):
+        //   1. TaskManager.resume() updates task status to "active" in the store
+        //   2. TaskManager.resume() calls backend.schedule(task, newExecutor)
+        //   3. schedule() re-registers the executor and creates a new job/scheduler
+        //
+        // Because TaskManager always supplies a fresh executor on schedule(),
+        // there is no need to preserve the old executor here.
+        await this.cancel(taskId);
+        logger.info("[BullMQ] Task paused (cancelled pending jobs; TaskManager will re-schedule on resume)", { taskId });
+    }
+    async resume(taskId) {
+        // No-op: BullMQ resume is handled by TaskManager calling schedule() after
+        // this method returns. See TaskManager.resume() which calls:
+        //   backend.schedule(updatedTask, executor)
+        // That call re-registers the executor and creates the job/scheduler in Redis.
+        logger.info("[BullMQ] Task resume requested (awaiting re-schedule from TaskManager)", { taskId });
+    }
+    async isHealthy() {
+        if (!this.queue) {
+            return false;
+        }
+        try {
+            // Check if the queue can reach Redis
+            await this.queue.getJobCounts();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ── Internal ──────────────────────────────────────────
+    /**
+     * Returns a connection options object for BullMQ / ioredis.
+     * When a URL is provided we parse it fully, preserving TLS (`rediss://`),
+     * ACL username, password, db index, and any query-string parameters so
+     * nothing is silently dropped.
+     */
+    getConnectionConfig() {
+        const redis = this.config.redis ?? {};
+        if (redis.url) {
+            const parsed = new URL(redis.url);
+            const opts = {
+                host: parsed.hostname || "localhost",
+                port: Number(parsed.port) || 6379,
+                db: parsed.pathname ? Number(parsed.pathname.slice(1)) || 0 : 0,
+            };
+            if (parsed.password) {
+                opts.password = decodeURIComponent(parsed.password);
+            }
+            if (parsed.username) {
+                opts.username = decodeURIComponent(parsed.username);
+            }
+            // rediss:// scheme → enable TLS
+            if (parsed.protocol === "rediss:") {
+                opts.tls = {};
+            }
+            return opts;
+        }
+        return {
+            host: redis.host ?? TASK_DEFAULTS.redis.host,
+            port: redis.port ?? TASK_DEFAULTS.redis.port,
+            ...(redis.password ? { password: redis.password } : {}),
+            db: redis.db ?? 0,
+        };
+    }
+    ensureInitialized() {
+        if (!this.queue) {
+            throw TaskError.create("BACKEND_NOT_INITIALIZED", "[BullMQ] Backend not initialized. Call initialize() first.");
+        }
+    }
+}

package/dist/tasks/backends/nodeTimeoutBackend.d.ts

@@ -0,0 +1,27 @@
+/**
+ * NodeTimeout Backend — Development/zero-dependency task scheduling.
+ *
+ * - Cron tasks → parsed with `croner`, scheduled via setTimeout chains
+ * - Interval tasks → setInterval
+ * - One-shot tasks → setTimeout
+ * - All timers are in-process — lost on restart
+ */
+import { type Task, type TaskBackend, type TaskExecutorFn, type TaskManagerConfig } from "../../types/taskTypes.js";
+export declare class NodeTimeoutBackend implements TaskBackend {
+    readonly name = "node-timeout";
+    private scheduled;
+    private paused;
+    private disposed;
+    private activeRuns;
+    private maxConcurrentRuns;
+    constructor(config: TaskManagerConfig);
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    schedule(task: Task, executor: TaskExecutorFn): Promise<void>;
+    cancel(taskId: string): Promise<void>;
+    pause(taskId: string): Promise<void>;
+    resume(taskId: string): Promise<void>;
+    isHealthy(): Promise<boolean>;
+    private executeTask;
+    private clearEntry;
+}

package/dist/tasks/backends/nodeTimeoutBackend.js

@@ -0,0 +1,140 @@
+/**
+ * NodeTimeout Backend — Development/zero-dependency task scheduling.
+ *
+ * - Cron tasks → parsed with `croner`, scheduled via setTimeout chains
+ * - Interval tasks → setInterval
+ * - One-shot tasks → setTimeout
+ * - All timers are in-process — lost on restart
+ */
+import { Cron } from "croner";
+import { logger } from "../../utils/logger.js";
+import { TASK_DEFAULTS, } from "../../types/taskTypes.js";
+export class NodeTimeoutBackend {
+    name = "node-timeout";
+    scheduled = new Map();
+    paused = new Map();
+    disposed = false;
+    activeRuns = 0;
+    maxConcurrentRuns;
+    constructor(config) {
+        this.maxConcurrentRuns =
+            config.maxConcurrentRuns ?? TASK_DEFAULTS.maxConcurrentRuns;
+    }
+    async initialize() {
+        logger.info("[NodeTimeout] Backend initialized");
+    }
+    async shutdown() {
+        this.disposed = true;
+        for (const entry of this.scheduled.values()) {
+            this.clearEntry(entry);
+        }
+        this.scheduled.clear();
+        this.paused.clear();
+        logger.info("[NodeTimeout] Backend shut down");
+    }
+    async schedule(task, executor) {
+        // Cancel existing schedule for this task if any
+        await this.cancel(task.id);
+        const entry = { taskId: task.id, executor, task };
+        const schedule = task.schedule;
+        if (schedule.type === "cron") {
+            entry.cronJob = new Cron(schedule.expression, {
+                timezone: schedule.timezone,
+                catch: (err) => {
+                    logger.error("[NodeTimeout] Cron execution error", {
+                        taskId: task.id,
+                        error: String(err),
+                    });
+                },
+            }, () => {
+                this.executeTask(entry);
+            });
+        }
+        else if (schedule.type === "interval") {
+            // Wait for the first interval tick before executing
+            entry.intervalId = setInterval(() => {
+                this.executeTask(entry);
+            }, schedule.every);
+        }
+        else if (schedule.type === "once") {
+            const at = typeof schedule.at === "string" ? new Date(schedule.at) : schedule.at;
+            const delay = Math.max(0, at.getTime() - Date.now());
+            entry.timeoutId = setTimeout(() => {
+                this.executeTask(entry);
+                this.scheduled.delete(task.id);
+            }, delay);
+        }
+        this.scheduled.set(task.id, entry);
+        logger.info("[NodeTimeout] Task scheduled", {
+            taskId: task.id,
+            type: schedule.type,
+        });
+    }
+    async cancel(taskId) {
+        const entry = this.scheduled.get(taskId);
+        if (entry) {
+            this.clearEntry(entry);
+            this.scheduled.delete(taskId);
+        }
+        this.paused.delete(taskId);
+        logger.debug("[NodeTimeout] Task cancelled", { taskId });
+    }
+    async pause(taskId) {
+        const entry = this.scheduled.get(taskId);
+        if (!entry) {
+            return;
+        }
+        this.clearEntry(entry);
+        this.scheduled.delete(taskId);
+        // Save the entry so we can re-schedule on resume
+        this.paused.set(taskId, entry);
+        logger.info("[NodeTimeout] Task paused", { taskId });
+    }
+    async resume(taskId) {
+        const entry = this.paused.get(taskId);
+        if (!entry) {
+            return;
+        }
+        this.paused.delete(taskId);
+        // Re-schedule with the saved task and executor
+        await this.schedule(entry.task, entry.executor);
+        logger.info("[NodeTimeout] Task resumed", { taskId });
+    }
+    async isHealthy() {
+        return !this.disposed;
+    }
+    // ── Internal ──────────────────────────────────────────
+    executeTask(entry) {
+        if (this.activeRuns >= this.maxConcurrentRuns) {
+            logger.warn("[NodeTimeout] Max concurrent runs reached, skipping tick", {
+                taskId: entry.taskId,
+                activeRuns: this.activeRuns,
+                maxConcurrentRuns: this.maxConcurrentRuns,
+            });
+            return;
+        }
+        this.activeRuns++;
+        entry
+            .executor(entry.task)
+            .catch((err) => {
+            logger.error("[NodeTimeout] Task execution failed", {
+                taskId: entry.taskId,
+                error: String(err),
+            });
+        })
+            .finally(() => {
+            this.activeRuns--;
+        });
+    }
+    clearEntry(entry) {
+        if (entry.cronJob) {
+            entry.cronJob.stop();
+        }
+        if (entry.intervalId !== undefined) {
+            clearInterval(entry.intervalId);
+        }
+        if (entry.timeoutId !== undefined) {
+            clearTimeout(entry.timeoutId);
+        }
+    }
+}

package/dist/tasks/backends/taskBackendRegistry.d.ts

@@ -0,0 +1,31 @@
+/**
+ * TaskBackendRegistry — registration point for all task backend implementations.
+ * Follows the same pattern as ProviderRegistry: dynamic imports, lazy registration.
+ */
+import type { TaskBackendName, TaskBackendFactoryFn, TaskManagerConfig, TaskBackend } from "../../types/taskTypes.js";
+export declare class TaskBackendRegistry {
+    private static factories;
+    private static registered;
+    /**
+     * Register a backend factory function.
+     * Can be called externally to add custom backends (e.g., "pg-boss").
+     */
+    static register(name: string, factory: TaskBackendFactoryFn): void;
+    /**
+     * Register the built-in backends (BullMQ, NodeTimeout).
+     * Idempotent — safe to call multiple times.
+     */
+    static registerDefaults(): void;
+    /**
+     * Create a backend instance by name.
+     */
+    static create(name: TaskBackendName | string, config: TaskManagerConfig): Promise<TaskBackend>;
+    /**
+     * Check if a backend is registered.
+     */
+    static has(name: string): boolean;
+    /**
+     * List all registered backend names.
+     */
+    static getAvailable(): string[];
+}

package/dist/tasks/backends/taskBackendRegistry.js

@@ -0,0 +1,65 @@
+/**
+ * TaskBackendRegistry — registration point for all task backend implementations.
+ * Follows the same pattern as ProviderRegistry: dynamic imports, lazy registration.
+ */
+import { logger } from "../../utils/logger.js";
+import { TaskError } from "../errors.js";
+export class TaskBackendRegistry {
+    static factories = new Map();
+    static registered = false;
+    /**
+     * Register a backend factory function.
+     * Can be called externally to add custom backends (e.g., "pg-boss").
+     */
+    static register(name, factory) {
+        TaskBackendRegistry.factories.set(name, factory);
+        logger.debug(`[TaskBackendRegistry] Registered backend: ${name}`);
+    }
+    /**
+     * Register the built-in backends (BullMQ, NodeTimeout).
+     * Idempotent — safe to call multiple times.
+     */
+    static registerDefaults() {
+        if (TaskBackendRegistry.registered) {
+            return;
+        }
+        TaskBackendRegistry.registered = true;
+        // BullMQ backend (production, Redis-backed)
+        TaskBackendRegistry.register("bullmq", async (config) => {
+            const { BullMQBackend } = await import("./bullmqBackend.js");
+            return new BullMQBackend(config);
+        });
+        // NodeTimeout backend (development, in-process timers)
+        TaskBackendRegistry.register("node-timeout", async (config) => {
+            const { NodeTimeoutBackend } = await import("./nodeTimeoutBackend.js");
+            return new NodeTimeoutBackend(config);
+        });
+        logger.debug("[TaskBackendRegistry] Registered default backends");
+    }
+    /**
+     * Create a backend instance by name.
+     */
+    static async create(name, config) {
+        TaskBackendRegistry.registerDefaults();
+        const factory = TaskBackendRegistry.factories.get(name);
+        if (!factory) {
+            const available = Array.from(TaskBackendRegistry.factories.keys());
+            throw TaskError.create("BACKEND_UNKNOWN", `Unknown task backend: "${name}". Available: ${available.join(", ")}`);
+        }
+        return factory(config);
+    }
+    /**
+     * Check if a backend is registered.
+     */
+    static has(name) {
+        TaskBackendRegistry.registerDefaults();
+        return TaskBackendRegistry.factories.has(name);
+    }
+    /**
+     * List all registered backend names.
+     */
+    static getAvailable() {
+        TaskBackendRegistry.registerDefaults();
+        return Array.from(TaskBackendRegistry.factories.keys());
+    }
+}

package/dist/tasks/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * TaskError — Typed error factory for the TaskManager system.
+ *
+ * Uses the standard NeuroLink createErrorFactory pattern so every task-related
+ * error carries a structured code, feature tag, and optional retryable flag.
+ */
+export declare const TaskErrorCodes: {
+    readonly TASK_NOT_FOUND: "TASK-001";
+    readonly BACKEND_NOT_INITIALIZED: "TASK-002";
+    readonly BACKEND_UNKNOWN: "TASK-003";
+    readonly INVALID_TASK_STATUS: "TASK-004";
+    readonly TASK_LIMIT_REACHED: "TASK-005";
+    readonly TASK_DISABLED: "TASK-006";
+    readonly SCHEDULE_FAILED: "TASK-007";
+};
+export declare const TaskError: {
+    codes: {
+        readonly TASK_NOT_FOUND: "TASK-001";
+        readonly BACKEND_NOT_INITIALIZED: "TASK-002";
+        readonly BACKEND_UNKNOWN: "TASK-003";
+        readonly INVALID_TASK_STATUS: "TASK-004";
+        readonly TASK_LIMIT_REACHED: "TASK-005";
+        readonly TASK_DISABLED: "TASK-006";
+        readonly SCHEDULE_FAILED: "TASK-007";
+    };
+    create: (code: "TASK_NOT_FOUND" | "BACKEND_NOT_INITIALIZED" | "BACKEND_UNKNOWN" | "INVALID_TASK_STATUS" | "TASK_LIMIT_REACHED" | "TASK_DISABLED" | "SCHEDULE_FAILED", message: string, options?: {
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+        cause?: Error;
+    } | undefined) => import("../index.js").NeuroLinkFeatureError;
+};

package/dist/tasks/errors.js

@@ -0,0 +1,17 @@
+/**
+ * TaskError — Typed error factory for the TaskManager system.
+ *
+ * Uses the standard NeuroLink createErrorFactory pattern so every task-related
+ * error carries a structured code, feature tag, and optional retryable flag.
+ */
+import { createErrorFactory } from "../core/infrastructure/baseError.js";
+export const TaskErrorCodes = {
+    TASK_NOT_FOUND: "TASK-001",
+    BACKEND_NOT_INITIALIZED: "TASK-002",
+    BACKEND_UNKNOWN: "TASK-003",
+    INVALID_TASK_STATUS: "TASK-004",
+    TASK_LIMIT_REACHED: "TASK-005",
+    TASK_DISABLED: "TASK-006",
+    SCHEDULE_FAILED: "TASK-007",
+};
+export const TaskError = createErrorFactory("Task", TaskErrorCodes);

package/dist/tasks/store/fileTaskStore.d.ts

@@ -0,0 +1,43 @@
+/**
+ * FileTaskStore — File-based persistence for TaskManager.
+ * Used automatically when backend is "node-timeout".
+ *
+ * Storage layout:
+ *   {storePath}                     — tasks.json (all task definitions)
+ *   {logsPath}/{taskId}.jsonl       — run log per task (append-only)
+ *   Continuation history is in-memory only (lost on restart).
+ */
+import { type Task, type TaskStatus, type TaskRunResult, type TaskStore, type TaskManagerConfig, type ConversationEntry } from "../../types/taskTypes.js";
+export declare class FileTaskStore implements TaskStore {
+    readonly type: "file";
+    private storePath;
+    private logsPath;
+    private maxRunLogs;
+    private maxHistoryEntries;
+    private tasks;
+    /** In-memory only — lost on restart */
+    private history;
+    private flushQueue;
+    constructor(config: TaskManagerConfig);
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    save(task: Task): Promise<void>;
+    get(taskId: string): Promise<Task | null>;
+    list(filter?: {
+        status?: TaskStatus;
+    }): Promise<Task[]>;
+    update(taskId: string, updates: Partial<Task>): Promise<Task>;
+    delete(taskId: string): Promise<void>;
+    appendRun(taskId: string, run: TaskRunResult): Promise<void>;
+    getRuns(taskId: string, options?: {
+        limit?: number;
+        status?: string;
+    }): Promise<TaskRunResult[]>;
+    appendHistory(taskId: string, messages: ConversationEntry[]): Promise<void>;
+    getHistory(taskId: string): Promise<ConversationEntry[]>;
+    clearHistory(taskId: string): Promise<void>;
+    /** Write all tasks to disk atomically, serialized via promise queue */
+    private flush;
+    /** Prune run log if it exceeds maxRunLogs entries */
+    private pruneRunLog;
+}