@checkstack/queue-memory-backend 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @checkstack/queue-memory-backend
 
+## 0.3.0
+
+### Minor Changes
+
+- 2c0822d: ### Queue System
+
+  - Added cron pattern support to `scheduleRecurring()` - accepts either `intervalSeconds` or `cronPattern`
+  - BullMQ backend uses native cron scheduling via `pattern` option
+  - InMemoryQueue implements wall-clock cron scheduling with `cron-parser`
+
+  ### Maintenance Backend
+
+  - Auto status transitions now use cron pattern `* * * * *` for precise second-0 scheduling
+  - User notifications are now sent for auto-started and auto-completed maintenances
+  - Refactored to call `addUpdate` RPC for status changes, centralizing hook/signal/notification logic
+
+  ### UI
+
+  - DateTimePicker now resets seconds and milliseconds to 0 when time is changed
+
+### Patch Changes
+
+- Updated dependencies [2c0822d]
+- Updated dependencies [66a3963]
+  - @checkstack/queue-api@0.2.0
+  - @checkstack/backend-api@0.5.0
+
 ## 0.2.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/queue-memory-backend",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {
@@ -12,8 +12,9 @@
     "@checkstack/backend-api": "workspace:*",
     "@checkstack/queue-api": "workspace:*",
     "@checkstack/queue-memory-common": "workspace:*",
-    "zod": "^4.2.1",
-    "@checkstack/common": "workspace:*"
+    "@checkstack/common": "workspace:*",
+    "cron-parser": "^4.9.0",
+    "zod": "^4.2.1"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/cron-scheduling.test.ts

