feat(backend): implement cron job system for scheduled tasks

Author: Lasim

package-lock.json

@@ -41,6 +41,7 @@
     "isomorphic-dompurify": "^2.28.0",
     "lucia": "^3.2.2",
     "nanoid": "^5.1.6",
+    "node-cron": "^4.2.1",
     "nodemailer": "^7.0.6",
     "pino": "^10.0.0",
     "pino-pretty": "^13.1.1",

services/backend/package.json

@@ -0,0 +1,101 @@
+import * as cron from 'node-cron';
+import type { FastifyBaseLogger } from 'fastify';
+
+/**
+ * CronJob interface - each cron job file must export this structure
+ */
+export interface CronJob {
+  /** Cron schedule expression (e.g., every 2 minutes, hourly, daily) */
+  schedule: string;
+  
+  /** Optional job name for logging */
+  name?: string;
+  
+  /** The task function to execute */
+  task: () => void | Promise<void>;
+}
+
+/**
+ * CronManager - Manages all cron jobs in the application
+ * 
+ * This class discovers, registers, and manages all cron jobs.
+ * It provides lifecycle management including graceful shutdown.
+ */
+export class CronManager {
+  private jobs: Map<string, cron.ScheduledTask> = new Map();
+  private logger: FastifyBaseLogger;
+
+  constructor(logger: FastifyBaseLogger) {
+    this.logger = logger;
+  }
+
+  /**
+   * Register a new cron job
+   * 
+   * @param jobDefinition - The cron job definition
+   */
+  register(jobDefinition: CronJob): void {
+    const jobName = jobDefinition.name || 'unnamed-job';
+
+    try {
+      const task = cron.schedule(jobDefinition.schedule, async () => {
+        this.logger.info({ 
+          job: jobName, 
+          schedule: jobDefinition.schedule 
+        }, 'Executing cron job');
+
+        try {
+          await jobDefinition.task();
+          this.logger.debug({ job: jobName }, 'Cron job completed successfully');
+        } catch (error) {
+          this.logger.error({ 
+            job: jobName, 
+            error 
+          }, 'Cron job execution failed');
+        }
+      });
+
+      this.jobs.set(jobName, task);
+      this.logger.info({ 
+        job: jobName, 
+        schedule: jobDefinition.schedule 
+      }, 'Cron job registered');
+
+    } catch (error) {
+      this.logger.error({ 
+        job: jobName, 
+        schedule: jobDefinition.schedule, 
+        error 
+      }, 'Failed to register cron job');
+    }
+  }
+
+  /**
+   * Start all registered cron jobs
+   */
+  start(): void {
+    this.logger.info({ count: this.jobs.size }, 'Cron jobs are running (auto-started on schedule)');
+  }
+
+  /**
+   * Stop all cron jobs gracefully
+   */
+  stop(): void {
+    this.logger.info({ count: this.jobs.size }, 'Stopping cron jobs');
+    
+    for (const [name, task] of this.jobs.entries()) {
+      task.stop();
+      this.logger.debug({ job: name }, 'Cron job stopped');
+    }
+
+    this.jobs.clear();
+    this.logger.info('All cron jobs stopped successfully');
+  }
+
+  /**
+   * Get list of registered job names
+   */
+  getJobNames(): string[] {
+    return Array.from(this.jobs.keys());
+  }
+}

services/backend/src/cron/cronManager.ts

@@ -0,0 +1,34 @@
+import type { FastifyBaseLogger } from 'fastify';
+import type { JobQueueService } from '../services/jobQueueService';
+import { CronManager } from './cronManager';
+// import { createExampleCronJob } from './jobs/exampleJob';
+
+/**
+ * Initialize and register all cron jobs
+ * 
+ * This function is called during server startup to set up all cron jobs.
+ * Add new cron jobs by:
+ * 1. Creating a job file in the jobs/ directory
+ * 2. Importing it here
+ * 3. Registering it with the CronManager
+ * 
+ * @param jobQueueService - Job queue service for creating background jobs
+ * @param logger - Logger instance
+ * @returns CronManager instance
+ */
+export function initializeCronJobs(
+  jobQueueService: JobQueueService,
+  logger: FastifyBaseLogger
+): CronManager {
+  const cronManager = new CronManager(logger);
+
+  // Example cron job - commented out, uncomment to test
+  // cronManager.register(createExampleCronJob(jobQueueService));
+
+  // Add your cron jobs here
+  // Example:
+  // cronManager.register(createDailyBackupJob(jobQueueService));
+  // cronManager.register(createHourlyCleanupJob(jobQueueService));
+
+  return cronManager;
+}

