@checkstack/queue-memory-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# @checkstack/queue-memory-backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/queue-api@0.0.2
+  - @checkstack/queue-memory-common@0.0.2
+
+## 1.0.1
+
+### Patch Changes
+
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/queue-api@1.0.1
+  - @checkstack/queue-memory-common@0.1.2
+
+## 1.0.0
+
+### Major Changes
+
+- 8e889b4: Add consumer group support to Queue API for distributed event system. BREAKING: consume() now requires ConsumeOptions with consumerGroup parameter.
+
+### Patch Changes
+
+- e4d83fc: Add BullMQ queue plugin with orphaned job cleanup
+
+  - **queue-api**: Added `listRecurringJobs()` method to Queue interface for detecting orphaned jobs
+  - **queue-bullmq-backend**: New plugin implementing BullMQ (Redis) queue backend with job schedulers, consumer groups, and distributed job persistence
+  - **queue-bullmq-common**: New common package with queue permissions
+  - **queue-memory-backend**: Implemented `listRecurringJobs()` for in-memory queue
+  - **healthcheck-backend**: Enhanced `bootstrapHealthChecks` to clean up orphaned job schedulers using `listRecurringJobs()`
+  - **test-utils-backend**: Added `listRecurringJobs()` to mock queue factory
+
+  This enables production-ready distributed queue processing with Redis persistence and automatic cleanup of orphaned jobs when health checks are deleted.
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [e4d83fc]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [8e889b4]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/backend-api@1.0.0
+  - @checkstack/queue-api@1.0.0
+  - @checkstack/queue-memory-common@0.1.1

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@checkstack/queue-memory-backend",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/queue-api": "workspace:*",
+    "@checkstack/queue-memory-common": "workspace:*",
+    "zod": "^4.2.1",
+    "@checkstack/common": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+import {
+  createBackendPlugin,
+  coreServices,
+} from "@checkstack/backend-api";
+import { InMemoryQueuePlugin } from "./plugin";
+import { permissionList } from "@checkstack/queue-memory-common";
+import { pluginMetadata } from "./plugin-metadata";
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+  register(env) {
+    env.registerPermissions(permissionList);
+
+    env.registerInit({
+      deps: {
+        queuePluginRegistry: coreServices.queuePluginRegistry,
+        logger: coreServices.logger,
+      },
+      init: async ({ queuePluginRegistry, logger }) => {
+        logger.debug("🔌 Registering In-Memory Queue Plugin...");
+        const plugin = new InMemoryQueuePlugin();
+        queuePluginRegistry.register(plugin);
+      },
+    });
+  },
+});

package/src/memory-queue.test.ts

