groupmq-plus 1.1.0

package/dist/lua/reserve.lua

@@ -0,0 +1,161 @@
+-- argv: ns, nowEpochMs, vtMs, scanLimit
+local ns = KEYS[1]
+local now = tonumber(ARGV[1])
+local vt = tonumber(ARGV[2])
+local scanLimit = tonumber(ARGV[3]) or 20
+
+local readyKey = ns .. ":ready"
+
+-- Respect paused state
+if redis.call("GET", ns .. ":paused") then
+  return nil
+end
+
+-- STALLED JOB RECOVERY WITH THROTTLING
+-- Check for stalled jobs periodically to avoid overhead in hot path
+-- This ensures stalled jobs are recovered even in high-load systems
+-- Check interval is adaptive: 1/4 of jobTimeout (to check 4x during visibility window), max 5s
+local processingKey = ns .. ":processing"
+local stalledCheckKey = ns .. ":stalled:lastcheck"
+local lastCheck = tonumber(redis.call("GET", stalledCheckKey)) or 0
+local stalledCheckInterval = math.min(math.floor(vt / 4), 5000)
+
+local shouldCheckStalled = (now - lastCheck) >= stalledCheckInterval
+
+-- Get available groups
+local groups = redis.call("ZRANGE", readyKey, 0, scanLimit - 1, "WITHSCORES")
+
+-- Check for stalled jobs if: queue is empty OR it's time for periodic check
+if (not groups or #groups == 0) or shouldCheckStalled then
+  if shouldCheckStalled then
+    redis.call("SET", stalledCheckKey, tostring(now))
+  end
+  
+  local expiredJobs = redis.call("ZRANGEBYSCORE", processingKey, 0, now)
+  for _, jobId in ipairs(expiredJobs) do
+    local procKey = ns .. ":processing:" .. jobId
+    local procData = redis.call("HMGET", procKey, "groupId", "deadlineAt")
+    local gid = procData[1]
+    local deadlineAt = tonumber(procData[2])
+    if gid and deadlineAt and now > deadlineAt then
+      local jobKey = ns .. ":job:" .. jobId
+      local jobScore = redis.call("HGET", jobKey, "score")
+      if jobScore then
+        local gZ = ns .. ":g:" .. gid
+        redis.call("ZADD", gZ, tonumber(jobScore), jobId)
+        local head = redis.call("ZRANGE", gZ, 0, 0, "WITHSCORES")
+        if head and #head >= 2 then
+          local headScore = tonumber(head[2])
+          redis.call("ZADD", readyKey, headScore, gid)
+        end
+        redis.call("DEL", ns .. ":lock:" .. gid)
+        redis.call("DEL", procKey)
+        redis.call("ZREM", processingKey, jobId)
+      end
+    end
+  end
+  
+  -- Refresh groups after recovery (only if we didn't have any before)
+  if not groups or #groups == 0 then
+    groups = redis.call("ZRANGE", readyKey, 0, scanLimit - 1, "WITHSCORES")
+  end
+end
+
+if not groups or #groups == 0 then
+  return nil
+end
+
+local chosenGid = nil
+local chosenIndex = nil
+local headJobId = nil
+local job = nil
+
+-- Try to atomically acquire a group and its head job
+-- BullMQ-style: use per-group active list instead of group locks
+for i = 1, #groups, 2 do
+  local gid = groups[i]
+  local gZ = ns .. ":g:" .. gid
+  local groupActiveKey = ns .. ":g:" .. gid .. ":active"
+  local configKey = ns .. ":config:" .. gid
+  
+  -- [PHASE 2 MODIFICATION START]
+  -- Check concurrency limit
+  local activeCount = redis.call("LLEN", groupActiveKey)
+  local limit = tonumber(redis.call("HGET", configKey, "concurrency")) or 1
+  
+  if activeCount < limit then
+    -- Group has capacity, try to get head job
+    local head = redis.call("ZRANGE", gZ, 0, 0, "WITHSCORES")
+    if head and #head >= 2 then
+      local headJobId = head[1]
+      local headJobKey = ns .. ":job:" .. headJobId
+      
+      -- Skip if head job is delayed (will be promoted later)
+      local jobStatus = redis.call("HGET", headJobKey, "status")
+      if jobStatus ~= "delayed" then
+        -- Pop the job and push to active list atomically
+        local zpop = redis.call("ZPOPMIN", gZ, 1)
+        if zpop and #zpop > 0 then
+          headJobId = zpop[1]
+          -- Read the popped job (use headJobId to avoid races)
+          headJobKey = ns .. ":job:" .. headJobId
+          job = redis.call("HMGET", headJobKey, "id","groupId","data","attempts","maxAttempts","seq","timestamp","orderMs","score")
+          
+          -- Push to group active list
+          redis.call("LPUSH", groupActiveKey, headJobId)
+          
+          chosenGid = gid
+          chosenIndex = (i + 1) / 2 - 1
+          -- Mark job as processing for accurate stalled detection and idempotency
+          redis.call("HSET", headJobKey, "status", "processing")
+          break
+        end
+      end
+    end
+  end
+  -- [PHASE 2 MODIFICATION END]
+end
+
+if not chosenGid or not job then
+  return nil
+end
+
+local id, groupId, payload, attempts, maxAttempts, seq, enq, orderMs, score = job[1], job[2], job[3], job[4], job[5], job[6], job[7], job[8], job[9]
+
+-- Validate job data exists (handle corrupted/missing job hash)
+if not id or id == false then
+  -- Job hash is missing/corrupted, clean up group active list
+  local groupActiveKey = ns .. ":g:" .. chosenGid .. ":active"
+  redis.call("LREM", groupActiveKey, 1, headJobId)
+  
+  -- Re-add next job to ready queue if exists
+  local gZ = ns .. ":g:" .. chosenGid
+  local nextHead = redis.call("ZRANGE", gZ, 0, 0, "WITHSCORES")
+  if nextHead and #nextHead >= 2 then
+    local nextScore = tonumber(nextHead[2])
+    redis.call("ZADD", readyKey, nextScore, chosenGid)
+  end
+  
+  return nil
+end
+
+-- Remove the group from ready queue
+redis.call("ZREMRANGEBYRANK", readyKey, chosenIndex, chosenIndex)
+
+local procKey = ns .. ":processing:" .. id
+local deadline = now + vt
+redis.call("HSET", procKey, "groupId", chosenGid, "deadlineAt", tostring(deadline))
+
+local processingKey2 = ns .. ":processing"
+redis.call("ZADD", processingKey2, deadline, id)
+
+local gZ = ns .. ":g:" .. chosenGid
+local nextHead = redis.call("ZRANGE", gZ, 0, 0, "WITHSCORES")
+if nextHead and #nextHead >= 2 then
+  local nextScore = tonumber(nextHead[2])
+  redis.call("ZADD", readyKey, nextScore, chosenGid)
+end
+
+return id .. "|||" .. groupId .. "|||" .. payload .. "|||" .. attempts .. "|||" .. maxAttempts .. "|||" .. seq .. "|||" .. enq .. "|||" .. orderMs .. "|||" .. score .. "|||" .. deadline
+
+

package/dist/lua/retry.lua

@@ -0,0 +1,53 @@
+-- argv: ns, jobId, backoffMs
+local ns = KEYS[1]
+local jobId = ARGV[1]
+local backoffMs = tonumber(ARGV[2]) or 0
+
+local jobKey = ns .. ":job:" .. jobId
+local gid = redis.call("HGET", jobKey, "groupId")
+local attempts = tonumber(redis.call("HINCRBY", jobKey, "attempts", 1))
+local maxAttempts = tonumber(redis.call("HGET", jobKey, "maxAttempts"))
+
+redis.call("DEL", ns .. ":processing:" .. jobId)
+redis.call("ZREM", ns .. ":processing", jobId)
+
+-- BullMQ-style: Remove from group active list
+local groupActiveKey = ns .. ":g:" .. gid .. ":active"
+redis.call("LREM", groupActiveKey, 1, jobId)
+
+if attempts > maxAttempts then
+  return -1
+end
+
+local score = tonumber(redis.call("HGET", jobKey, "score"))
+local gZ = ns .. ":g:" .. gid
+
+-- Re-add job to group
+redis.call("ZADD", gZ, score, jobId)
+
+-- If backoffMs > 0, delay the retry
+if backoffMs > 0 then
+  local now = tonumber(redis.call("TIME")[1]) * 1000
+  local delayUntil = now + backoffMs
+  
+  -- Move to delayed set
+  local delayedKey = ns .. ":delayed"
+  redis.call("ZADD", delayedKey, delayUntil, jobId)
+  redis.call("HSET", jobKey, "runAt", tostring(delayUntil), "status", "delayed")
+  
+  -- Don't add to ready yet - will be added when promoted
+  -- (delayed jobs block their group)
+else
+  -- No backoff - immediate retry
+  redis.call("HSET", jobKey, "status", "waiting")
+  
+  -- Add group to ready queue
+  local head = redis.call("ZRANGE", gZ, 0, 0, "WITHSCORES")
+  if head and #head >= 2 then
+    local headScore = tonumber(head[2])
+    local readyKey = ns .. ":ready"
+    redis.call("ZADD", readyKey, headScore, gid)
+  end
+end
+
+return attempts

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "groupmq-plus",
+  "version": "1.1.0",
+  "description": "Per-group FIFO queue on Redis with visibility timeouts and retries.",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "author": "OpenPanel.dev <hello@openpanel.dev> (https://openpanel.dev)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Openpanel-dev/groupmq"
+  },
+  "bugs": {
+    "url": "https://github.com/Openpanel-dev/groupmq/issues"
+  },
+  "homepage": "https://github.com/Openpanel-dev/groupmq#readme",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "redis",
+    "queue",
+    "fifo",
+    "worker",
+    "node",
+    "typescript"
+  ],
+  "dependencies": {
+    "cron-parser": "^4.9.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.2.4",
+    "@bull-board/api": "^6.13.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^10.3.5",
+    "@semantic-release/npm": "^11.0.2",
+    "@types/node": "^20.12.12",
+    "@types/pidusage": "^2.0.5",
+    "bullmq": "^5.58.7",
+    "commander": "^14.0.1",
+    "conventional-changelog-conventionalcommits": "^7",
+    "ioredis": "^5.4.1",
+    "jiti": "^2.5.1",
+    "pidusage": "^4.0.1",
+    "pino": "^9.12.0",
+    "pretty-ms": "^9.3.0",
+    "semantic-release": "^23.0.0",
+    "tsdown": "^0.15.4",
+    "typescript": "^5.6.2",
+    "vitest": "^2.0.5",
+    "winston": "^3.18.3"
+  },
+  "peerDependencies": {
+    "ioredis": ">=5"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --format cjs --dts --sourcemap && node scripts/copy-lua.mjs",
+    "prebuild": "pnpm test:lua",
+    "test": "vitest run --no-file-parallelism",
+    "test:lua": "node scripts/validate-lua-scripts.js",
+    "test:many": "for i in {1..200}; do pnpm run test; done",
+    "dev:test": "vitest --watch",
+    "monitor": "jiti cli.ts",
+    "benchmark": "jiti benchmark/benchmark.ts",
+    "benchmark:both": "pnpm benchmark --mq both --jobs 5000 --workers 4 --job-type cpu --multi-process && pnpm format:fix -- benchmark/results",
+    "benchmark:both:empty": "pnpm benchmark --mq both --jobs 5000 --workers 4 --job-type empty --multi-process && pnpm format:fix -- benchmark/results",
+    "benchmark:groupmq": "pnpm benchmark --mq groupmq --jobs 5000 --workers 4 --job-type cpu --multi-process && pnpm format:fix -- benchmark/results",
+    "benchmark:groupmq:dragonfly": "pnpm benchmark --db dragonfly --mq groupmq --jobs 5000 --workers 10 --job-type cpu --multi-process && pnpm format:fix -- benchmark/results",
+    "benchmark:bullmq": "pnpm benchmark --mq bullmq --jobs 5000 --workers 4 --job-type cpu --multi-process && pnpm format:fix -- benchmark/results",
+    "format": "biome format .",
+    "format:fix": "biome format --write",
+    "format:fixall": "biome format --write .",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write --unsafe .",
+    "typecheck": "tsc --noEmit"
+  }
+}