@checkstack/queue-memory-backend 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @checkstack/queue-memory-backend
 
+## 0.2.2
+
+### Patch Changes
+
+- Updated dependencies [d94121b]
+  - @checkstack/backend-api@0.3.3
+  - @checkstack/queue-api@0.1.1
+
+## 0.2.1
+
+### Patch Changes
+
+- Updated dependencies [180be38]
+- Updated dependencies [7a23261]
+  - @checkstack/queue-api@0.1.0
+  - @checkstack/common@0.3.0
+  - @checkstack/backend-api@0.3.2
+  - @checkstack/queue-memory-common@0.1.1
+
 ## 0.2.0
 
 ### Minor Changes

package/package.json

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

package/src/benchmark.ts

@@ -0,0 +1,215 @@
+#!/usr/bin/env bun
+/**
+ * Queue Load Benchmark Script
+ *
+ * Run manually to measure queue throughput at various concurrency levels:
+ *
+ *   cd plugins/queue-memory-backend
+ *   bun run src/benchmark.ts
+ *
+ * This is NOT a test file - it runs benchmarks and prints results.
+ */
+
+import { InMemoryQueue } from "./memory-queue";
+import type { Logger } from "@checkstack/backend-api";
+
+const testLogger: Logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
+
+/**
+ * Simulate an I/O-bound job (like a health check)
+ */
+async function simulateIOWork(durationMs: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, durationMs));
+}
+
+/**
+ * Calculate percentile from sorted array
+ */
+function percentile(sortedValues: number[], p: number): number {
+  const index = Math.ceil((p / 100) * sortedValues.length) - 1;
+  return sortedValues[Math.max(0, index)];
+}
+
+interface LoadTestResult {
+  concurrency: number;
+  totalJobs: number;
+  durationMs: number;
+  jobsPerSecond: number;
+  avgLatencyMs: number;
+  p50LatencyMs: number;
+  p95LatencyMs: number;
+  p99LatencyMs: number;
+}
+
+/**
+ * Run a load test at a specific concurrency level
+ */
+async function runLoadTest(props: {
+  concurrency: number;
+  totalJobs: number;
+  jobDurationMs: number;
+}): Promise<LoadTestResult> {
+  const { concurrency, totalJobs, jobDurationMs } = props;
+
+  const queue = new InMemoryQueue<number>(
+    `load-test-${concurrency}`,
+    {
+      concurrency,
+      maxQueueSize: totalJobs + 100,
+      delayMultiplier: 1,
+      heartbeatIntervalMs: 0,
+    },
+    testLogger
+  );
+
+  const latencies: number[] = [];
+  let completed = 0;
+  const startTimes = new Map<number, number>();
+
+  await queue.consume(
+    async (job) => {
+      const jobStart = startTimes.get(job.data) ?? Date.now();
+      await simulateIOWork(jobDurationMs);
+      const latency = Date.now() - jobStart;
+      latencies.push(latency);
+      completed++;
+    },
+    { consumerGroup: "load-test-group", maxRetries: 0 }
+  );
+
+  const testStart = Date.now();
+  for (let i = 0; i < totalJobs; i++) {
+    startTimes.set(i, Date.now());
+    await queue.enqueue(i);
+  }
+
+  while (completed < totalJobs) {
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  const testDuration = Date.now() - testStart;
+
+  await queue.stop();
+
+  const sortedLatencies = latencies.toSorted((a, b) => a - b);
+  const avgLatency =
+    latencies.reduce((sum, l) => sum + l, 0) / latencies.length;
+
+  return {
+    concurrency,
+    totalJobs,
+    durationMs: testDuration,
+    jobsPerSecond: (totalJobs / testDuration) * 1000,
+    avgLatencyMs: Math.round(avgLatency),
+    p50LatencyMs: percentile(sortedLatencies, 50),
+    p95LatencyMs: percentile(sortedLatencies, 95),
+    p99LatencyMs: percentile(sortedLatencies, 99),
+  };
+}
+
+function formatResult(result: LoadTestResult): string {
+  return [
+    `Concurrency: ${result.concurrency}`,
+    `  Jobs: ${result.totalJobs} in ${result.durationMs}ms`,
+    `  Throughput: ${result.jobsPerSecond.toFixed(1)} jobs/sec`,
+    `  Latency: avg=${result.avgLatencyMs}ms, p50=${result.p50LatencyMs}ms, p95=${result.p95LatencyMs}ms, p99=${result.p99LatencyMs}ms`,
+  ].join("\n");
+}
+
+// Main benchmark runner
+async function main() {
+  console.log("\n🚀 Queue Load Benchmark\n");
+  console.log("=".repeat(60));
+
+  // Test 1: Fast jobs
+  console.log("\n📊 Fast Jobs (10ms simulated I/O)\n");
+  for (const concurrency of [5, 10, 25, 50]) {
+    const result = await runLoadTest({
+      concurrency,
+      totalJobs: 100,
+      jobDurationMs: 10,
+    });
+    console.log(formatResult(result));
+    console.log("-".repeat(60));
+  }
+
+  // Test 2: Realistic jobs
+  console.log("\n📊 Realistic Jobs (50ms simulated I/O)\n");
+  for (const concurrency of [5, 10, 25, 50]) {
+    const result = await runLoadTest({
+      concurrency,
+      totalJobs: 100,
+      jobDurationMs: 50,
+    });
+    console.log(formatResult(result));
+    console.log("-".repeat(60));
+  }
+
+  // Test 3: Slow jobs showing concurrency benefit
+  console.log("\n📊 Slow Jobs (200ms) - Demonstrating Concurrency Benefits\n");
+  const results: LoadTestResult[] = [];
+  for (const concurrency of [1, 5, 10, 25]) {
+    const result = await runLoadTest({
+      concurrency,
+      totalJobs: 50,
+      jobDurationMs: 200,
+    });
+    results.push(result);
+    console.log(formatResult(result));
+    console.log("-".repeat(60));
+  }
+  const sequential = results.find((r) => r.concurrency === 1)!;
+  const parallel = results.find((r) => r.concurrency === 25)!;
+  console.log(
+    `\n✨ Speedup: ${(sequential.durationMs / parallel.durationMs).toFixed(
+      1
+    )}x faster with concurrency=25`
+  );
+
+  // Test 4: Burst load
+  console.log("\n📊 Burst Load (500 jobs at once)\n");
+  const burstResult = await runLoadTest({
+    concurrency: 50,
+    totalJobs: 500,
+    jobDurationMs: 20,
+  });
+  console.log(formatResult(burstResult));
+
+  // Test 5: Max throughput
+  console.log("\n📊 Max Throughput (minimal job duration)\n");
+  const maxResult = await runLoadTest({
+    concurrency: 100,
+    totalJobs: 1000,
+    jobDurationMs: 1,
+  });
+  console.log(formatResult(maxResult));
+  console.log(
+    `\n✨ Max throughput: ${maxResult.jobsPerSecond.toFixed(0)} jobs/sec`
+  );
+
+  // Capacity planning guidance
+  console.log("\n" + "=".repeat(60));
+  console.log("📋 CAPACITY PLANNING GUIDANCE");
+  console.log("=".repeat(60));
+  console.log(`
+Throughput Formula: jobs/sec ≈ concurrency / avg_job_duration_seconds
+
+Concurrency Settings:
+  - Default: 10 (conservative)
+  - Moderate: 25-50 (I/O-bound checks)
+  - Aggressive: 100 (max, watch resources)
+
+Bottlenecks: DB pool, rate limits, memory, sockets
+
+Recommendations:
+  - Start with concurrency=10
+  - Increase if jobs queue but CPU/memory low
+  - Use BullMQ for horizontal scaling
+`);
+}
+
+await main();

package/src/memory-queue.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { describe, it, expect, beforeEach, afterEach, jest } from "bun:test";
 import { InMemoryQueue } from "./memory-queue";
 import type { QueueJob } from "@checkstack/queue-api";
 import type { Logger } from "@checkstack/backend-api";
@@ -345,12 +345,14 @@ describe("InMemoryQueue Consumer Groups", () => {
 
   describe("Delayed Jobs", () => {
     it("should not process job until delay expires", async () => {
-      const processedTimes: number[] = [];
-      const enqueueTime = Date.now();
+      // Use fake timers for deterministic behavior
+      jest.useFakeTimers();
+
+      let processed = false;
 
       await queue.consume(
-        async (job) => {
-          processedTimes.push(Date.now());
+        async () => {
+          processed = true;
         },
         { consumerGroup: "delay-group", maxRetries: 0 }
       );
@@ -358,21 +360,23 @@ describe("InMemoryQueue Consumer Groups", () => {
       // 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);
+      // Advance time but NOT past the delay (20ms)
+      jest.advanceTimersByTime(15);
+      await Promise.resolve();
+      expect(processed).toBe(false);
 
-      // Wait for delay to expire (20ms + generous buffer for CI)
-      await new Promise((resolve) => setTimeout(resolve, 150));
-      expect(processedTimes.length).toBe(1);
+      // Advance past the delay
+      jest.advanceTimersByTime(10);
+      await Promise.resolve();
+      expect(processed).toBe(true);
 
-      // 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
+      jest.useRealTimers();
     });
 
     it("should process non-delayed jobs immediately while delayed jobs wait", async () => {
+      // Use fake timers to make this test completely deterministic
+      jest.useFakeTimers();
+
       const processed: string[] = [];
 
       await queue.consume(
@@ -382,23 +386,33 @@ describe("InMemoryQueue Consumer Groups", () => {
         { consumerGroup: "mixed-delay-group", maxRetries: 0 }
       );
 
-      // Enqueue delayed job first (10s delay = 100ms with multiplier)
+      // Enqueue delayed job first (10s delay = 100ms with 0.01 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));
+      // Advance timers just enough for immediate job to process, but NOT the delayed job
+      jest.advanceTimersByTime(10);
+      // Flush the promise queue to let the async handler complete
+      await Promise.resolve();
+
       expect(processed).toEqual(["immediate"]);
 
-      // Wait for delayed job (100ms + generous buffer for CI)
-      await new Promise((resolve) => setTimeout(resolve, 300));
+      // Advance past the delay (100ms total needed)
+      jest.advanceTimersByTime(100);
+      await Promise.resolve();
+
       expect(processed).toEqual(["immediate", "delayed"]);
+
+      // Restore real timers
+      jest.useRealTimers();
     });
 
     it("should respect priority with delayed jobs", async () => {
+      // Use fake timers for deterministic behavior
+      jest.useFakeTimers();
+
       const processed: string[] = [];
 
       await queue.consume(
@@ -423,8 +437,9 @@ describe("InMemoryQueue Consumer Groups", () => {
         priority: 5,
       });
 
-      // Wait for delay to expire (10ms + buffer)
-      await new Promise((resolve) => setTimeout(resolve, 50));
+      // Advance past the delay (10ms)
+      jest.advanceTimersByTime(15);
+      await Promise.resolve();
 
       // Should process in priority order (highest first)
       expect(processed).toEqual([
@@ -432,6 +447,8 @@ describe("InMemoryQueue Consumer Groups", () => {
         "medium-priority",
         "low-priority",
       ]);
+
+      jest.useRealTimers();
     });
   });