@@ -0,0 +1,471 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { InMemoryQueue } from "./memory-queue";
+import type { QueueJob } from "@checkstack/queue-api";
+
+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
+    });
+  });
+
+  describe("Broadcast Pattern (Unique Consumer Groups)", () => {
+    it("should deliver message to all consumers with different groups", async () => {
+      const received: string[] = [];
+
+      // Register two consumers with different groups
+      await queue.consume(
+        async (job) => {
+          received.push(`consumer-1:${job.data}`);
+        },
+        { consumerGroup: "group-1", maxRetries: 0 }
+      );
+
+      await queue.consume(
+        async (job) => {
+          received.push(`consumer-2:${job.data}`);
+        },
+        { consumerGroup: "group-2", maxRetries: 0 }
+      );
+
+      // Enqueue a message
+      await queue.enqueue("test-message");
+
+      // Wait for processing
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Both consumers should receive the message
+      expect(received).toContain("consumer-1:test-message");
+      expect(received).toContain("consumer-2:test-message");
+      expect(received.length).toBe(2);
+    });
+
+    it("should deliver multiple messages to all consumer groups", async () => {
+      const received: Record<string, string[]> = {
+        "group-1": [],
+        "group-2": [],
+      };
+
+      await queue.consume(
+        async (job) => {
+          received["group-1"].push(job.data);
+        },
+        { consumerGroup: "group-1", maxRetries: 0 }
+      );
+
+      await queue.consume(
+        async (job) => {
+          received["group-2"].push(job.data);
+        },
+        { consumerGroup: "group-2", maxRetries: 0 }
+      );
+
+      // Enqueue multiple messages
+      await queue.enqueue("msg-1");
+      await queue.enqueue("msg-2");
+      await queue.enqueue("msg-3");
+
+      // Wait for processing
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      // Both groups should receive all messages
+      expect(received["group-1"]).toEqual(["msg-1", "msg-2", "msg-3"]);
+      expect(received["group-2"]).toEqual(["msg-1", "msg-2", "msg-3"]);
+    });
+  });
+
+  describe("Work-Queue Pattern (Same Consumer Group)", () => {
+    it("should distribute messages round-robin within same group", async () => {
+      const received: Record<string, string[]> = {
+        "consumer-1": [],
+        "consumer-2": [],
+      };
+
+      // Two consumers in the same group
+      await queue.consume(
+        async (job) => {
+          received["consumer-1"].push(job.data);
+        },
+        { consumerGroup: "shared-group", maxRetries: 0 }
+      );
+
+      await queue.consume(
+        async (job) => {
+          received["consumer-2"].push(job.data);
+        },
+        { consumerGroup: "shared-group", maxRetries: 0 }
+      );
+
+      // Enqueue multiple messages
+      await queue.enqueue("msg-1");
+      await queue.enqueue("msg-2");
+      await queue.enqueue("msg-3");
+      await queue.enqueue("msg-4");
+
+      // Wait for processing
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      // Messages should be distributed (round-robin)
+      const total =
+        received["consumer-1"].length + received["consumer-2"].length;
+      expect(total).toBe(4);
+
+      // Each consumer should get some messages (round-robin)
+      expect(received["consumer-1"].length).toBeGreaterThan(0);
+      expect(received["consumer-2"].length).toBeGreaterThan(0);
+
+      // All messages should be received exactly once across consumers
+      const allReceived = [
+        ...received["consumer-1"],
+        ...received["consumer-2"],
+      ].sort();
+      expect(allReceived).toEqual(["msg-1", "msg-2", "msg-3", "msg-4"]);
+    });
+
+    it("should only deliver to one consumer in the group", async () => {
+      let consumer1Count = 0;
+      let consumer2Count = 0;
+
+      await queue.consume(
+        async () => {
+          consumer1Count++;
+        },
+        { consumerGroup: "work-group", maxRetries: 0 }
+      );
+
+      await queue.consume(
+        async () => {
+          consumer2Count++;
+        },
+        { consumerGroup: "work-group", maxRetries: 0 }
+      );
+
+      // Single message
+      await queue.enqueue("test");
+
+      // Wait for processing
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Only one consumer should process it
+      expect(consumer1Count + consumer2Count).toBe(1);
+    });
+  });
+
+  describe("Retry Logic", () => {
+    it("should retry failed jobs with exponential backoff", async () => {
+      let attempts = 0;
+      const attemptTimestamps: number[] = [];
+
+      await queue.consume(
+        async (job) => {
+          attemptTimestamps.push(Date.now());
+          attempts++;
+          if (attempts < 3) {
+            throw new Error("Simulated failure");
+          }
+        },
+        { consumerGroup: "retry-group", maxRetries: 3 }
+      );
+
+      await queue.enqueue("test");
+
+      // Wait for retries (with delayMultiplier=0.01: 20ms + 40ms = 60ms + buffer)
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      // Should have tried 3 times (initial + 2 retries)
+      expect(attempts).toBe(3);
+
+      // Check exponential backoff (delays should increase)
+      if (attemptTimestamps.length >= 3) {
+        const delay1 = attemptTimestamps[1] - attemptTimestamps[0];
+        const delay2 = attemptTimestamps[2] - attemptTimestamps[1];
+
+        // With delayMultiplier=0.01: first retry after 2^1 * 1000 * 0.01 = 20ms
+        expect(delay1).toBeGreaterThanOrEqual(15); // Allow tolerance
+        expect(delay1).toBeLessThanOrEqual(50);
+
+        // Second retry after 2^2 * 1000 * 0.01 = 40ms
+        expect(delay2).toBeGreaterThanOrEqual(35);
+        expect(delay2).toBeLessThanOrEqual(80);
+
+        // Verify exponential growth (delay2 should be roughly 2x delay1)
+        expect(delay2).toBeGreaterThan(delay1);
+      }
+    });
+
+    it("should not retry beyond maxRetries", async () => {
+      let attempts = 0;
+
+      await queue.consume(
+        async () => {
+          attempts++;
+          throw new Error("Always fails");
+        },
+        { consumerGroup: "fail-group", maxRetries: 2 }
+      );
+
+      await queue.enqueue("test");
+
+      // Wait for all retries (with delayMultiplier=0.01: ~60ms total)
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      // Should try 3 times total (initial + 2 retries)
+      expect(attempts).toBe(3);
+    });
+  });
+
+  describe("Mixed Patterns", () => {
+    it("should handle both broadcast and work-queue simultaneously", async () => {
+      const broadcastReceived: string[] = [];
+      const workQueueReceived: string[] = [];
+
+      // Broadcast consumers (different groups)
+      await queue.consume(
+        async (job) => {
+          broadcastReceived.push(`broadcast-1:${job.data}`);
+        },
+        { consumerGroup: "broadcast-1", maxRetries: 0 }
+      );
+
+      await queue.consume(
+        async (job) => {
+          broadcastReceived.push(`broadcast-2:${job.data}`);
+        },
+        { consumerGroup: "broadcast-2", maxRetries: 0 }
+      );
+
+      // Work-queue consumers (same group)
+      await queue.consume(
+        async (job) => {
+          workQueueReceived.push(`work-1:${job.data}`);
+        },
+        { consumerGroup: "work-group", maxRetries: 0 }
+      );
+
+      await queue.consume(
+        async (job) => {
+          workQueueReceived.push(`work-2:${job.data}`);
+        },
+        { consumerGroup: "work-group", maxRetries: 0 }
+      );
+
+      await queue.enqueue("test-msg");
+
+      // Wait for processing
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      // Both broadcast consumers should receive
+      expect(broadcastReceived.length).toBe(2);
+      expect(broadcastReceived).toContain("broadcast-1:test-msg");
+      expect(broadcastReceived).toContain("broadcast-2:test-msg");
+
+      // Only one work-queue consumer should receive
+      expect(workQueueReceived.length).toBe(1);
+      expect(
+        workQueueReceived[0] === "work-1:test-msg" ||
+          workQueueReceived[0] === "work-2:test-msg"
+      ).toBe(true);
+    });
+  });
+
+  describe("Queue Stats", () => {
+    it("should track consumer group count", async () => {
+      await queue.consume(async () => {}, {
+        consumerGroup: "group-1",
+        maxRetries: 0,
+      });
+      await queue.consume(async () => {}, {
+        consumerGroup: "group-2",
+        maxRetries: 0,
+      });
+      await queue.consume(async () => {}, {
+        consumerGroup: "group-3",
+        maxRetries: 0,
+      });
+
+      const stats = await queue.getStats();
+      expect(stats.consumerGroups).toBe(3);
+    });
+
+    it("should track pending, processing, completed, and failed", async () => {
+      let processedCount = 0;
+
+      await queue.consume(
+        async () => {
+          processedCount++;
+          if (processedCount === 2) {
+            throw new Error("Fail second job");
+          }
+          // Simulate some processing time
+          await new Promise((resolve) => setTimeout(resolve, 50));
+        },
+        { consumerGroup: "stats-group", maxRetries: 0 }
+      );
+
+      await queue.enqueue("msg-1");
+      await queue.enqueue("msg-2");
+      await queue.enqueue("msg-3");
+
+      // Check stats during processing
+      await new Promise((resolve) => setTimeout(resolve, 25));
+      let stats = await queue.getStats();
+      expect(stats.processing).toBeGreaterThanOrEqual(0);
+
+      // Wait for completion
+      await new Promise((resolve) => setTimeout(resolve, 200));
+      stats = await queue.getStats();
+
+      expect(stats.completed).toBe(2); // msg-1 and msg-3
+      expect(stats.failed).toBe(1); // msg-2
+      expect(stats.pending).toBe(0);
+    });
+  });
+
+  describe("Delayed Jobs", () => {
+    it("should not process job until delay expires", async () => {
+      const processedTimes: number[] = [];
+      const enqueueTime = Date.now();
+
+      await queue.consume(
+        async (job) => {
+          processedTimes.push(Date.now());
+        },
+        { consumerGroup: "delay-group", maxRetries: 0 }
+      );
+
+      // Enqueue with 2-second delay (becomes 20ms with delayMultiplier=0.01)
+      await queue.enqueue("delayed-job", { startDelay: 2 });
+
+      // Check immediately - should not be processed yet
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      expect(processedTimes.length).toBe(0);
+
+      // Wait for delay to expire (20ms + generous buffer for CI)
+      await new Promise((resolve) => setTimeout(resolve, 150));
+      expect(processedTimes.length).toBe(1);
+
+      // Verify it was processed after the delay
+      const actualDelay = processedTimes[0] - enqueueTime;
+      expect(actualDelay).toBeGreaterThanOrEqual(15); // Allow tolerance
+      expect(actualDelay).toBeLessThanOrEqual(200); // Allow more tolerance for CI
+    });
+
+    it("should process non-delayed jobs immediately while delayed jobs wait", async () => {
+      const processed: string[] = [];
+
+      await queue.consume(
+        async (job) => {
+          processed.push(job.data);
+        },
+        { consumerGroup: "mixed-delay-group", maxRetries: 0 }
+      );
+
+      // Enqueue delayed job first (10s delay = 100ms with multiplier)
+      await queue.enqueue("delayed", { startDelay: 10 });
+
+      // Enqueue immediate job
+      await queue.enqueue("immediate");
+
+      // Wait for immediate job to be processed (should be done quickly)
+      // The delayed job should NOT be processed yet (100ms delay)
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      expect(processed).toEqual(["immediate"]);
+
+      // Wait for delayed job (100ms + generous buffer for CI)
+      await new Promise((resolve) => setTimeout(resolve, 200));
+      expect(processed).toEqual(["immediate", "delayed"]);
+    });
+
+    it("should respect priority with delayed jobs", async () => {
+      const processed: string[] = [];
+
+      await queue.consume(
+        async (job) => {
+          processed.push(job.data);
+        },
+        { consumerGroup: "priority-delay-group", maxRetries: 0 }
+      );
+
+      // Enqueue multiple delayed jobs with same delay but different priorities
+      // (1s delay = 10ms with multiplier)
+      await queue.enqueue("low-priority", {
+        startDelay: 1,
+        priority: 1,
+      });
+      await queue.enqueue("high-priority", {
+        startDelay: 1,
+        priority: 10,
+      });
+      await queue.enqueue("medium-priority", {
+        startDelay: 1,
+        priority: 5,
+      });
+
+      // Wait for delay to expire (10ms + buffer)
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      // Should process in priority order (highest first)
+      expect(processed).toEqual([
+        "high-priority",
+        "medium-priority",
+        "low-priority",
+      ]);
+    });
+  });
+
+  describe("Job Deduplication", () => {
+    it("should skip duplicate jobs with same jobId", async () => {
+      const processed: string[] = [];
+
+      await queue.consume(
+        async (job) => {
+          processed.push(job.data);
+        },
+        { consumerGroup: "dedup-group", maxRetries: 0 }
+      );
+
+      // Enqueue job with custom jobId
+      const jobId1 = await queue.enqueue("first", { jobId: "unique-job-1" });
+      expect(jobId1).toBe("unique-job-1");
+
+      // Try to enqueue duplicate (should return same jobId without adding to queue)
+      const jobId2 = await queue.enqueue("duplicate", {
+        jobId: "unique-job-1",
+      });
+      expect(jobId2).toBe("unique-job-1");
+
+      // Wait for processing
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Should only have processed the first job
+      expect(processed.length).toBe(1);
+      expect(processed[0]).toBe("first");
+    });
+
+    it("should allow different jobIds", async () => {
+      const processed: string[] = [];
+
+      await queue.consume(
+        async (job) => {
+          processed.push(job.data);
+        },
+        { consumerGroup: "different-group", maxRetries: 0 }
+      );
+
+      await queue.enqueue("job1", { jobId: "job-1" });
+      await queue.enqueue("job2", { jobId: "job-2" });
+      await queue.enqueue("job3", { jobId: "job-3" });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(processed.length).toBe(3);
+      expect(processed).toContain("job1");
+      expect(processed).toContain("job2");
+      expect(processed).toContain("job3");
+    });
+  });
+});