services/backend/src/cron/index.ts

@@ -0,0 +1,24 @@
+import type { CronJob } from '../cronManager';
+import type { JobQueueService } from '../../services/jobQueueService';
+
+/**
+ * Example Cron Job - Runs every 2 minutes
+ * 
+ * This job demonstrates how to push work to the job queue system
+ * from a cron schedule. Every 2 minutes, it creates a new job in
+ * the queue which will be processed by the ExampleCronWorker.
+ * 
+ * The worker will log: "hello from queue every 2min"
+ */
+export function createExampleCronJob(jobQueueService: JobQueueService): CronJob {
+  return {
+    name: 'example-every-2min',
+    schedule: '*/2 * * * *', // Every 2 minutes
+    
+    task: async () => {
+      await jobQueueService.createJob('example_cron_job', {
+        message: 'hello from queue every 2min'
+      });
+    }
+  };
+}

services/backend/src/cron/jobs/exampleJob.ts

@@ -197,6 +197,40 @@ export async function initializeDatabaseDependentServices(
         server.log.warn('⚠️ Continuing without Job Queue System due to error');
       }
 
+      // Initialize and start Cron Job System (after Job Queue System)
+      try {
+        server.log.debug('🔄 Initializing Cron Job System...');
+        const { initializeCronJobs } = await import('./cron');
+        
+        // Check if jobQueueService exists before initializing cron
+        if ((server as any).jobQueueService) {
+          const cronManager = initializeCronJobs((server as any).jobQueueService, server.log);
+          server.log.debug('✅ Cron jobs registered');
+          
+          // Start all cron jobs
+          cronManager.start();
+          server.log.info('✅ Cron Job System started and jobs scheduled');
+          
+          // Decorate server with cron manager for graceful shutdown
+          if (!server.hasDecorator('cronManager')) {
+            server.decorate('cronManager', cronManager);
+          } else {
+            (server as any).cronManager = cronManager;
+          }
+        } else {
+          server.log.warn('⚠️ Job Queue Service not available, skipping Cron Job System initialization');
+        }
+        
+      } catch (cronError) {
+        server.log.error({
+          error: cronError,
+          message: cronError instanceof Error ? cronError.message : 'Unknown error',
+          stack: cronError instanceof Error ? cronError.stack : 'No stack trace'
+        }, '❌ Cron Job System failed to initialize:');
+        // Don't throw - continue with startup but log the error
+        server.log.warn('⚠️ Continuing without Cron Job System due to error');
+      }
+
       // Start Token Cleanup Service (only after database is ready)
       try {
         server.log.debug('Starting Token Cleanup Service...');
@@ -601,7 +635,14 @@ export const createServer = async () => {
   server.log.info('Authentication routes registered under /api/auth.');
 
   server.addHook('onClose', async () => {
-    // Stop job processor first to gracefully finish current jobs
+    // Stop cron jobs first
+    if ((server as any).cronManager) {
+      server.log.info('Stopping cron jobs...');
+      (server as any).cronManager.stop();
+      server.log.info('Cron jobs stopped.');
+    }
+    
+    // Stop job processor to gracefully finish current jobs
     if ((server as any).jobProcessorService) {
       server.log.info('Stopping job processor...');
       await (server as any).jobProcessorService.stop();

services/backend/src/server.ts

@@ -5,6 +5,7 @@ import { type AnyDatabase } from '../db'
 import type SqliteDriver from 'better-sqlite3'
 import { type PluginManager } from '../plugin-system'
 import { type DeployStackEventBus } from '../events'
+import { type CronManager } from '../cron/cronManager'
 
 declare module 'fastify' {
   interface FastifyInstance {
@@ -27,6 +28,9 @@ declare module 'fastify' {
     // Methods for re-initializing database services after setup
     reinitializeDatabaseServices: () => Promise<boolean>
     reinitializePluginsWithDatabase: () => Promise<void>
+    
+    // Cron manager for scheduled jobs
+    cronManager?: CronManager
   }
 
   interface FastifyReply {