redis-smq 9.0.0-next.7 → 9.0.0-next.9

package/CHANGELOG.md

@@ -3,6 +3,34 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [9.0.0-next.9](https://github.com/weyoss/redis-smq/compare/v9.0.0-next.8...v9.0.0-next.9) (2025-10-21)
+
+### 🐛 Bug Fixes
+
+- **redis-smq:** add missing RoutingKeyRequiredError class ([2a76b66](https://github.com/weyoss/redis-smq/commit/2a76b668a698cd79f8cb437a642d5062067cd149))
+
+### 📝 Documentation
+
+- **redis-smq:** update documentation and improve md formatting ([c659b9f](https://github.com/weyoss/redis-smq/commit/c659b9f8f4b026d731ddaf94228ce871ee56f14a))
+
+### ♻️ Code Refactoring
+
+- **redis-smq:** rename QueueConsumerGroupsCache to PubSubTargetResolver, clean up Producer docs ([1ea5669](https://github.com/weyoss/redis-smq/commit/1ea566959e97b0b695cea85b9f2117903273320d))
+
+## [9.0.0-next.8](https://github.com/weyoss/redis-smq/compare/v9.0.0-next.7...v9.0.0-next.8) (2025-10-18)
+
+### ✨ Features
+
+- **redis-smq:** make consumerGroupId optional for PubSub queue consumers ([0529efd](https://github.com/weyoss/redis-smq/commit/0529efd3ab38ba6f423143af344b30d2ef1cc4a4))
+
+### 🐛 Bug Fixes
+
+- **redis-smq:** check consumer group existence when relevant ([1711ac1](https://github.com/weyoss/redis-smq/commit/1711ac1db83ae8ca1e65947c33ca2878f49e15ed))
+
+### 📝 Documentation
+
+- **redis-smq:** clarify consumer group behavior for PubSub queues ([84f0e48](https://github.com/weyoss/redis-smq/commit/84f0e484bdca19085d067d738bb9d1adaa825ca1))
+
 ## [9.0.0-next.7](https://github.com/weyoss/redis-smq/compare/v9.0.0-next.6...v9.0.0-next.7) (2025-10-13)
 
 **Note:** Version bump only for package redis-smq

package/dist/cjs/src/common/redis-client/scripts/lua/publish-message.lua

@@ -8,13 +8,14 @@
 -- KEYS[3]: keyQueuePending
 -- KEYS[4]: keyQueueScheduled
 -- KEYS[5]: keyQueueMessages
--- KEYS[6]: keyMessage
+-- KEYS[6]: keyQueueConsumerGroups
+-- KEYS[7]: keyMessage
 --
 -- ARGV layout:
 -- ARGV[1-11]: Queue property keys and scheduling values
--- ARGV[12-34]: Message property keys (22 keys)
--- ARGV[35-57]: Message property values (22 values)
-
+-- ARGV[12-34]: Message property keys (23 keys)
+-- ARGV[35-57]: Message property values (23 values)
+-- ARGV[58]: consumerGroupId
 --
 -- This script depends on 'shared-procedures/publish-message.lua'.
 -- The content of 'shared-procedures/publish-message.lua' must be prepended to this script before loading it into Redis.

package/dist/cjs/src/common/redis-client/scripts/lua/publish-scheduled.lua

@@ -1,27 +1,29 @@
 -- Description:
 -- Publishes due scheduled messages for a SINGLE queue. This script handles two cases:
--- 1. Simple scheduled message: The message is moved to the pending queue.
--- 2. Repeating scheduled message: A new message is created and published, and the original is rescheduled.
+-- 1. Simple scheduled message: The message is moved to the pending queue. If the target consumer group is gone, it is moved to the dead-letter queue.
+-- 2. Repeating scheduled message: A new message is created and published. If the target consumer group is gone, the original repeating message is dead-lettered to terminate its cycle, and the new message for the current firing is discarded.
 --
 -- This script depends on 'shared-procedures/publish-message.lua'.
 -- The content of 'shared-procedures/publish-message.lua' must be prepended to this script before loading it into Redis.
 --
 -- KEYS:
---   Static Keys (1-5):
+--   Static Keys (1-7):
 --     KEYS[1]: keyQueueProperties
 --     KEYS[2]: keyQueuePending
 --     KEYS[3]: keyQueueMessages
 --     KEYS[4]: keyQueuePriorityPending
 --     KEYS[5]: keyQueueScheduled
---   Dynamic Keys (6...): A repeating pair for each message.
+--     KEYS[6]: keyQueueDeadLettered
+--     KEYS[7]: keyQueueConsumerGroups
+--   Dynamic Keys (8...): A repeating pair for each message.
 --     - keyMessage (for the new message, or an empty placeholder)
 --     - keyScheduledMessage (for the original message)
 --
 -- ARGV:
---   ARGV[1-32]: A list of all EQueueProperty and EMessageProperty constants.
---   ARGV[33...]: A flat list of repeating parameters for each message.
+--   ARGV[1-34]: A list of all EQueueProperty and EMessageProperty constants.
+--   ARGV[35...]: A flat list of repeating parameters for each message.
 --
--- ARGV structure per message (12 parameters):
+-- ARGV structure per message (13 parameters):
 --   1. messageId (new message ID, or '')
 --   2. message (new message body, or '')
 --   3. messagePriority
@@ -34,6 +36,7 @@
 --   10. scheduledMessageCronFired
 --   11. scheduledMessageRepeatCount
 --   12. scheduledMessageEffectiveScheduledDelay
+--   13. consumerGroupId
 --
 -- Returns:
 --   - The number of successfully processed messages.
@@ -45,6 +48,8 @@ local keyQueuePending = KEYS[2]
 local keyQueueMessages = KEYS[3]
 local keyQueuePriorityPending = KEYS[4]
 local keyQueueScheduled = KEYS[5]
+local keyQueueDeadLettered = KEYS[6]
+local keyQueueConsumerGroups = KEYS[7]
 
 -- Early exit if the queue does not exist. This check is now done only once per batch.
 local queueType = redis.call("HGET", keyQueueProperties, ARGV[1] -- EQueuePropertyQueueType
@@ -53,48 +58,50 @@ if queueType == false then
     return 0
 end
 
--- Queue Property Constants (ARGV[1-7])
+-- Queue Property Constants (ARGV[1-8])
 local EQueuePropertyQueueType = ARGV[1]
 local EQueuePropertyMessagesCount = ARGV[2]
 local EQueuePropertyPendingMessagesCount = ARGV[3]
 local EQueuePropertyScheduledMessagesCount = ARGV[4]
-local EQueuePropertyQueueTypePriorityQueue = ARGV[5]
-local EQueuePropertyQueueTypeLIFOQueue = ARGV[6]
-local EQueuePropertyQueueTypeFIFOQueue = ARGV[7]
-
--- Message Status Constants (ARGV[8-9])
-local EMessagePropertyStatusPending = ARGV[8]
-local EMessagePropertyStatusScheduled = ARGV[9]
-
--- Message Property Constants (ARGV[10-32])
-local EMessagePropertyId = ARGV[10]
-local EMessagePropertyStatus = ARGV[11]
-local EMessagePropertyMessage = ARGV[12]
-local EMessagePropertyScheduledAt = ARGV[13]
-local EMessagePropertyPublishedAt = ARGV[14]
-local EMessagePropertyProcessingStartedAt = ARGV[15]
-local EMessagePropertyDeadLetteredAt = ARGV[16]
-local EMessagePropertyAcknowledgedAt = ARGV[17]
-local EMessagePropertyUnacknowledgedAt = ARGV[18]
-local EMessagePropertyLastUnacknowledgedAt = ARGV[19]
-local EMessagePropertyLastScheduledAt = ARGV[20]
-local EMessagePropertyRequeuedAt = ARGV[21]
-local EMessagePropertyRequeueCount = ARGV[22]
-local EMessagePropertyLastRequeuedAt = ARGV[23]
-local EMessagePropertyLastRetriedAttemptAt = ARGV[24]
-local EMessagePropertyScheduledCronFired = ARGV[25]
-local EMessagePropertyAttempts = ARGV[26]
-local EMessagePropertyScheduledRepeatCount = ARGV[27]
-local EMessagePropertyExpired = ARGV[28]
-local EMessagePropertyEffectiveScheduledDelay = ARGV[29]
-local EMessagePropertyScheduledTimes = ARGV[30]
-local EMessagePropertyScheduledMessageParentId = ARGV[31]
-local EMessagePropertyRequeuedMessageParentId = ARGV[32]
+local EQueuePropertyDeadLetteredMessagesCount = ARGV[5]
+local EQueuePropertyQueueTypePriorityQueue = ARGV[6]
+local EQueuePropertyQueueTypeLIFOQueue = ARGV[7]
+local EQueuePropertyQueueTypeFIFOQueue = ARGV[8]
+
+-- Message Status Constants (ARGV[9-11])
+local EMessagePropertyStatusPending = ARGV[9]
+local EMessagePropertyStatusScheduled = ARGV[10]
+local EMessagePropertyStatusDeadLettered = ARGV[11]
+
+-- Message Property Constants (ARGV[12-34])
+local EMessagePropertyId = ARGV[12]
+local EMessagePropertyStatus = ARGV[13]
+local EMessagePropertyMessage = ARGV[14]
+local EMessagePropertyScheduledAt = ARGV[15]
+local EMessagePropertyPublishedAt = ARGV[16]
+local EMessagePropertyProcessingStartedAt = ARGV[17]
+local EMessagePropertyDeadLetteredAt = ARGV[18]
+local EMessagePropertyAcknowledgedAt = ARGV[19]
+local EMessagePropertyUnacknowledgedAt = ARGV[20]
+local EMessagePropertyLastUnacknowledgedAt = ARGV[21]
+local EMessagePropertyLastScheduledAt = ARGV[22]
+local EMessagePropertyRequeuedAt = ARGV[23]
+local EMessagePropertyRequeueCount = ARGV[24]
+local EMessagePropertyLastRequeuedAt = ARGV[25]
+local EMessagePropertyLastRetriedAttemptAt = ARGV[26]
+local EMessagePropertyScheduledCronFired = ARGV[27]
+local EMessagePropertyAttempts = ARGV[28]
+local EMessagePropertyScheduledRepeatCount = ARGV[29]
+local EMessagePropertyExpired = ARGV[30]
+local EMessagePropertyEffectiveScheduledDelay = ARGV[31]
+local EMessagePropertyScheduledTimes = ARGV[32]
+local EMessagePropertyScheduledMessageParentId = ARGV[33]
+local EMessagePropertyRequeuedMessageParentId = ARGV[34]
 
 -- Loop constants
-local INITIAL_ARGV_OFFSET = 32
-local INITIAL_KEY_OFFSET = 5
-local PARAMS_PER_MESSAGE = 12
+local INITIAL_ARGV_OFFSET = 34
+local INITIAL_KEY_OFFSET = 7
+local PARAMS_PER_MESSAGE = 14
 local KEYS_PER_MESSAGE = 2
 local keyIndex = INITIAL_KEY_OFFSET + 1
 local processed_count = 0
@@ -113,83 +120,111 @@ for argvIndex = INITIAL_ARGV_OFFSET + 1, #ARGV, PARAMS_PER_MESSAGE do
     local scheduledMessageCronFired = ARGV[argvIndex + 9]
     local scheduledMessageRepeatCount = ARGV[argvIndex + 10]
     local scheduledMessageEffectiveScheduledDelay = ARGV[argvIndex + 11]
+    local consumerGroupId = ARGV[argvIndex + 12]
+    local messageDeadLetteredAt = ARGV[argvIndex + 13]
 
     -- Extract keys for the current message
     local keyMessage = KEYS[keyIndex]
     local keyScheduledMessage = KEYS[keyIndex + 1]
     keyIndex = keyIndex + KEYS_PER_MESSAGE
 
+    local group_exists = true
+    if consumerGroupId and consumerGroupId ~= '' then
+        if redis.call("SISMEMBER", keyQueueConsumerGroups, consumerGroupId) == 0 then
+            group_exists = false
+        end
+    end
+
     -- Case 1: A simple scheduled message is due. Move it to the pending queue.
     if newMessageId == '' then
-        if queueType == EQueuePropertyQueueTypeFIFOQueue then
-            redis.call("LPUSH", keyQueuePending, scheduledMessageId)
-        elseif queueType == EQueuePropertyQueueTypeLIFOQueue then
-            redis.call("RPUSH", keyQueuePending, scheduledMessageId)
-        else -- Priority queue
-            redis.call("ZADD", keyQueuePriorityPending, newMessagePriority, scheduledMessageId)
+        -- Always remove from scheduled queue first
+        if redis.call("ZREM", keyQueueScheduled, scheduledMessageId) == 1 then
+            redis.call("HINCRBY", keyQueueProperties, EQueuePropertyScheduledMessagesCount, -1)
+
+            if group_exists then
+                if queueType == EQueuePropertyQueueTypeFIFOQueue then
+                    redis.call("LPUSH", keyQueuePending, scheduledMessageId)
+                elseif queueType == EQueuePropertyQueueTypeLIFOQueue then
+                    redis.call("RPUSH", keyQueuePending, scheduledMessageId)
+                else -- Priority queue
+                    redis.call("ZADD", keyQueuePriorityPending, newMessagePriority, scheduledMessageId)
+                end
+                redis.call("HINCRBY", keyQueueProperties, EQueuePropertyPendingMessagesCount, 1)
+
+                -- Update all relevant properties for the scheduled message
+                redis.call(
+                        "HSET", keyScheduledMessage,
+                        EMessagePropertyPublishedAt, scheduledMessagePublishedAt,
+                        EMessagePropertyStatus, EMessagePropertyStatusPending,
+                        EMessagePropertyLastScheduledAt, scheduledMessageLastScheduledAt,
+                        EMessagePropertyScheduledTimes, scheduledMessageScheduledTimes,
+                        EMessagePropertyScheduledCronFired, scheduledMessageCronFired,
+                        EMessagePropertyScheduledRepeatCount, scheduledMessageRepeatCount,
+                        EMessagePropertyEffectiveScheduledDelay, scheduledMessageEffectiveScheduledDelay
+                )
+            else
+                -- Group does not exist, dead-letter the message
+                redis.call("RPUSH", keyQueueDeadLettered, scheduledMessageId)
+                redis.call("HINCRBY", keyQueueProperties, EQueuePropertyDeadLetteredMessagesCount, 1)
+                redis.call(
+                        "HSET", keyScheduledMessage,
+                        EMessagePropertyStatus, EMessagePropertyStatusDeadLettered,
+                        EMessagePropertyDeadLetteredAt, messageDeadLetteredAt)
+            end
+            processed_count = processed_count + 1
         end
-        redis.call("ZREM", keyQueueScheduled, scheduledMessageId)
-        redis.call("HINCRBY", keyQueueProperties, EQueuePropertyPendingMessagesCount, 1)
-        redis.call("HINCRBY", keyQueueProperties, EQueuePropertyScheduledMessagesCount, -1)
-
-        -- Update all relevant properties for the scheduled message
-        redis.call(
-                "HSET", keyScheduledMessage,
-                EMessagePropertyPublishedAt, scheduledMessagePublishedAt,
-                EMessagePropertyStatus, EMessagePropertyStatusPending,
-                EMessagePropertyLastScheduledAt, scheduledMessageLastScheduledAt,
-                EMessagePropertyScheduledTimes, scheduledMessageScheduledTimes,
-                EMessagePropertyScheduledCronFired, scheduledMessageCronFired,
-                EMessagePropertyScheduledRepeatCount, scheduledMessageRepeatCount,
-                EMessagePropertyEffectiveScheduledDelay, scheduledMessageEffectiveScheduledDelay
-        )
-        processed_count = processed_count + 1
     else
-        -- Case 2: A repeating message is due. Publish a new message and reschedule the original.
-        if scheduledMessageNextScheduleTimestamp == "0" then
-            -- This is the last repetition, so we don't reschedule.
-            -- We just remove it from the scheduled set.
-            redis.call("ZREM", keyQueueScheduled, scheduledMessageId)
-        else
+        -- Case 2: A repeating message is due.
+        if group_exists then
+            -- Group exists: Publish a new message and reschedule the original.
+
             -- Reschedule the original message for its next occurrence
             redis.call("ZADD", keyQueueScheduled, scheduledMessageNextScheduleTimestamp, scheduledMessageId)
-        end
 
-        -- Update all relevant properties for the original scheduled message
-        redis.call(
-                "HSET", keyScheduledMessage,
-                EMessagePropertyLastScheduledAt, scheduledMessageLastScheduledAt,
-                EMessagePropertyScheduledTimes, scheduledMessageScheduledTimes,
-                EMessagePropertyScheduledCronFired, scheduledMessageCronFired,
-                EMessagePropertyScheduledRepeatCount, scheduledMessageRepeatCount,
-                EMessagePropertyEffectiveScheduledDelay, scheduledMessageEffectiveScheduledDelay
-        )
-
-        -- Publishing the new message
-        -- The order of keys must exactly match the 'publish-message.lua' script.
-        local pKeys = {
-            keyQueueProperties,
-            keyQueuePriorityPending,
-            keyQueuePending,
-            keyQueueScheduled,
-            keyQueueMessages,
-            keyMessage
-        }
-        -- The order of arguments must exactly match the 'publish-message.lua' script.
-        local pArgs = {
-            -- Queue properties (1-7)
-            EQueuePropertyQueueType, EQueuePropertyMessagesCount, EQueuePropertyPendingMessagesCount, EQueuePropertyScheduledMessagesCount, EQueuePropertyQueueTypePriorityQueue, EQueuePropertyQueueTypeLIFOQueue, EQueuePropertyQueueTypeFIFOQueue,
-            -- Message priority and scheduling (8-11)
-            newMessagePriority, '', EMessagePropertyStatusScheduled, EMessagePropertyStatusPending,
-            -- Message Property Keys (12-34, 23 keys)
-            EMessagePropertyId, EMessagePropertyStatus, EMessagePropertyMessage, EMessagePropertyScheduledAt, EMessagePropertyPublishedAt, EMessagePropertyProcessingStartedAt, EMessagePropertyDeadLetteredAt, EMessagePropertyAcknowledgedAt, EMessagePropertyUnacknowledgedAt, EMessagePropertyLastUnacknowledgedAt, EMessagePropertyLastScheduledAt, EMessagePropertyRequeuedAt, EMessagePropertyRequeueCount, EMessagePropertyLastRequeuedAt, EMessagePropertyLastRetriedAttemptAt, EMessagePropertyScheduledCronFired, EMessagePropertyAttempts, EMessagePropertyScheduledRepeatCount, EMessagePropertyExpired, EMessagePropertyEffectiveScheduledDelay, EMessagePropertyScheduledTimes, EMessagePropertyScheduledMessageParentId, EMessagePropertyRequeuedMessageParentId,
-            -- Message Property Values (35-57, 23 values)
-            newMessageId, EMessagePropertyStatusPending, newMessage, '', newMessagePublishedAt, '', '', '', '', '', '', '', '0', '', '', '0', '0', '0', '0', '0', '0', scheduledMessageId, ''
-        }
-        -- Publish the new message by calling the shared publish_message function
-        local result = publish_message(pKeys, pArgs)
-        if result ~= 'OK' then
-            return 'PUBLISH_ERROR:' .. newMessageId .. ':' .. result
+            -- Update all relevant properties for the original scheduled message
+            redis.call(
+                    "HSET", keyScheduledMessage,
+                    EMessagePropertyLastScheduledAt, scheduledMessageLastScheduledAt,
+                    EMessagePropertyScheduledTimes, scheduledMessageScheduledTimes,
+                    EMessagePropertyScheduledCronFired, scheduledMessageCronFired,
+                    EMessagePropertyScheduledRepeatCount, scheduledMessageRepeatCount,
+                    EMessagePropertyEffectiveScheduledDelay, scheduledMessageEffectiveScheduledDelay
+            )
+
+            -- Publishing the new message
+            local pKeys = {
+                keyQueueProperties,
+                keyQueuePriorityPending,
+                keyQueuePending,
+                keyQueueScheduled,
+                keyQueueMessages,
+                keyQueueConsumerGroups,
+                keyMessage
+            }
+            local pArgs = {
+                EQueuePropertyQueueType, EQueuePropertyMessagesCount, EQueuePropertyPendingMessagesCount, EQueuePropertyScheduledMessagesCount, EQueuePropertyQueueTypePriorityQueue, EQueuePropertyQueueTypeLIFOQueue, EQueuePropertyQueueTypeFIFOQueue,
+                newMessagePriority, '', EMessagePropertyStatusScheduled, EMessagePropertyStatusPending,
+                EMessagePropertyId, EMessagePropertyStatus, EMessagePropertyMessage, EMessagePropertyScheduledAt, EMessagePropertyPublishedAt, EMessagePropertyProcessingStartedAt, EMessagePropertyDeadLetteredAt, EMessagePropertyAcknowledgedAt, EMessagePropertyUnacknowledgedAt, EMessagePropertyLastUnacknowledgedAt, EMessagePropertyLastScheduledAt, EMessagePropertyRequeuedAt, EMessagePropertyRequeueCount, EMessagePropertyLastRequeuedAt, EMessagePropertyLastRetriedAttemptAt, EMessagePropertyScheduledCronFired, EMessagePropertyAttempts, EMessagePropertyScheduledRepeatCount, EMessagePropertyExpired, EMessagePropertyEffectiveScheduledDelay, EMessagePropertyScheduledTimes, EMessagePropertyScheduledMessageParentId, EMessagePropertyRequeuedMessageParentId,
+                newMessageId, EMessagePropertyStatusPending, newMessage, '', newMessagePublishedAt, '', '', '', '', '', '', '', '0', '', '', '0', '0', '0', '0', '0', '0', scheduledMessageId, '',
+                consumerGroupId
+            }
+            local result = publish_message(pKeys, pArgs)
+            if result ~= 'OK' then
+                return 'PUBLISH_ERROR:' .. newMessageId .. ':' .. result
+            end
+        else
+            -- Group does not exist. Dead-letter the original repeating message to stop its cycle.
+            -- The new message for this firing is simply discarded.
+            if redis.call("ZREM", keyQueueScheduled, scheduledMessageId) == 1 then
+                redis.call("RPUSH", keyQueueDeadLettered, scheduledMessageId)
+                redis.call(
+                        "HSET", keyScheduledMessage,
+                        EMessagePropertyStatus, EMessagePropertyStatusDeadLettered,
+                        EMessagePropertyDeadLetteredAt, messageDeadLetteredAt
+                )
+                redis.call("HINCRBY", keyQueueProperties, EQueuePropertyScheduledMessagesCount, -1)
+                redis.call("HINCRBY", keyQueueProperties, EQueuePropertyDeadLetteredMessagesCount, 1)
+            end
         end
         processed_count = processed_count + 1
     end

package/dist/cjs/src/common/redis-client/scripts/lua/requeue-delayed.lua

@@ -1,17 +1,20 @@
--- Description:
 -- Re-queues messages from the delayed sorted set to the pending queue.
 -- This script is designed for batch processing to improve performance. It moves messages
 -- that are due for a retry back into the active processing queue.
 -- It atomically removes messages from the delayed queue to prevent race conditions
 -- and updates message status and the 'lastRetriedAttemptAt' timestamp.
 -- It supports FIFO, LIFO, and Priority queues.
+-- For PUB/SUB queues, if a message's target consumer group has been deleted,
+-- the message is moved to the dead-letter queue instead of being re-queued.
 -- Queue counters are updated once per batch for efficiency.
 --
 -- KEYS:
---   Static Keys (1-2):
+--   Static Keys (1-4):
 --     KEYS[1]: keyQueueProperties (HMAP)
 --     KEYS[2]: keyQueueDelayed (ZSET)
---   Dynamic Keys (3...):
+--     KEYS[3]: keyQueueDeadLettered (LIST)
+--     KEYS[4]: keyQueueConsumerGroups (SET)
+--   Dynamic Keys (5...):
 --     A flat list of repeating keys for each message.
 --
 --   KEYS structure per message (3 keys):
@@ -20,33 +23,39 @@
 --     3. keyQueuePriorityPending (for Priority)
 --
 -- ARGV:
---   Static ARGV (1-9):
---     ARGV[1-8]: A list of all EQueueProperty and EMessageProperty constants.
---     ARGV[9]: Current timestamp.
---   Dynamic ARGV (10...):
+--   Static ARGV (1-12):
+--     ARGV[1-11]: A list of all EQueueProperty and EMessageProperty constants.
+--     ARGV[12]: Current timestamp.
+--   Dynamic ARGV (13...):
 --     A flat list of repeating parameters for each message.
 --
--- ARGV structure per message (2 parameters):
+-- ARGV structure per message (3 parameters):
 --   1. messageId
 --   2. messagePriority
+--   3. consumerGroupId
 --
 -- Returns:
---   - The number of messages successfully processed and re-queued.
+--   - The number of messages successfully processed (re-queued or dead-lettered).
 
 -- Static Keys
 local keyQueueProperties = KEYS[1]
 local keyQueueDelayed = KEYS[2]
+local keyQueueDeadLettered = KEYS[3]
+local keyQueueConsumerGroups = KEYS[4]
 
 -- Static ARGV
 local EQueuePropertyQueueType = ARGV[1]
 local EQueuePropertyDelayedMessagesCount = ARGV[2]
 local EQueuePropertyPendingMessagesCount = ARGV[3]
-local EMessagePropertyStatus = ARGV[4]
-local EMessagePropertyStatusPending = ARGV[5]
-local EMessagePropertyLastRetriedAttemptAt = ARGV[6]
-local EQueuePropertyQueueTypeLIFOQueue = ARGV[7]
-local EQueuePropertyQueueTypeFIFOQueue = ARGV[8]
-local timestamp = ARGV[9]
+local EQueuePropertyDeadLetteredMessagesCount = ARGV[4]
+local EMessagePropertyStatus = ARGV[5]
+local EMessagePropertyStatusPending = ARGV[6]
+local EMessagePropertyStatusDeadLettered = ARGV[7]
+local EMessagePropertyDeadLetteredAt = ARGV[8]
+local EMessagePropertyLastRetriedAttemptAt = ARGV[9]
+local EQueuePropertyQueueTypeLIFOQueue = ARGV[10]
+local EQueuePropertyQueueTypeFIFOQueue = ARGV[11]
+local timestamp = ARGV[12]
 
 -- Early exit if the queue does not exist
 local queueType = redis.call("HGET", keyQueueProperties, EQueuePropertyQueueType)
@@ -55,19 +64,21 @@ if queueType == false then
 end
 
 -- Constants for parameter counts
-local INITIAL_KEY_OFFSET = 2
-local INITIAL_ARGV_OFFSET = 9
-local PARAMS_PER_MESSAGE = 2
+local INITIAL_KEY_OFFSET = 4
+local INITIAL_ARGV_OFFSET = 12
+local PARAMS_PER_MESSAGE = 3
 local KEYS_PER_MESSAGE = 3
 
 local keyIndex = INITIAL_KEY_OFFSET + 1
-local processed_count = 0
+local requeued_count = 0
+local dead_lettered_count = 0
 
 -- Process messages in batches
 for argvIndex = INITIAL_ARGV_OFFSET + 1, #ARGV, PARAMS_PER_MESSAGE do
     -- Extract message parameters
     local messageId = ARGV[argvIndex]
     local messagePriority = ARGV[argvIndex + 1]
+    local consumerGroupId = ARGV[argvIndex + 2]
 
     -- Get the message keys for this iteration from KEYS
     local keyMessage = KEYS[keyIndex]
@@ -79,30 +90,57 @@ for argvIndex = INITIAL_ARGV_OFFSET + 1, #ARGV, PARAMS_PER_MESSAGE do
     -- If ZREM returns 0, the message was not found (e.g., already processed),
     -- so we skip it to prevent corrupting queue counters.
     if redis.call("ZREM", keyQueueDelayed, messageId) == 1 then
-        -- Move the message to the pending queue.
-        if queueType == EQueuePropertyQueueTypeFIFOQueue then
-            redis.call("LPUSH", keyQueuePending, messageId)
-        elseif queueType == EQueuePropertyQueueTypeLIFOQueue then
-            redis.call("RPUSH", keyQueuePending, messageId)
-        else -- Priority queue
-            redis.call("ZADD", keyQueuePriorityPending, messagePriority, messageId)
+        local group_exists = true
+        if consumerGroupId and consumerGroupId ~= '' then
+            if redis.call("SISMEMBER", keyQueueConsumerGroups, consumerGroupId) == 0 then
+                group_exists = false
+            end
         end
 
-        -- Update message properties
-        redis.call("HSET", keyMessage,
-                EMessagePropertyStatus, EMessagePropertyStatusPending,
-                EMessagePropertyLastRetriedAttemptAt, timestamp
-        )
+        if group_exists then
+            -- Move the message to the pending queue.
+            if queueType == EQueuePropertyQueueTypeFIFOQueue then
+                redis.call("LPUSH", keyQueuePending, messageId)
+            elseif queueType == EQueuePropertyQueueTypeLIFOQueue then
+                redis.call("RPUSH", keyQueuePending, messageId)
+            else -- Priority queue
+                redis.call("ZADD", keyQueuePriorityPending, messagePriority, messageId)
+            end
 
-        processed_count = processed_count + 1
+            -- Update message properties
+            redis.call("HSET", keyMessage,
+                    EMessagePropertyStatus, EMessagePropertyStatusPending,
+                    EMessagePropertyLastRetriedAttemptAt, timestamp
+            )
+
+            requeued_count = requeued_count + 1
+        else
+            -- The consumer group does not exist. Dead-letter the message.
+            redis.call("RPUSH", keyQueueDeadLettered, messageId)
+
+            -- Update message properties
+            redis.call("HSET", keyMessage,
+                    EMessagePropertyStatus, EMessagePropertyStatusDeadLettered,
+                    EMessagePropertyDeadLetteredAt, timestamp
+            )
+
+            dead_lettered_count = dead_lettered_count + 1
+        end
     end
 end
 
 -- After processing the whole batch, update queue counters once.
--- This is much more efficient than updating them inside the loop.
-if processed_count > 0 then
-    redis.call("HINCRBY", keyQueueProperties, EQueuePropertyDelayedMessagesCount, -processed_count)
-    redis.call("HINCRBY", keyQueueProperties, EQueuePropertyPendingMessagesCount, processed_count)
+if requeued_count > 0 then
+    redis.call("HINCRBY", keyQueueProperties, EQueuePropertyPendingMessagesCount, requeued_count)
+end
+
+if dead_lettered_count > 0 then
+    redis.call("HINCRBY", keyQueueProperties, EQueuePropertyDeadLetteredMessagesCount, dead_lettered_count)
+end
+
+local total_processed = requeued_count + dead_lettered_count
+if total_processed > 0 then
+    redis.call("HINCRBY", keyQueueProperties, EQueuePropertyDelayedMessagesCount, -total_processed)
 end
 
-return processed_count
+return total_processed