sneakers_max_retry_handler 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 11c75e850f1367f8a75940dba6f75c3652c92f2d4cbfde8ebe89a60dc671660a
+  data.tar.gz: 7642b2c40070abc4207de8fbbc8831d654cef6a7d484762f65ee383bf9de433d
+SHA512:
+  metadata.gz: '080715a56d2c622df989e2f292d4c462927a7fe749624c159889b09138b9f077326512ccb0aed36b42a124bd895a4b69008ad11a999c80bd6d5303cb1f85841d'
+  data.tar.gz: bda03c7af5ff41b9beefd68d3e9b45bdb04340b1c20ed81e1537079c1f12cd163bfba3f5d9af88c80481d7d1038826313cc9b0dab14ad8ece1751bfcd24f0d2d

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in sneakers_max_retry_handler.gemspec
+gemspec
+
+gem "irb"
+gem "rake", "~> 13.0"

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 KlimSem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,35 @@
+# Sneakers-Max-Retry-Handler
+
+A modified max retry handler for RabbitMQ and [Sneakers](https://github.com/ruby-amqp/kicks/)
+
+A small modification of Sneaker's built-in [Maxretry class](https://github.com/ruby-amqp/kicks/blob/main/lib/sneakers/handlers/maxretry.rb)
+the replacement class is called ```SneakersMaxRetryHandler::Maxretry```
+has the exact same logic, but you can pass arguments for handler created queues
+
+
+# Installation
+
+Include it in your Gemfile.
+
+```ruby
+gem 'sneakers_max_retry_handler'
+```
+
+Next install it with Bundler.
+
+```bash
+$ bundle install
+```
+
+
+# Use:
+
+initialize your worker with the Maxretry handler:
+
+```ruby
+class MyWorker
+   from_queue 'audit_service', {
+      handler: SneakersMaxRetryHandler::Maxretry,
+   }
+end
+```

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "sneakers_max_retry_handler"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/sneakers_max_retry_handler/maxretry.rb

@@ -0,0 +1,216 @@
+require 'base64'
+require 'json'
+
+module SneakersMaxRetryHandler
+  #
+  # Maxretry uses dead letter policies on Rabbitmq to requeue and retry
+  # messages after failure (rejections and errors). When the maximum
+  # number of retries is reached it will put the message on an error queue.
+  # This handler will only retry at the queue level. To accomplish that, the
+  # setup is a bit complex.
+  #
+  # Input:
+  #   worker_exchange (eXchange)
+  #   worker_queue (Queue)
+  # We create:
+  #   worker_queue-retry - (X) where we setup the worker queue to dead-letter.
+  #   worker_queue-retry - (Q) queue bound to ^ exchange, dead-letters to
+  #                        worker_queue-retry-requeue.
+  #   worker_queue-error - (X) where to send max-retry failures
+  #   worker_queue-error - (Q) bound to worker_queue-error.
+  #   worker_queue-retry-requeue - (X) exchange to bind worker_queue to for
+  #                                requeuing directly to the worker_queue.
+  #
+  # This requires that you setup arguments to the worker queue to line up the
+  # dead letter queue. See the example for more information.
+  #
+  # Many of these can be override with options:
+  # - retry_exchange - sets retry exchange & queue
+  # - retry_error_exchange - sets error exchange and queue
+  # - retry_requeue_exchange - sets the exchange created to re-queue things
+  #   back to the worker queue.
+  #
+  class Maxretry
+
+    def initialize(channel, queue, opts)
+      @worker_queue_name = queue.name
+      Sneakers.logger.debug do
+        "#{log_prefix} creating handler, opts=#{opts}"
+      end
+
+      @channel = channel
+      @opts = opts
+
+      # Construct names, defaulting where suitable
+      retry_name = @opts[:retry_exchange] || "#{@worker_queue_name}-retry"
+      error_name = @opts[:retry_error_exchange] || "#{@worker_queue_name}-error"
+      requeue_name = @opts[:retry_requeue_exchange] || "#{@worker_queue_name}-retry-requeue"
+      retry_routing_key = @opts[:retry_routing_key] || "#"
+
+      # Create the exchanges
+      @retry_exchange, @error_exchange, @requeue_exchange = [retry_name, error_name, requeue_name].map do |name|
+        Sneakers.logger.debug { "#{log_prefix} creating exchange=#{name}" }
+        @channel.exchange(name,
+                          :type => 'topic',
+                          :durable => exchange_durable?)
+      end
+
+      # Create the queues and bindings
+      Sneakers.logger.debug do
+        "#{log_prefix} creating queue=#{retry_name} x-dead-letter-exchange=#{requeue_name}"
+      end
+      @retry_queue = @channel.queue(retry_name,
+                                    :durable => queue_durable?,
+                                    :arguments => {
+                                      :'x-dead-letter-exchange' => requeue_name,
+                                      :'x-message-ttl' => @opts[:retry_timeout] || 60000
+                                    })
+      @retry_queue.bind(@retry_exchange, :routing_key => '#')
+
+      Sneakers.logger.debug do
+        "#{log_prefix} creating queue=#{error_name}"
+      end
+      @error_queue = @channel.queue(error_name,
+                                    :durable => queue_durable?)
+      @error_queue.bind(@error_exchange, :routing_key => '#')
+
+      # Finally, bind the worker queue to our requeue exchange
+      queue.bind(@requeue_exchange, :routing_key => retry_routing_key)
+
+      @max_retries = @opts[:retry_max_times] || 5
+    end
+
+    def self.configure_queue(name, opts)
+      retry_name = opts.fetch(:retry_exchange, "#{name}-retry")
+      opt_args = opts[:queue_options][:arguments] ? opts[:queue_options][:arguments].inject({}){|memo,(k,v)| memo[k.to_sym] = v; memo} : {}
+      opts[:queue_options][:arguments] = { :'x-dead-letter-exchange' => retry_name }.merge(opt_args)
+      opts[:queue_options]
+    end
+
+    def acknowledge(hdr, props, msg)
+      @channel.acknowledge(hdr.delivery_tag, false)
+    end
+
+    def reject(hdr, props, msg, requeue = false)
+      if requeue
+        # This was explicitly rejected specifying it be requeued so we do not
+        # want it to pass through our retry logic.
+        @channel.reject(hdr.delivery_tag, requeue)
+      else
+        handle_retry(hdr, props, msg, :reject)
+      end
+    end
+
+
+    def error(hdr, props, msg, err)
+      handle_retry(hdr, props, msg, err)
+    end
+
+    def noop(hdr, props, msg)
+
+    end
+
+    # Helper logic for retry handling. This will reject the message if there
+    # are remaining retries left on it, otherwise it will publish it to the
+    # error exchange along with the reason.
+    # @param hdr [Bunny::DeliveryInfo]
+    # @param props [Bunny::MessageProperties]
+    # @param msg [String] The message
+    # @param reason [String, Symbol, Exception] Reason for the retry, included
+    #   in the JSON we put on the error exchange.
+    def handle_retry(hdr, props, msg, reason)
+      # +1 for the current attempt
+      num_attempts = failure_count(props[:headers]) + 1
+      if num_attempts <= @max_retries
+        # We call reject which will route the message to the
+        # x-dead-letter-exchange (ie. retry exchange) on the queue
+        Sneakers.logger.info do
+          "#{log_prefix} msg=retrying, count=#{num_attempts}, headers=#{props[:headers]}"
+        end
+        @channel.reject(hdr.delivery_tag, false)
+        # TODO: metrics
+      else
+        # Retried more than the max times
+        # Publish the original message with the routing_key to the error exchange
+        Sneakers.logger.info do
+          "#{log_prefix} msg=failing, retry_count=#{num_attempts}, reason=#{reason}"
+        end
+        data = {
+          error: reason.to_s,
+          num_attempts: num_attempts,
+          failed_at: Time.now.iso8601,
+          properties: props.to_hash
+        }.tap do |hash|
+          if reason.is_a?(Exception)
+            hash[:error_class] = reason.class.to_s
+            hash[:error_message] = "#{reason}"
+            if reason.backtrace
+              hash[:backtrace] = reason.backtrace.take(10)
+            end
+          end
+        end
+
+        # Preserve retry log in a list
+        if retry_info = props[:headers]['retry_info']
+          old_retry0 = JSON.parse(retry_info) rescue {error: "Failed to parse retry info"}
+          old_retry  = Array(old_retry0)
+          # Prevent old retry from nesting
+          data[:properties][:headers].delete('retry_info')
+          data = old_retry.unshift(data)
+        end
+
+        @error_exchange.publish(msg, {
+          routing_key: hdr.routing_key,
+          headers: {
+            retry_info: data.to_json
+          }
+        })
+        @channel.acknowledge(hdr.delivery_tag, false)
+        # TODO: metrics
+      end
+    end
+    private :handle_retry
+
+    # Uses the x-death header to determine the number of failures this job has
+    # seen in the past. This does not count the current failure. So for
+    # instance, the first time the job fails, this will return 0, the second
+    # time, 1, etc.
+    # @param headers [Hash] Hash of headers that Rabbit delivers as part of
+    #   the message
+    # @return [Integer] Count of number of failures.
+    def failure_count(headers)
+      if headers.nil? || headers['x-death'].nil?
+        0
+      else
+        x_death_array = headers['x-death'].select do |x_death|
+          x_death['queue'] == @worker_queue_name
+        end
+        if x_death_array.count > 0 && x_death_array.first['count']
+          # Newer versions of RabbitMQ return headers with a count key
+          x_death_array.inject(0) {|sum, x_death| sum + x_death['count']}
+        else
+          # Older versions return a separate x-death header for each failure
+          x_death_array.count
+        end
+      end
+    end
+    private :failure_count
+
+    # Prefix all of our log messages so they are easier to find. We don't have
+    # the worker, so the next best thing is the queue name.
+    def log_prefix
+      "Maxretry handler [queue=#{@worker_queue_name}]"
+    end
+    private :log_prefix
+
+    private
+
+    def queue_durable?
+      @opts.fetch(:queue_options, {}).fetch(:durable, false)
+    end
+
+    def exchange_durable?
+      queue_durable?
+    end
+  end
+end

data/lib/sneakers_max_retry_handler/version.rb

@@ -0,0 +1,3 @@
+module SneakersMaxRetryHandler
+  VERSION = "0.1.0"
+end

data/lib/sneakers_max_retry_handler.rb

@@ -0,0 +1 @@
+require 'sneakers_max_retry_handler/maxretry.rb'

data/sneakers_max_retry_handler.gemspec

@@ -0,0 +1,22 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'sneakers_max_retry_handler/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "sneakers_max_retry_handler"
+  spec.version       = SneakersMaxRetryHandler::VERSION
+  spec.authors       = ["KlimSem"]
+  spec.email         = ["klimsemikin@gmail.com"]
+  spec.licenses      = ['MIT']
+
+  spec.summary       = %q{Adds MaxRetry Handler to use with Kicks}
+  spec.description   = %q{Adds MaxRetry handler which supports additional settings}
+  spec.homepage      = "https://github.com/KlimSemikin/sneakers_max_retry_handler"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "kicks", "~> 3.2.0"
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "pry-byebug", "~> 3.5"
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: sneakers_max_retry_handler
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- KlimSem
+bindir: bin
+cert_chain: []
+date: 2025-08-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: kicks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+description: Adds MaxRetry handler which supports additional settings
+email:
+- klimsemikin@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.md
+- bin/console
+- bin/setup
+- lib/sneakers_max_retry_handler.rb
+- lib/sneakers_max_retry_handler/maxretry.rb
+- lib/sneakers_max_retry_handler/version.rb
+- sneakers_max_retry_handler.gemspec
+homepage: https://github.com/KlimSemikin/sneakers_max_retry_handler
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.6
+specification_version: 4
+summary: Adds MaxRetry Handler to use with Kicks
+test_files: []