@@ -0,0 +1,289 @@
+/**
+ * Cron Scheduling Tests for InMemoryQueue
+ *
+ * Uses Bun's Jest-compatible fake timers (`jest.useFakeTimers`, `jest.advanceTimersByTime`)
+ * to test cron scheduling without waiting for real time to pass.
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+  jest,
+  setSystemTime,
+  mock,
+} from "bun:test";
+import { InMemoryQueue } from "./memory-queue";
+import type { Logger } from "@checkstack/backend-api";
+
+const mockError = mock(() => {});
+const testLogger: Logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: mockError,
+};
+
+function createTestQueue(name: string) {
+  return new InMemoryQueue<string>(
+    name,
+    {
+      concurrency: 10,
+      maxQueueSize: 100,
+      delayMultiplier: 1, // Use real timing for cron tests
+      heartbeatIntervalMs: 100,
+    },
+    testLogger,
+  );
+}
+
+describe("InMemoryQueue Cron Scheduling", () => {
+  let queue: InMemoryQueue<string> | undefined;
+
+  beforeEach(() => {
+    // Enable fake timers with initial time
+    jest.useFakeTimers();
+    setSystemTime(new Date("2026-01-18T10:00:00Z"));
+    mockError.mockClear();
+  });
+
+  afterEach(async () => {
+    jest.useRealTimers();
+    if (queue) {
+      await queue.stop();
+      queue = undefined;
+    }
+  });
+
+  describe("Basic cron execution", () => {
+    it("should execute cron job at correct wall-clock time", async () => {
+      queue = createTestQueue("test-cron-execute");
+
+      let executionCount = 0;
+      await queue.consume(
+        async () => {
+          executionCount++;
+        },
+        { consumerGroup: "test", maxRetries: 0 },
+      );
+
+      // Schedule to run every minute at second 0
+      await queue.scheduleRecurring("payload", {
+        jobId: "cron-every-minute",
+        cronPattern: "* * * * *",
+      });
+
+      // Advance time by 61 seconds to trigger cron at 10:01:00
+      jest.advanceTimersByTime(61_000);
+      await Promise.resolve(); // Allow microtasks to flush
+
+      expect(executionCount).toBeGreaterThanOrEqual(1);
+    });
+
+    it("should reschedule cron job after execution", async () => {
+      queue = createTestQueue("test-cron-reschedule");
+
+      let executionCount = 0;
+      await queue.consume(
+        async () => {
+          executionCount++;
+        },
+        { consumerGroup: "test", maxRetries: 0 },
+      );
+
+      await queue.scheduleRecurring("payload", {
+        jobId: "cron-reschedule",
+        cronPattern: "* * * * *",
+      });
+
+      // Advance 2 minutes to trigger two executions
+      jest.advanceTimersByTime(60_000);
+      await Promise.resolve();
+
+      jest.advanceTimersByTime(60_000);
+      await Promise.resolve();
+
+      expect(executionCount).toBeGreaterThanOrEqual(2);
+    });
+  });
+
+  describe("Cron cancellation", () => {
+    it("should cancel pending cron jobs on stop()", async () => {
+      queue = createTestQueue("test-cron-stop");
+
+      let executionCount = 0;
+      await queue.consume(
+        async () => {
+          executionCount++;
+        },
+        { consumerGroup: "test", maxRetries: 0 },
+      );
+
+      await queue.scheduleRecurring("payload", {
+        jobId: "cron-stop-test",
+        cronPattern: "* * * * *",
+      });
+
+      // Stop the queue before cron fires
+      await queue.stop();
+      queue = undefined;
+
+      // Advance time past when cron should have fired
+      jest.advanceTimersByTime(120_000);
+      await Promise.resolve();
+
+      // Should NOT have executed any jobs since queue was stopped
+      expect(executionCount).toBe(0);
+    });
+
+    it("should stop cron scheduling when cancelled", async () => {
+      queue = createTestQueue("test-cron-cancel");
+
+      let executionCount = 0;
+      await queue.consume(
+        async () => {
+          executionCount++;
+        },
+        { consumerGroup: "test", maxRetries: 0 },
+      );
+
+      await queue.scheduleRecurring("payload", {
+        jobId: "cron-cancel-test",
+        cronPattern: "* * * * *",
+      });
+
+      // Execute once
+      jest.advanceTimersByTime(60_000);
+      await Promise.resolve();
+      const countBeforeCancel = executionCount;
+
+      // Cancel the job
+      await queue.cancelRecurring("cron-cancel-test");
+
+      // Advance time - should NOT execute
+      jest.advanceTimersByTime(60_000);
+      await Promise.resolve();
+
+      expect(executionCount).toBe(countBeforeCancel);
+    });
+  });
+
+  describe("Cron job details", () => {
+    it("should return cronPattern in getRecurringJobDetails", async () => {
+      queue = createTestQueue("test-cron-details");
+
+      await queue.scheduleRecurring("payload", {
+        jobId: "cron-details-test",
+        cronPattern: "0 9 * * 1-5",
+      });
+
+      const details = await queue.getRecurringJobDetails("cron-details-test");
+
+      expect(details).toBeDefined();
+      expect(details?.jobId).toBe("cron-details-test");
+      expect("cronPattern" in details!).toBe(true);
+      if ("cronPattern" in details!) {
+        expect(details.cronPattern).toBe("0 9 * * 1-5");
+      }
+    });
+
+    it("should return intervalSeconds for interval-based jobs", async () => {
+      queue = createTestQueue("test-interval-details");
+
+      await queue.scheduleRecurring("payload", {
+        jobId: "interval-details-test",
+        intervalSeconds: 60,
+      });
+
+      const details = await queue.getRecurringJobDetails(
+        "interval-details-test",
+      );
+
+      expect(details).toBeDefined();
+      expect(details?.jobId).toBe("interval-details-test");
+      expect("intervalSeconds" in details!).toBe(true);
+      if ("intervalSeconds" in details!) {
+        expect(details.intervalSeconds).toBe(60);
+      }
+    });
+  });
+
+  describe("MAX_TIMEOUT handling", () => {
+    it("should handle long delays by chunking timeouts", async () => {
+      queue = createTestQueue("test-max-timeout");
+
+      let executionCount = 0;
+      await queue.consume(
+        async () => {
+          executionCount++;
+        },
+        { consumerGroup: "test", maxRetries: 0 },
+      );
+
+      // Schedule monthly cron (1st of each month at midnight)
+      // Starting from Jan 18, next run is Feb 1 = ~14 days
+      await queue.scheduleRecurring("payload", {
+        jobId: "monthly-cron",
+        cronPattern: "0 0 1 * *",
+      });
+
+      // Advance 10 days - should not have executed yet
+      jest.advanceTimersByTime(10 * 24 * 60 * 60 * 1000);
+      await Promise.resolve();
+      expect(executionCount).toBe(0);
+
+      // Advance 5 more days to pass Feb 1 (total 15 days)
+      jest.advanceTimersByTime(5 * 24 * 60 * 60 * 1000);
+      await Promise.resolve();
+
+      // Now it should have executed on Feb 1
+      expect(executionCount).toBeGreaterThanOrEqual(1);
+    });
+
+    it("should chunk timeouts longer than MAX_TIMEOUT", async () => {
+      queue = createTestQueue("test-max-timeout-chunk");
+
+      let executionCount = 0;
+      await queue.consume(
+        async () => {
+          executionCount++;
+        },
+        { consumerGroup: "test", maxRetries: 0 },
+      );
+
+      // Schedule cron for ~30 days from now (past MAX_TIMEOUT of ~24.8 days)
+      // Feb 18 at midnight = 31 days from Jan 18
+      await queue.scheduleRecurring("payload", {
+        jobId: "far-cron",
+        cronPattern: "0 0 18 2 *",
+      });
+
+      // Advance 25 days (past MAX_TIMEOUT) - requires chunking internally
+      jest.advanceTimersByTime(25 * 24 * 60 * 60 * 1000);
+      await Promise.resolve();
+      expect(executionCount).toBe(0); // Feb 12 - still not Feb 18
+
+      // Advance 7 more days to Feb 18
+      jest.advanceTimersByTime(7 * 24 * 60 * 60 * 1000);
+      await Promise.resolve();
+
+      expect(executionCount).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe("Invalid cron patterns", () => {
+    it("should log error for invalid cron pattern", async () => {
+      queue = createTestQueue("test-invalid-cron");
+
+      await queue.scheduleRecurring("payload", {
+        jobId: "invalid-cron",
+        cronPattern: "invalid-pattern",
+      });
+
+      // The error should be logged immediately during scheduleNextCronRun
+      expect(mockError).toHaveBeenCalled();
+    });
+  });
+});

package/src/memory-queue.ts

@@ -5,9 +5,11 @@ import {
   QueueStats,
   ConsumeOptions,
   RecurringJobDetails,
+  RecurringSchedule,
 } from "@checkstack/queue-api";
 import type { Logger } from "@checkstack/backend-api";
 import { InMemoryQueueConfig } from "./plugin";
+import parser from "cron-parser";
 
 /**
  * Extended queue job with availability tracking for delayed jobs
@@ -62,16 +64,20 @@ interface ConsumerGroupState<T> {
 }
 
 /**
- * Recurring job metadata
+ * Maximum setTimeout delay (~24.8 days) to avoid overflow
  */
