@checkstack/queue-memory-backend 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @checkstack/queue-memory-backend
 
+## 0.2.0
+
+### Minor Changes
+
+- 9a27800: Changed recurring job scheduling from completion-based to wall-clock scheduling.
+
+  **Breaking Change:** Recurring jobs now run on a fixed interval (like BullMQ) regardless of whether the previous job has completed. If a job takes longer than `intervalSeconds`, multiple jobs may run concurrently.
+
+  **Improvements:**
+
+  - Fixed job ID collision bug when rescheduling within the same millisecond
+  - Configuration updates via `scheduleRecurring()` now properly cancel old intervals before starting new ones
+  - Added `heartbeatIntervalMs` to config for resilient job recovery after system sleep
+
+### Patch Changes
+
+- 9a27800: Fix recurring jobs resilience and add logger support
+
+  **Rescheduling Fix:**
+  Previously, recurring job rescheduling logic was inside the `try` block of `processJob()`. When a job handler threw an exception and `maxRetries` was exhausted (or 0), the recurring job would never be rescheduled, permanently breaking the scheduling chain.
+
+  This fix moves the rescheduling logic to the `finally` block, ensuring recurring jobs are always rescheduled after execution, regardless of success or failure.
+
+  **Heartbeat Mechanism:**
+  Added a periodic heartbeat (default: 5 seconds) that checks for ready jobs and triggers processing. This ensures jobs are processed even if `setTimeout` callbacks fail to fire (e.g., after system sleep/wake cycles). Configurable via `heartbeatIntervalMs` option; set to 0 to disable.
+
+  **Logger Service Integration:**
+
+  - Added optional `logger` parameter to `QueuePlugin.createQueue()` interface
+  - `InMemoryQueue` now uses the provided logger instead of raw `console.error`
+  - Consistent with the rest of the codebase's logging patterns
+
+- Updated dependencies [9a27800]
+  - @checkstack/queue-api@0.0.6
+  - @checkstack/backend-api@0.3.1
+
 ## 0.1.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/queue-memory-backend",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {

package/src/memory-queue.test.ts

@@ -1,16 +1,34 @@
-import { describe, it, expect, beforeEach } from "bun:test";
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
 import { InMemoryQueue } from "./memory-queue";
 import type { QueueJob } from "@checkstack/queue-api";
+import type { Logger } from "@checkstack/backend-api";
+
+// Suppress console.error output during tests for failed jobs
+const testLogger: Logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
 
 describe("InMemoryQueue Consumer Groups", () => {
   let queue: InMemoryQueue<string>;
 
   beforeEach(() => {
-    queue = new InMemoryQueue("test-queue", {
-      concurrency: 10,
-      maxQueueSize: 100,
-      delayMultiplier: 0.01, // 100x faster delays for testing
-    });
+    queue = new InMemoryQueue(
+      "test-queue",
+      {
+        concurrency: 10,
+        maxQueueSize: 100,
+        delayMultiplier: 0.01, // 100x faster delays for testing
+        heartbeatIntervalMs: 0, // Disable heartbeat during tests
+      },
+      testLogger
+    );
+  });
+
+  afterEach(async () => {
+    await queue.stop();
   });
 
   describe("Broadcast Pattern (Unique Consumer Groups)", () => {
@@ -376,7 +394,7 @@ describe("InMemoryQueue Consumer Groups", () => {
       expect(processed).toEqual(["immediate"]);
 
       // Wait for delayed job (100ms + generous buffer for CI)
-      await new Promise((resolve) => setTimeout(resolve, 200));
+      await new Promise((resolve) => setTimeout(resolve, 300));
       expect(processed).toEqual(["immediate", "delayed"]);
     });
 
@@ -468,4 +486,6 @@ describe("InMemoryQueue Consumer Groups", () => {
       expect(processed).toContain("job3");
     });
   });
+
+  // NOTE: Recurring job tests are in recurring-jobs.test.ts
 });

package/src/memory-queue.ts

@@ -6,6 +6,7 @@ import {
   ConsumeOptions,
   RecurringJobDetails,
 } from "@checkstack/queue-api";