package/src/memory-queue.ts

@@ -0,0 +1,429 @@
+import {
+  Queue,
+  QueueJob,
+  QueueConsumer,
+  QueueStats,
+  ConsumeOptions,
+  RecurringJobDetails,
+} from "@checkstack/queue-api";
+import { InMemoryQueueConfig } from "./plugin";
+
+/**
+ * Extended queue job with availability tracking for delayed jobs
+ */
+interface InternalQueueJob<T> extends QueueJob<T> {
+  availableAt: Date;
+}
+
+/**
+ * Simple semaphore for concurrency control
+ */
+class Semaphore {
+  private permits: number;
+  private waiting: Array<() => void> = [];
+
+  constructor(permits: number) {
+    this.permits = permits;
+  }
+
+  async acquire(): Promise<void> {
+    if (this.permits > 0) {
+      this.permits--;
+      return;
+    }
+
+    return new Promise<void>((resolve) => {
+      this.waiting.push(resolve);
+    });
+  }
+
+  release(): void {
+    this.permits++;
+    const resolve = this.waiting.shift();
+    if (resolve) {
+      this.permits--;
+      resolve();
+    }
+  }
+}
+
+/**
+ * Consumer group state tracking
+ */
+interface ConsumerGroupState<T> {
+  consumers: Array<{
+    id: string;
+    handler: QueueConsumer<T>;
+    maxRetries: number;
+  }>;
+  nextConsumerIndex: number; // For round-robin within group
+  processedJobIds: Set<string>; // Track which jobs this group has processed
+}
+
+/**
+ * Recurring job metadata
+ */
+interface RecurringJobMetadata<T> {
+  jobId: string;
+  intervalSeconds: number;
+  payload: T;
+  priority: number;
+  enabled: boolean; // For cancellation
+}
+
+/**
+ * In-memory queue implementation with consumer group support
+ */
+export class InMemoryQueue<T> implements Queue<T> {
+  private jobs: InternalQueueJob<T>[] = [];
+  private consumerGroups = new Map<string, ConsumerGroupState<T>>();
+  private recurringJobs = new Map<string, RecurringJobMetadata<T>>();
+  private semaphore: Semaphore;
+  private stopped = false;
+  private processing = 0;
+  private stats = {
+    completed: 0,
+    failed: 0,
+  };
+
+  constructor(private name: string, private config: InMemoryQueueConfig) {
+    this.semaphore = new Semaphore(config.concurrency);
+  }
+
+  async enqueue(
+    data: T,
+    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})`
+      );
+    }
+
+    const now = new Date();
+    const delayMs = options?.startDelay
+      ? options.startDelay * 1000 * (this.config.delayMultiplier ?? 1)
+      : 0;
+    const availableAt = delayMs > 0 ? new Date(now.getTime() + delayMs) : now;
+
+    // Use custom jobId if provided, otherwise generate one
+    const jobId = options?.jobId ?? crypto.randomUUID();
+
+    // Check for duplicate jobId
+    if (options?.jobId && this.jobs.some((j) => j.id === options.jobId)) {
+      // Job with this ID already exists, skip silently
+      return options.jobId;
+    }
+
+    const job: InternalQueueJob<T> = {
+      id: jobId,
+      data,
+      priority: options?.priority ?? 0,
+      timestamp: now,
+      attempts: 0,
+      availableAt,
+    };
+
+    // Insert job in priority order (higher priority first)
+    const insertIndex = this.jobs.findIndex(
+      (existingJob) => existingJob.priority! < job.priority!
+    );
+
+    if (insertIndex === -1) {
+      this.jobs.push(job);
+    } else {
+      this.jobs.splice(insertIndex, 0, job);
+    }
+
+    // Trigger processing for all consumer groups (or schedule for later)
+    if (!this.stopped) {
+      if (options?.startDelay) {
+        // Schedule processing when the job becomes available
+        const scheduledDelayMs =
+          options.startDelay * 1000 * (this.config.delayMultiplier ?? 1);
+        setTimeout(() => {
+          if (!this.stopped) {
+            void this.processNext();
+          }
+        }, scheduledDelayMs);
+      } else {
+        void this.processNext();
+      }
+    }
+
+    return job.id;
+  }
+
+  async consume(
+    consumer: QueueConsumer<T>,
+    options: ConsumeOptions
+  ): Promise<void> {
+    const { consumerGroup, maxRetries = 3 } = options;
+
+    // Get or create consumer group
+    let groupState = this.consumerGroups.get(consumerGroup);
+    if (!groupState) {
+      groupState = {
+        consumers: [],
+        nextConsumerIndex: 0,
+        processedJobIds: new Set(),
+      };
+      this.consumerGroups.set(consumerGroup, groupState);
+    }
+
+    // Add consumer to group
+    groupState.consumers.push({
+      id: crypto.randomUUID(),
+      handler: consumer,
+      maxRetries,
+    });
+
+    // Start processing existing jobs
+    if (!this.stopped) {
+      void this.processNext();
+    }
+  }
+
+  async scheduleRecurring(
+    data: T,
+    options: {
+      jobId: string;
+      intervalSeconds: number;
+      startDelay?: number;
+      priority?: number;
+    }
+  ): Promise<string> {
+    const { jobId, intervalSeconds, startDelay = 0, priority = 0 } = options;
+
+    // Check if this is an update to an existing recurring job
+    const existingMetadata = this.recurringJobs.get(jobId);
+    if (existingMetadata) {
+      // UPDATE CASE: Cancel pending executions
+      // 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 true; // Keep other jobs
+      });
+    }
+
+    // Store or update recurring job metadata
+    this.recurringJobs.set(jobId, {
+      jobId,
+      intervalSeconds,
+      payload: data,
+      priority,
+      enabled: true,
+    });
+
+    // Schedule first execution with new configuration
+    await this.enqueue(data, {
+      jobId: `${jobId}:${Date.now()}`, // Unique ID for this execution
+      startDelay,
+      priority,
+    });
+
+    return jobId;
+  }
+
+  async cancelRecurring(jobId: string): Promise<void> {
+    const metadata = this.recurringJobs.get(jobId);
+    if (metadata) {
+      metadata.enabled = false; // Mark as disabled to stop future rescheduling
+
+      // 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);
+          }
+          return false;
+        }
+        return true;
+      });
+    }
+  }
+
+  async listRecurringJobs(): Promise<string[]> {
+    return [...this.recurringJobs.keys()];
+  }
+
+  async getRecurringJobDetails(
+    jobId: string
+  ): Promise<RecurringJobDetails<T> | undefined> {
+    const metadata = this.recurringJobs.get(jobId);
+    if (!metadata || !metadata.enabled) {
+      return undefined;
+    }
+    return {
+      jobId: metadata.jobId,
+      data: metadata.payload,
+      intervalSeconds: metadata.intervalSeconds,
+      priority: metadata.priority,
+    };
+  }
+
+  async getInFlightCount(): Promise<number> {
+    return this.processing;
+  }
+
+  private async processNext(): Promise<void> {
+    if (this.jobs.length === 0 || this.consumerGroups.size === 0) {
+      return;
+    }
+
+    const now = new Date();
+
+    // For each consumer group, check if there's a job they haven't processed
+    for (const [groupId, groupState] of this.consumerGroups.entries()) {
+      if (groupState.consumers.length === 0) continue;
+
+      // Find next unprocessed job for this group that is available
+      const job = this.jobs.find(
+        (j) => !groupState.processedJobIds.has(j.id) && j.availableAt <= now
+      );
+
+      if (!job) continue;
+
+      // Mark as processed by this group
+      groupState.processedJobIds.add(job.id);
+
+      // Select consumer via round-robin
+      const consumerIndex =
+        groupState.nextConsumerIndex % groupState.consumers.length;
+      const selectedConsumer = groupState.consumers[consumerIndex];
+      groupState.nextConsumerIndex++;
+
+      // Process job (don't await - process asynchronously)
+      void this.processJob(job, selectedConsumer, groupId, groupState);
+    }
+
+    // Remove fully processed jobs
+    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)
+      );
+    });
+  }
+
+  private async processJob(
+    job: InternalQueueJob<T>,
+    consumer: ConsumerGroupState<T>["consumers"][0],
+    groupId: string,
+    groupState: ConsumerGroupState<T>
+  ): Promise<void> {
+    await this.semaphore.acquire();
+    this.processing++;
+
+    let isRetrying = false;
+
+    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(
+        `Job ${job.id} failed in group ${groupId} (attempt ${job.attempts}):`,
+        error
+      );
+
+      // Retry logic
+      if (job.attempts! < consumer.maxRetries) {
+        job.attempts!++;
+        isRetrying = true;
+
+        // Remove from processed set to allow retry
+        groupState.processedJobIds.delete(job.id);
+
+        // 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)
+        );
+        if (insertIndex === -1) {
+          this.jobs.push(job);
+        } else {
+          this.jobs.splice(insertIndex, 0, job);
+        }
+
+        // Re-trigger processing with exponential backoff
+        const delay =
+          Math.pow(2, job.attempts!) *
+          1000 *
+          (this.config.delayMultiplier ?? 1);
+        setTimeout(() => {
+          if (!this.stopped) {
+            void this.processNext();
+          }
+        }, delay);
+      } else {
+        this.stats.failed++;
+      }
+    } finally {
+      this.processing--;
+      this.semaphore.release();
+
+      // Process next job if available (but not if we're retrying - setTimeout will handle it)
+      if (!isRetrying && this.jobs.length > 0 && !this.stopped) {
+        void this.processNext();
+      }
+    }
+  }
+
+  /**
+   * 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;
+
+    // Wait for all processing jobs to complete
+    while (this.processing > 0) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  async getStats(): Promise<QueueStats> {
+    return {
+      pending: this.jobs.length,
+      processing: this.processing,
+      completed: this.stats.completed,
+      failed: this.stats.failed,
+      consumerGroups: this.consumerGroups.size,
+    };
+  }
+
+  async testConnection(): Promise<void> {
+    // In-memory queue is always available
+  }
+}

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the Queue Memory backend.
+ * This is the single source of truth for the plugin ID.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "queue-memory",
+});

package/src/plugin.ts

@@ -0,0 +1,44 @@
+import { QueuePlugin, Queue } from "@checkstack/queue-api";
+import { z } from "zod";
+import { InMemoryQueue } from "./memory-queue";
+
+const configSchema = z.object({
+  concurrency: z
+    .number()
+    .min(1)
+    .max(100)
+    .default(10)
+    .describe("Maximum number of concurrent jobs to process"),
+  maxQueueSize: z
+    .number()
+    .min(1)
+    .default(10_000)
+    .describe("Maximum number of jobs that can be queued"),
+  /**
+   * Multiplier for all delays (retry backoff, startDelay).
+   * Default is 1 (normal). Set to 0.01 in tests for 100x faster delays.
+   */
+  delayMultiplier: z
+    .number()
+    .min(0)
+    .max(1)
+    .default(1)
+    .describe(
+      "Delay multiplier (default: 1). Only change for testing purposes - set to 0.01 for 100x faster test execution."
+    ),
+});
+
+export type InMemoryQueueConfig = z.infer<typeof configSchema>;
+
+export class InMemoryQueuePlugin implements QueuePlugin<InMemoryQueueConfig> {
+  id = "memory";
+  displayName = "In-Memory Queue";
+  description =
+    "Simple in-memory queue for development and single-instance deployments";
+  configVersion = 1; // Initial version
+  configSchema = configSchema;
+
+  createQueue<T>(name: string, config: InMemoryQueueConfig): Queue<T> {
+    return new InMemoryQueue<T>(name, config);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}