-interface RecurringJobMetadata<T> {
+const MAX_TIMEOUT = 2_147_483_647;
+
+/**
+ * Recurring job metadata - supports both interval and cron patterns
+ */
+type RecurringJobMetadata<T> = {
   jobId: string;
-  intervalSeconds: number;
   payload: T;
   priority: number;
-  enabled: boolean; // For cancellation
-  intervalId?: ReturnType<typeof setInterval>; // For wall-clock scheduling
-}
+  enabled: boolean;
+  timerId?: ReturnType<typeof setTimeout> | ReturnType<typeof setInterval>;
+} & RecurringSchedule;
 
 /**
  * In-memory queue implementation with consumer group support
@@ -94,7 +100,7 @@ export class InMemoryQueue<T> implements Queue<T> {
   constructor(
     private name: string,
     private config: InMemoryQueueConfig,
-    logger: Logger
+    logger: Logger,
   ) {
     this.semaphore = new Semaphore(config.concurrency);
     this.logger = logger;
@@ -126,11 +132,11 @@ export class InMemoryQueue<T> implements Queue<T> {
 
   async enqueue(
     data: T,
-    options?: { priority?: number; startDelay?: number; jobId?: string }
+    options?: { priority?: number; startDelay?: number; jobId?: string },
   ): Promise<string> {
     if (this.jobs.length >= this.config.maxQueueSize) {
       throw new Error(
-        `Queue '${this.name}' is full (max: ${this.config.maxQueueSize})`
+        `Queue '${this.name}' is full (max: ${this.config.maxQueueSize})`,
       );
     }
 
@@ -160,7 +166,7 @@ export class InMemoryQueue<T> implements Queue<T> {
 
     // Insert job in priority order (higher priority first)
     const insertIndex = this.jobs.findIndex(
-      (existingJob) => existingJob.priority! < job.priority!
+      (existingJob) => existingJob.priority! < job.priority!,
     );
 
     if (insertIndex === -1) {
@@ -188,7 +194,7 @@ export class InMemoryQueue<T> implements Queue<T> {
 
   async consume(
     consumer: QueueConsumer<T>,
-    options: ConsumeOptions
+    options: ConsumeOptions,
   ): Promise<void> {
     const { consumerGroup, maxRetries = 3 } = options;
 
@@ -220,50 +226,102 @@ export class InMemoryQueue<T> implements Queue<T> {
     data: T,
     options: {
       jobId: string;
-      intervalSeconds: number;
-      startDelay?: number;
       priority?: number;
-    }
+    } & RecurringSchedule,
   ): Promise<string> {
-    const { jobId, intervalSeconds, startDelay = 0, priority = 0 } = options;
+    const { jobId, priority = 0 } = options;
 
     // Check if this is an update to an existing recurring job
     const existingMetadata = this.recurringJobs.get(jobId);
     if (existingMetadata) {
-      // UPDATE CASE: Clear existing interval and pending executions
-      if (existingMetadata.intervalId) {
-        clearInterval(existingMetadata.intervalId);
+      // UPDATE CASE: Clear existing timer and pending executions
+      if (existingMetadata.timerId) {
+        if ("cronPattern" in existingMetadata) {
+          clearTimeout(existingMetadata.timerId);
+        } else {
+          clearInterval(existingMetadata.timerId);
+        }
       }
 
       // Find and remove any pending jobs for this recurring job
       this.jobs = this.jobs.filter((job) => {
-        // Check if this job belongs to the recurring job being updated
         if (job.id.startsWith(jobId + ":")) {
-          // Remove from processed sets to prevent orphaned references
           for (const group of this.consumerGroups.values()) {
             group.processedJobIds.delete(job.id);
           }
-          return false; // Remove this job
+          return false;
+        }
+        return true;
+      });
+    }
+
+    // Handle cron-based scheduling
+    if ("cronPattern" in options && options.cronPattern) {
+      const cronPattern = options.cronPattern;
+
+      // Wall-clock cron scheduling with MAX_TIMEOUT handling
+      const scheduleNextCronRun = () => {
+        if (this.stopped) return;
+
+        const metadata = this.recurringJobs.get(jobId);
+        if (!metadata || !metadata.enabled) return;
+
+        try {
+          const interval = parser.parseExpression(cronPattern);
+          const nextRun = interval.next().toDate();
+          const delayMs = nextRun.getTime() - Date.now();
+
+          if (delayMs > MAX_TIMEOUT) {
+            // Chunk long delays - wake up periodically to recalculate
+            metadata.timerId = setTimeout(scheduleNextCronRun, MAX_TIMEOUT);
+            return;
+          }
+
+          metadata.timerId = setTimeout(
+            () => {
+              if (!this.stopped && metadata.enabled) {
+                const uniqueId = `${jobId}:${Date.now()}-${Math.random()
+                  .toString(36)
+                  .slice(2, 8)}`;
+                void this.enqueue(data, { jobId: uniqueId, priority });
+                scheduleNextCronRun(); // Reschedule for next cron time
+              }
+            },
+            Math.max(0, delayMs),
+          );
+        } catch (error) {
+          this.logger.error(`Invalid cron pattern "${cronPattern}":`, error);
         }
-        return true; // Keep other jobs
+      };
+
+      // Store recurring job metadata
+      this.recurringJobs.set(jobId, {
+        jobId,
+        cronPattern,
+        payload: data,
+        priority,
+        enabled: true,
       });
+
+      // Start cron scheduling
+      scheduleNextCronRun();
+
+      return jobId;
     }
 
-    // Calculate interval in ms with delay multiplier
+    // Handle interval-based scheduling (original behavior)
+    // TypeScript XOR pattern doesn't narrow well, but intervalSeconds is guaranteed here
+    const intervalSeconds = options.intervalSeconds!;
     const intervalMs =
       intervalSeconds * 1000 * (this.config.delayMultiplier ?? 1);
 
     // Create interval for wall-clock scheduling
-    const intervalId = setInterval(() => {
+    const timerId = setInterval(() => {
       if (!this.stopped) {
-        // Add random suffix to ensure unique job IDs
         const uniqueId = `${jobId}:${Date.now()}-${Math.random()
           .toString(36)
           .slice(2, 8)}`;
-        void this.enqueue(data, {
-          jobId: uniqueId,
-          priority,
-        });
+        void this.enqueue(data, { jobId: uniqueId, priority });
       }
     }, intervalMs);
 
@@ -274,18 +332,14 @@ export class InMemoryQueue<T> implements Queue<T> {
       payload: data,
       priority,
       enabled: true,
-      intervalId,
+      timerId,
     });
 
-    // Schedule first execution (with optional startDelay)
+    // Schedule first execution immediately for interval-based jobs
     const firstJobId = `${jobId}:${Date.now()}-${Math.random()
       .toString(36)
       .slice(2, 8)}`;
-    await this.enqueue(data, {
-      jobId: firstJobId,
-      startDelay,
-      priority,
-    });
+    await this.enqueue(data, { jobId: firstJobId, priority });
 
     return jobId;
   }
@@ -295,16 +349,19 @@ export class InMemoryQueue<T> implements Queue<T> {
     if (metadata) {
       metadata.enabled = false; // Mark as disabled
 
-      // Clear the interval timer
-      if (metadata.intervalId) {
-        clearInterval(metadata.intervalId);
-        metadata.intervalId = undefined;
+      // Clear the timer (works for both setTimeout and setInterval)
+      if (metadata.timerId) {
+        if ("cronPattern" in metadata) {
+          clearTimeout(metadata.timerId);
+        } else {
+          clearInterval(metadata.timerId);
+        }
+        metadata.timerId = undefined;
       }
 
       // Also cancel any pending jobs
       this.jobs = this.jobs.filter((job) => {
         if (job.id.startsWith(jobId + ":")) {
-          // Remove from processed sets
           for (const group of this.consumerGroups.values()) {
             group.processedJobIds.delete(job.id);
           }
@@ -320,18 +377,23 @@ export class InMemoryQueue<T> implements Queue<T> {
   }
 
   async getRecurringJobDetails(
-    jobId: string
+    jobId: string,
   ): Promise<RecurringJobDetails<T> | undefined> {
     const metadata = this.recurringJobs.get(jobId);
     if (!metadata || !metadata.enabled) {
       return undefined;
     }
-    return {
+
+    const baseDetails = {
       jobId: metadata.jobId,
       data: metadata.payload,
-      intervalSeconds: metadata.intervalSeconds,
       priority: metadata.priority,
     };
+
+    if ("cronPattern" in metadata && metadata.cronPattern) {
+      return { ...baseDetails, cronPattern: metadata.cronPattern };
+    }
+    return { ...baseDetails, intervalSeconds: metadata.intervalSeconds! };
   }
 
   async getInFlightCount(): Promise<number> {
@@ -351,7 +413,7 @@ export class InMemoryQueue<T> implements Queue<T> {
 
       // Find next unprocessed job for this group that is available
       const job = this.jobs.find(
-        (j) => !groupState.processedJobIds.has(j.id) && j.availableAt <= now
+        (j) => !groupState.processedJobIds.has(j.id) && j.availableAt <= now,
       );
 
       if (!job) continue;
@@ -373,7 +435,7 @@ export class InMemoryQueue<T> implements Queue<T> {
     this.jobs = this.jobs.filter((job) => {
       // Job is done if all groups have processed it
       return ![...this.consumerGroups.values()].every((group) =>
-        group.processedJobIds.has(job.id)
+        group.processedJobIds.has(job.id),
       );
     });
   }
@@ -382,7 +444,7 @@ export class InMemoryQueue<T> implements Queue<T> {
     job: InternalQueueJob<T>,
     consumer: ConsumerGroupState<T>["consumers"][0],
     groupId: string,
-    groupState: ConsumerGroupState<T>
+    groupState: ConsumerGroupState<T>,
   ): Promise<void> {
     await this.semaphore.acquire();
     this.processing++;
@@ -395,7 +457,7 @@ export class InMemoryQueue<T> implements Queue<T> {
     } catch (error) {
       this.logger.error(
         `Job ${job.id} failed in group ${groupId} (attempt ${job.attempts}):`,
-        error
+        error,
       );
 
       // Retry logic
@@ -408,7 +470,7 @@ export class InMemoryQueue<T> implements Queue<T> {
 
         // Re-add job to queue for retry (with priority to process soon, preserving availableAt)
         const insertIndex = this.jobs.findIndex(
-          (existingJob) => existingJob.priority! < (job.priority ?? 0)
+          (existingJob) => existingJob.priority! < (job.priority ?? 0),
         );
         if (insertIndex === -1) {
           this.jobs.push(job);
@@ -447,11 +509,15 @@ export class InMemoryQueue<T> implements Queue<T> {
       this.heartbeatInterval = undefined;
     }
 
-    // Clear all recurring job intervals
+    // Clear all recurring job timers (both cron and interval)
     for (const metadata of this.recurringJobs.values()) {
-      if (metadata.intervalId) {
-        clearInterval(metadata.intervalId);
-        metadata.intervalId = undefined;
+      if (metadata.timerId) {
+        if ("cronPattern" in metadata) {
+          clearTimeout(metadata.timerId);
+        } else {
+          clearInterval(metadata.timerId);
+        }
+        metadata.timerId = undefined;
       }
       metadata.enabled = false;
     }