+import type { Logger } from "@checkstack/backend-api";
 import { InMemoryQueueConfig } from "./plugin";
 
 /**
@@ -69,6 +70,7 @@ interface RecurringJobMetadata<T> {
   payload: T;
   priority: number;
   enabled: boolean; // For cancellation
+  intervalId?: ReturnType<typeof setInterval>; // For wall-clock scheduling
 }
 
 /**
@@ -86,8 +88,40 @@ export class InMemoryQueue<T> implements Queue<T> {
     failed: 0,
   };
 
-  constructor(private name: string, private config: InMemoryQueueConfig) {
+  private logger: Logger;
+  private heartbeatInterval: ReturnType<typeof setInterval> | undefined;
+
+  constructor(
+    private name: string,
+    private config: InMemoryQueueConfig,
+    logger: Logger
+  ) {
     this.semaphore = new Semaphore(config.concurrency);
+    this.logger = logger;
+
+    // Start heartbeat for resilient job processing (e.g., after system sleep)
+    if (config.heartbeatIntervalMs > 0) {
+      this.heartbeatInterval = setInterval(() => {
+        if (
+          !this.stopped &&
+          this.jobs.length > 0 &&
+          this.consumerGroups.size > 0
+        ) {
+          void this.processNext();
+        }
+      }, config.heartbeatIntervalMs);
+    }
+  }
+
+  /**
+   * Schedule a callback after a delay.
+   */
+  private scheduleDelayed(ms: number, callback: () => void): void {
+    setTimeout(() => {
+      if (!this.stopped) {
+        callback();
+      }
+    }, ms);
   }
 
   async enqueue(
@@ -141,11 +175,9 @@ export class InMemoryQueue<T> implements Queue<T> {
         // Schedule processing when the job becomes available
         const scheduledDelayMs =
           options.startDelay * 1000 * (this.config.delayMultiplier ?? 1);
-        setTimeout(() => {
-          if (!this.stopped) {
-            void this.processNext();
-          }
-        }, scheduledDelayMs);
+        this.scheduleDelayed(scheduledDelayMs, () => {
+          void this.processNext();
+        });
       } else {
         void this.processNext();
       }
@@ -198,7 +230,11 @@ export class InMemoryQueue<T> implements Queue<T> {
     // Check if this is an update to an existing recurring job
     const existingMetadata = this.recurringJobs.get(jobId);
     if (existingMetadata) {
-      // UPDATE CASE: Cancel pending executions
+      // UPDATE CASE: Clear existing interval and pending executions
+      if (existingMetadata.intervalId) {
+        clearInterval(existingMetadata.intervalId);
+      }
+
       // 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
@@ -213,18 +249,40 @@ export class InMemoryQueue<T> implements Queue<T> {
       });
     }
 
-    // Store or update recurring job metadata
+    // Calculate interval in ms with delay multiplier
+    const intervalMs =
+      intervalSeconds * 1000 * (this.config.delayMultiplier ?? 1);
+
+    // Create interval for wall-clock scheduling
+    const intervalId = 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,
+        });
+      }
+    }, intervalMs);
+
+    // Store recurring job metadata with interval ID
     this.recurringJobs.set(jobId, {
       jobId,
       intervalSeconds,
       payload: data,
       priority,
       enabled: true,
+      intervalId,
     });
 
-    // Schedule first execution with new configuration
+    // Schedule first execution (with optional startDelay)
+    const firstJobId = `${jobId}:${Date.now()}-${Math.random()
+      .toString(36)
+      .slice(2, 8)}`;
     await this.enqueue(data, {
-      jobId: `${jobId}:${Date.now()}`, // Unique ID for this execution
+      jobId: firstJobId,
       startDelay,
       priority,
     });
