bunsane 0.1.4 → 0.2.0

package/core/SchedulerManager.ts

@@ -12,12 +12,13 @@ import type {
     SchedulerConfig,
     TaskMetrics
 } from "../types/scheduler.types";
-import Query from "./Query";
+import { Query } from "../query/Query";
 import { Entity } from "./Entity";
 import { CronParser } from "../utils/cronParser";
 import type { ComponentTargetConfig } from "./EntityHookManager";
 import ArcheType from "./ArcheType";
-import { BaseComponent } from "./Components";
+import { BaseComponent } from "./components";
+import { DistributedLock, type DistributedLockConfig } from "./scheduler/DistributedLock";
 
 const loggerInstance = logger.child({ scope: "SchedulerManager" });
 
@@ -27,7 +28,8 @@ export class SchedulerManager {
     private intervals: Map<string, NodeJS.Timeout> = new Map();
     private isRunning: boolean = false;
     private eventListeners: SchedulerEventCallback[] = [];
-    private config: SchedulerConfig;
+    public config: SchedulerConfig;
+    private distributedLock: DistributedLock;
     private metrics: SchedulerMetrics = {
         totalTasks: 0,
         runningTasks: 0,
@@ -37,7 +39,10 @@ export class SchedulerManager {
         totalExecutionTime: 0,
         timedOutTasks: 0,
         retriedTasks: 0,
-        taskMetrics: {}
+        taskMetrics: {},
+        skippedExecutions: 0,
+        lockAttempts: 0,
+        locksAcquired: 0
     };
 
     private constructor() {
@@ -45,10 +50,21 @@ export class SchedulerManager {
             enabled: true,
             maxConcurrentTasks: 5,
             defaultTimeout: 30000, // 30 seconds
-            enableLogging: true,
-            runOnStart: true
+            enableLogging: false,
+            runOnStart: true,
+            distributedLocking: true, // Enable by default for multi-instance safety
+            lockTimeout: 0, // No retry by default - skip if can't acquire
+            lockRetryInterval: 100,
         };
 
+        // Initialize distributed lock with config
+        this.distributedLock = new DistributedLock({
+            enabled: this.config.distributedLocking ?? true,
+            enableLogging: this.config.enableLogging,
+            lockTimeout: this.config.lockTimeout ?? 0,
+            retryInterval: this.config.lockRetryInterval ?? 100,
+        });
+
         this.initializeLifecycleIntegration();
     }
 
@@ -63,7 +79,6 @@ export class SchedulerManager {
         ApplicationLifecycle.addPhaseListener((event) => {
             const phase = event.detail;
             if (phase === ApplicationPhase.APPLICATION_READY) {
-                logger.info("Scheduler initialized and ready");
                 if (this.config.runOnStart) {
                     this.start();
                 }
@@ -78,8 +93,15 @@ export class SchedulerManager {
         }
 
         // Validate task info
-        if (!taskInfo.id || !taskInfo.name || (!taskInfo.componentTarget && !taskInfo.options?.componentTarget) || !taskInfo.interval) {
-            const error = new Error(`Invalid task info: missing required fields (id, name, componentTarget/componentTarget config, interval)`);
+        if (!taskInfo.id || !taskInfo.name || !taskInfo.interval) {
+            const error = new Error(`Invalid task info: missing required fields (id, name, interval)`);
+            loggerInstance.error(`Failed to register task: ${error.message}`);
+            throw error;
+        }
+
+        // Validate query configuration
+        if (!taskInfo.options?.query && !taskInfo.options?.componentTarget && !taskInfo.componentTarget) {
+            const error = new Error(`Invalid task info: must provide either query function, componentTarget config, or legacy componentTarget`);
             loggerInstance.error(`Failed to register task: ${error.message}`);
             throw error;
         }
@@ -118,6 +140,59 @@ export class SchedulerManager {
         }
     }
 
+    /**
+     * Schedule a simple job with a cron expression and callback.
+     * This is a simpler alternative to registerTask for jobs that don't need
+     * entity-component system integration.
+     */
+    public scheduleJob(name: string, cronExpression: string, callback: () => Promise<void> | void): { cancel: () => void } {
+        const jobId = `job_${name}_${Date.now()}`;
+
+        // Validate cron expression
+        const validation = CronParser.validate(cronExpression);
+        if (!validation.isValid) {
+            throw new Error(`Invalid cron expression for job "${name}": ${validation.error}`);
+        }
+
+        let timeoutId: ReturnType<typeof setTimeout> | null = null;
+        let cancelled = false;
+
+        const scheduleNextExecution = () => {
+            if (cancelled) return;
+
+            const nextExecution = CronParser.getNextExecution(validation.fields!, new Date());
+            if (!nextExecution) {
+                loggerInstance.warn(`Unable to calculate next execution for job "${name}"`);
+                return;
+            }
+
+            const delay = nextExecution.getTime() - Date.now();
+            timeoutId = setTimeout(async () => {
+                if (cancelled) return;
+                try {
+                    await callback();
+                } catch (error) {
+                    loggerInstance.error(`Job "${name}" failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                scheduleNextExecution();
+            }, delay);
+
+            this.intervals.set(jobId, timeoutId as any);
+        };
+
+        scheduleNextExecution();
+
+        return {
+            cancel: () => {
+                cancelled = true;
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                    this.intervals.delete(jobId);
+                }
+            }
+        };
+    }
+
     private scheduleTask(taskInfo: ScheduledTaskInfo): void {
         try {
             if (taskInfo.interval === ScheduleInterval.CRON) {
@@ -134,6 +209,13 @@ export class SchedulerManager {
     private scheduleIntervalTask(taskInfo: ScheduledTaskInfo): void {
         const intervalMs = this.getIntervalMilliseconds(taskInfo.interval);
 
+        // Clear any existing interval for this task before creating a new one
+        const existingInterval = this.intervals.get(taskInfo.id);
+        if (existingInterval) {
+            clearInterval(existingInterval);
+            this.intervals.delete(taskInfo.id);
+        }
+
         // For very long intervals (monthly), use a different approach
         if (intervalMs > 24 * 60 * 60 * 1000) { // More than 24 hours
             this.scheduleLongIntervalTask(taskInfo, intervalMs);
@@ -188,6 +270,12 @@ export class SchedulerManager {
 
         taskInfo.nextExecution = nextExecution;
 
+        // Clear any existing timeout for this task before creating a new one
+        const existingTimeout = this.intervals.get(taskInfo.id);
+        if (existingTimeout) {
+            clearTimeout(existingTimeout as any);
+        }
+
         // Schedule the task to run at the calculated time
         const timeoutId = setTimeout(async () => {
             await this.executeTask(taskInfo.id);
@@ -232,6 +320,38 @@ export class SchedulerManager {
             return;
         }
 
+        // Try to acquire distributed lock before executing
+        this.metrics.lockAttempts++;
+        const lockResult = await this.distributedLock.tryAcquire(taskId);
+
+        if (!lockResult.acquired) {
+            // Another instance is executing this task
+            this.metrics.skippedExecutions++;
+
+            if (this.config.enableLogging) {
+                loggerInstance.debug(`Task ${taskInfo.name} skipped - another instance is executing (lock key: ${lockResult.lockKey})`);
+            }
+
+            this.emitEvent({
+                type: 'task.skipped',
+                taskId: taskInfo.id,
+                timestamp: new Date(),
+                data: { reason: 'lock_unavailable', lockKey: lockResult.lockKey.toString() }
+            });
+
+            return;
+        }
+
+        // Lock acquired successfully
+        this.metrics.locksAcquired++;
+
+        this.emitEvent({
+            type: 'task.lock.acquired',
+            taskId: taskInfo.id,
+            timestamp: new Date(),
+            data: { lockKey: lockResult.lockKey.toString() }
+        });
+
         taskInfo.isRunning = true;
         taskInfo.lastExecution = new Date();
         this.metrics.runningTasks++;
@@ -240,51 +360,25 @@ export class SchedulerManager {
         const timeout = taskInfo.options?.timeout || this.config.defaultTimeout;
 
         try {
-            // Create query based on component targeting configuration
-            let query: Query;
-
-            if (taskInfo.options?.componentTarget) {
-                // Use new component targeting configuration
+            // Create query based on targeting configuration
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            let query: Query<any>;
+
+            if (taskInfo.options?.query) {
+                // Use custom query function (preferred approach)
+                query = taskInfo.options.query();
+            } else if (taskInfo.options?.componentTarget) {
+                // Use component targeting configuration (deprecated - use query instead)
                 const componentTarget = taskInfo.options.componentTarget;
                 query = this.buildQueryFromComponentTarget(componentTarget);
             } else if (taskInfo.componentTarget) {
-                // Use legacy single component targeting
+                // Use legacy single component targeting (deprecated - use query instead)
                 query = new Query().with(taskInfo.componentTarget);
             } else {
-                throw new Error('No component target specified');
+                throw new Error('No query function or component target specified');
             }
 
-            // Apply component filters if specified
-            if (taskInfo.options?.componentFilters && taskInfo.options.componentFilters.length > 0) {
-                // Group filters by component for the Query API
-                const filtersByComponent = new Map<string, any[]>();
-
-                for (const filter of taskInfo.options.componentFilters) {
-                    // For now, we'll assume filters are for the main component
-                    // In a more advanced implementation, we could support filters for different components
-                    const mainComponent = taskInfo.componentTarget || taskInfo.options?.componentTarget?.includeComponents?.[0];
-                    if (mainComponent) {
-                        const componentName = typeof mainComponent === 'function' ? mainComponent.name : 'unknown';
-                        if (!filtersByComponent.has(componentName)) {
-                            filtersByComponent.set(componentName, []);
-                        }
-                        filtersByComponent.get(componentName)!.push(filter);
-                    }
-                }
-
-                // Apply filters to components
-                for (const [componentName, filters] of filtersByComponent.entries()) {
-                    // This is a simplified implementation - in practice, you'd need to map component names to actual component classes
-                    if (filters.length > 0) {
-                        // For legacy compatibility, apply to the main component
-                        if (taskInfo.componentTarget) {
-                            query.with(taskInfo.componentTarget, Query.filters(...filters));
-                        }
-                    }
-                }
-            }
-
-            // Apply entity limit if specified
+            // Apply entity limit if specified (can be used with query function)
             if (taskInfo.options?.maxEntitiesPerExecution) {
                 query.take(taskInfo.options.maxEntitiesPerExecution);
             }
@@ -351,6 +445,16 @@ export class SchedulerManager {
         } finally {
             taskInfo.isRunning = false;
             this.metrics.runningTasks--;
+
+            // Release the distributed lock
+            await this.distributedLock.release(taskId);
+
+            this.emitEvent({
+                type: 'task.lock.released',
+                taskId: taskInfo.id,
+                timestamp: new Date(),
+                data: { lockKey: lockResult.lockKey.toString() }
+            });
         }
     }
 
@@ -376,18 +480,19 @@ export class SchedulerManager {
             this.scheduleTask(taskInfo);
         }
 
+        const lockStatus = this.config.distributedLocking !== false ? 'enabled' : 'disabled';
         if (this.config.enableLogging) {
-            loggerInstance.info(`Scheduler started with ${this.tasks.size} tasks (sorted by priority)`);
+            loggerInstance.info(`Scheduler started with ${this.tasks.size} tasks (sorted by priority, distributed locking: ${lockStatus})`);
         }
 
         this.emitEvent({
             type: 'scheduler.started',
             timestamp: new Date(),
-            data: { taskCount: this.tasks.size }
+            data: { taskCount: this.tasks.size, distributedLocking: this.config.distributedLocking !== false }
         });
     }
 
-    public stop(): void {
+    public async stop(): Promise<void> {
         if (!this.isRunning) {
             loggerInstance.warn("Scheduler is not running");
             return;
@@ -402,6 +507,9 @@ export class SchedulerManager {
         }
         this.intervals.clear();
 
+        // Release all distributed locks held by this instance
+        await this.distributedLock.releaseAll();
+
         if (this.config.enableLogging) {
             loggerInstance.info("Scheduler stopped");
         }
@@ -472,6 +580,15 @@ export class SchedulerManager {
 
     public updateConfig(config: Partial<SchedulerConfig>): void {
         this.config = { ...this.config, ...config };
+
+        // Sync distributed lock configuration
+        this.distributedLock.updateConfig({
+            enabled: this.config.distributedLocking ?? true,
+            enableLogging: this.config.enableLogging,
+            lockTimeout: this.config.lockTimeout ?? 0,
+            retryInterval: this.config.lockRetryInterval ?? 100,
+        });
+
         if (this.config.enableLogging) {
             loggerInstance.info(`Scheduler configuration updated: ${JSON.stringify(config)}`);
         }
@@ -481,6 +598,28 @@ export class SchedulerManager {
         return { ...this.config };
     }
 
+    /**
+     * Get distributed lock configuration and status
+     */
+    public getDistributedLockInfo(): {
+        enabled: boolean;
+        heldLocks: number;
+        config: DistributedLockConfig;
+    } {
+        return {
+            enabled: this.config.distributedLocking !== false,
+            heldLocks: this.distributedLock.getHeldLockCount(),
+            config: this.distributedLock.getConfig(),
+        };
+    }
+
+    /**
+     * Check if distributed locking is enabled
+     */
+    public isDistributedLockingEnabled(): boolean {
+        return this.config.distributedLocking !== false;
+    }
+
     /**
      * Execute a task with timeout enforcement
      */
@@ -642,8 +781,10 @@ export class SchedulerManager {
      * @param componentTarget The component targeting configuration
      * @returns A Query object configured with the component targeting
      */
-    private buildQueryFromComponentTarget(componentTarget: ComponentTargetConfig): Query {
-        let query = new Query();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    private buildQueryFromComponentTarget(componentTarget: ComponentTargetConfig): Query<any> {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let query: Query<any> = new Query();
 
         // Handle archetype matching first (most specific)
         if (componentTarget.archetype) {