@@ -235,7 +293,13 @@ export class InMemoryQueue<T> implements Queue<T> {
   async cancelRecurring(jobId: string): Promise<void> {
     const metadata = this.recurringJobs.get(jobId);
     if (metadata) {
-      metadata.enabled = false; // Mark as disabled to stop future rescheduling
+      metadata.enabled = false; // Mark as disabled
+
+      // Clear the interval timer
+      if (metadata.intervalId) {
+        clearInterval(metadata.intervalId);
+        metadata.intervalId = undefined;
+      }
 
       // Also cancel any pending jobs
       this.jobs = this.jobs.filter((job) => {
@@ -328,22 +392,8 @@ export class InMemoryQueue<T> implements Queue<T> {
     try {
       await consumer.handler(job);
       this.stats.completed++;
-
-      // After successful execution, check for recurring job and reschedule
-      const recurringJobId = this.findRecurringJobId(job.id);
-      if (recurringJobId) {
-        const metadata = this.recurringJobs.get(recurringJobId);
-        if (metadata?.enabled) {
-          // Reschedule for next interval
-          void this.enqueue(metadata.payload, {
-            jobId: `${recurringJobId}:${Date.now()}`,
-            startDelay: metadata.intervalSeconds,
-            priority: metadata.priority,
-          });
-        }
-      }
     } catch (error) {
-      console.error(
+      this.logger.error(
         `Job ${job.id} failed in group ${groupId} (attempt ${job.attempts}):`,
         error
       );
@@ -371,11 +421,9 @@ export class InMemoryQueue<T> implements Queue<T> {
           Math.pow(2, job.attempts!) *
           1000 *
           (this.config.delayMultiplier ?? 1);
-        setTimeout(() => {
-          if (!this.stopped) {
-            void this.processNext();
-          }
-        }, delay);
+        this.scheduleDelayed(delay, () => {
+          void this.processNext();
+        });
       } else {
         this.stats.failed++;
       }
@@ -390,23 +438,24 @@ export class InMemoryQueue<T> implements Queue<T> {
     }
   }
 
-  /**
-   * Extract the recurring job ID from an execution job ID
-   * Execution jobs have format: "recurringJobId:timestamp"
-   */
-  private findRecurringJobId(executionJobId: string): string | undefined {
-    // Check if this execution job belongs to any recurring job
-    for (const [recurringId] of this.recurringJobs) {
-      if (executionJobId.startsWith(recurringId + ":")) {
-        return recurringId;
-      }
-    }
-    return undefined;
-  }
-
   async stop(): Promise<void> {
     this.stopped = true;
 
+    // Clear heartbeat interval
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = undefined;
+    }
+
+    // Clear all recurring job intervals
+    for (const metadata of this.recurringJobs.values()) {
+      if (metadata.intervalId) {
+        clearInterval(metadata.intervalId);
+        metadata.intervalId = undefined;
+      }
+      metadata.enabled = false;
+    }
+
     // Wait for all processing jobs to complete
     while (this.processing > 0) {
       await new Promise((resolve) => setTimeout(resolve, 100));

package/src/plugin.ts

@@ -1,4 +1,5 @@
 import { QueuePlugin, Queue } from "@checkstack/queue-api";
+import type { Logger } from "@checkstack/backend-api";
 import { z } from "zod";
 import { InMemoryQueue } from "./memory-queue";
 
@@ -26,6 +27,18 @@ const configSchema = z.object({
     .describe(
       "Delay multiplier (default: 1). Only change for testing purposes - set to 0.01 for 100x faster test execution."
     ),
+  /**
+   * Interval in milliseconds for the heartbeat that checks for ready jobs.
+   * This ensures jobs are processed even if setTimeout fails (e.g., after system sleep).
+   * Set to 0 to disable.
+   */
+  heartbeatIntervalMs: z
+    .number()
+    .min(0)
+    .default(5000)
+    .describe(
+      "Heartbeat interval in ms to check for ready jobs (default: 5000). Set to 0 to disable."
+    ),
 });
 
 export type InMemoryQueueConfig = z.infer<typeof configSchema>;
@@ -38,7 +51,11 @@ export class InMemoryQueuePlugin implements QueuePlugin<InMemoryQueueConfig> {
   configVersion = 1; // Initial version
   configSchema = configSchema;
 
-  createQueue<T>(name: string, config: InMemoryQueueConfig): Queue<T> {
-    return new InMemoryQueue<T>(name, config);
+  createQueue<T>(
+    name: string,
+    config: InMemoryQueueConfig,
+    logger: Logger
+  ): Queue<T> {
+    return new InMemoryQueue<T>(name, config, logger);
   }
 }

package/src/recurring-jobs.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Recurring Job Tests for InMemoryQueue
+ */
+
+import { describe, it, expect, afterEach } from "bun:test";
+import { InMemoryQueue } from "./memory-queue";
+import type { Logger } from "@checkstack/backend-api";
+
+const testLogger: Logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
+
+function createTestQueue(name: string) {
+  return new InMemoryQueue<string>(
+    name,
+    {
+      concurrency: 10,
+      maxQueueSize: 100,
+      delayMultiplier: 0.01, // Speed up delays for testing
+      heartbeatIntervalMs: 5,
+    },
+    testLogger
+  );
+}
+
+describe("InMemoryQueue Recurring Jobs", () => {
+  let queue: InMemoryQueue<string> | undefined;
+
+  afterEach(async () => {
+    if (queue) {
+      await queue.stop();
+      queue = undefined;
+    }
+  });
+
+  it("should reschedule recurring job after successful execution", async () => {
+    queue = createTestQueue("test-reschedule");
+
+    let executionCount = 0;
+    await queue.consume(
+      async () => {
+        executionCount++;
+      },
+      { consumerGroup: "test", maxRetries: 0 }
+    );
+
+    await queue.scheduleRecurring("payload", {
+      jobId: "recurring-success",
+      intervalSeconds: 0.5, // 5ms with multiplier
+    });
+
+    // Wait for multiple executions
+    await Bun.sleep(100);
+
+    expect(executionCount).toBeGreaterThanOrEqual(2);
+  });
+
+  it("should reschedule recurring job even after handler failure", async () => {
+    queue = createTestQueue("test-failure-reschedule");
+
+    let executionCount = 0;
+    await queue.consume(
+      async () => {
+        executionCount++;
+        throw new Error("Handler failed");
+      },
+      { consumerGroup: "test", maxRetries: 0 }
+    );
+
+    await queue.scheduleRecurring("payload", {
+      jobId: "recurring-failure",
+      intervalSeconds: 0.5,
+    });
+
+    await Bun.sleep(100);
+
+    // Should still reschedule despite failures
+    expect(executionCount).toBeGreaterThanOrEqual(2);
+  });
+
+  it("should not reschedule during retries", async () => {
+    queue = createTestQueue("test-no-reschedule-during-retry");
+
+    let attempts = 0;
+    let completed = false;
+
+    await queue.consume(
+      async () => {
+        attempts++;
+        if (attempts < 3) {
+          throw new Error("Retry me");
+        }
+        completed = true;
+      },
+      { consumerGroup: "test", maxRetries: 5 }
+    );
+
+    await queue.scheduleRecurring("payload", {
+      jobId: "recurring-retry",
+      intervalSeconds: 60, // Long interval so only retries should execute
+    });
+
+    await Bun.sleep(200);
+
+    // Should complete after retries, not reschedule
+    expect(completed).toBe(true);
+    expect(attempts).toBe(3);
+  });
+
+  it("should stop scheduling when cancelled", async () => {
+    queue = createTestQueue("test-cancel");
+
+    let executionCount = 0;
+    await queue.consume(
+      async () => {
+        executionCount++;
+      },
+      { consumerGroup: "test", maxRetries: 0 }
+    );
+
+    await queue.scheduleRecurring("payload", {
+      jobId: "recurring-cancel",
+      intervalSeconds: 0.5,
+    });
+
+    await Bun.sleep(50);
+    const countBeforeCancel = executionCount;
+
+    await queue.cancelRecurring("recurring-cancel");
+    await Bun.sleep(100);
+
+    // Should not have executed more after cancellation
+    expect(countBeforeCancel).toBeGreaterThanOrEqual(1);
+    expect(executionCount).toBe(countBeforeCancel);
+  });
+
+  it("should update recurring job when called with same jobId", async () => {
+    queue = createTestQueue("test-update");
+
+    const payloads: string[] = [];
+    await queue.consume(
+      async (job) => {
+        payloads.push(job.data);
+      },
+      { consumerGroup: "test", maxRetries: 0 }
+    );
+
+    // Schedule with original payload
+    await queue.scheduleRecurring("original-payload", {
+      jobId: "recurring-update",
+      intervalSeconds: 5, // 50ms with multiplier - slow interval
+    });
+
+    await Bun.sleep(20);
+
+    // Update to new payload and faster interval
+    await queue.scheduleRecurring("updated-payload", {
+      jobId: "recurring-update",
+      intervalSeconds: 0.5, // 5ms with multiplier
+    });
+
+    await Bun.sleep(80);
+
+    // Should have the updated payload multiple times
+    const updatedPayloads = payloads.filter((p) => p === "updated-payload");
+    expect(updatedPayloads.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("should cancel old interval and pending jobs when updating", async () => {
+    queue = createTestQueue("test-update-cancels-old");
+
+    let executionCount = 0;
+    await queue.consume(
+      async () => {
+        executionCount++;
+      },
+      { consumerGroup: "test", maxRetries: 0 }
+    );
+
+    // Schedule with a long interval (won't fire again during test)
+    await queue.scheduleRecurring("payload", {
+      jobId: "recurring-test",
+      intervalSeconds: 100, // Very long, should only execute once initially
+    });
+
+    await Bun.sleep(30);
+    const countAfterFirst = executionCount;
+
+    // Update to a short interval
+    await queue.scheduleRecurring("payload", {
+      jobId: "recurring-test",
+      intervalSeconds: 0.5, // 5ms with multiplier
+    });
+
+    await Bun.sleep(80);
+
+    // Should have executed multiple times with new interval
+    expect(executionCount).toBeGreaterThan(countAfterFirst);
+    expect(executionCount - countAfterFirst).toBeGreaterThanOrEqual(2);
+  });
+});