philiprehberger-retry_queue 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 289a1d7d4fe45b2fe49121a2f132c18a68eddb7f9ebaae0a034fc0868bfd316c
-  data.tar.gz: 0dadd128377a6ffed0cd0ea1eecb68734aeac75eaca3ef01ba6e8d6403ab71b9
+  metadata.gz: 22b3442db8a011863de798c26bd3d255b65cc355655bc98c7b32f5dc0d233a01
+  data.tar.gz: 73279504fb90ae3768d615e2e3e1db7df57151946320490856ccb62a98e7a2d3
 SHA512:
-  metadata.gz: ac758a0803e01ddd0e3475bbde13a59b5925d8e71ffecec5465ed323211d8d0f2f26d4ed08ace8c143526da40d8b2e9616d2bf57b25b6a8120285792dcdadc18
-  data.tar.gz: a7e1f56022346513d9b1db113903326ff5ba8c57b37820a22f2574d72fb608646b29b7de7d7debfe19a590b616e7423ba57b4191512d9279bdd8933dcfaf2208
+  metadata.gz: 106135b96e386b6fbda72eb74adba46d85d8e11eb233736a91b8dc2fec4304baa7ce6497f05553c7a9c649ca7a4641131fd1e2d48a072e013a9f2f6c5bbdbf4e
+  data.tar.gz: e478bba48e5c678502099b50db3f61714d3e5873bd5f3b244a0e47ff2a781570a703805449983df313bd4c6f3a3833790fe4e54203b579de7ab3279abbabe500

data/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-29
+
+### Added
+- Selective retry via `retry_on:` parameter to only retry specific exception classes
+- Retry hooks via `on_retry:` parameter with callbacks fired before each retry attempt
+- DLQ reprocessing via `Result#reprocess_failed` to iterate over failed items with their last error
+
 ## [0.1.2] - 2026-03-24
 
 ### Fixed

data/README.md

@@ -2,7 +2,12 @@
 
 [![Tests](https://github.com/philiprehberger/rb-retry-queue/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-retry-queue/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-retry_queue.svg)](https://rubygems.org/gems/philiprehberger-retry_queue)
+[![GitHub release](https://img.shields.io/github/v/release/philiprehberger/rb-retry-queue)](https://github.com/philiprehberger/rb-retry-queue/releases)
+[![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-retry-queue)](https://github.com/philiprehberger/rb-retry-queue/commits/main)
 [![License](https://img.shields.io/github/license/philiprehberger/rb-retry-queue)](LICENSE)
+[![Bug Reports](https://img.shields.io/github/issues/philiprehberger/rb-retry-queue/bug)](https://github.com/philiprehberger/rb-retry-queue/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+[![Feature Requests](https://img.shields.io/github/issues/philiprehberger/rb-retry-queue/enhancement)](https://github.com/philiprehberger/rb-retry-queue/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
+[![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
 
 Batch processor with per-item retry, backoff, and dead letter collection
 
@@ -45,16 +50,41 @@ result = Philiprehberger::RetryQueue.process(items, max_retries: 5, backoff: ->(
 end
 ```
 
-### Dead Letter Inspection
+### Selective Retry
+
+```ruby
+result = Philiprehberger::RetryQueue.process(items, max_retries: 3, retry_on: [Net::OpenTimeout, Timeout::Error]) do |item|
+  api_call(item)
+end
+
+# Only Net::OpenTimeout and Timeout::Error trigger retries
+# All other errors send the item straight to failed
+```
+
+### Retry Hooks
+
+```ruby
+logger_hook = ->(item, error, attempt) { puts "Retrying #{item}: #{error.message} (attempt #{attempt})" }
+metrics_hook = ->(item, _error, _attempt) { increment_counter("retry.#{item}") }
+
+result = Philiprehberger::RetryQueue.process(items, max_retries: 3, on_retry: [logger_hook, metrics_hook]) do |item|
+  process_item(item)
+end
+```
+
+### DLQ Reprocessing
 
 ```ruby
 result = Philiprehberger::RetryQueue.process(jobs, max_retries: 2) do |job|
   job.execute!
 end
 
-result.failed.each do |entry|
-  puts "Item: #{entry[:item]}, Error: #{entry[:error].message}, Attempts: #{entry[:attempts]}"
+reprocessed = result.reprocess_failed do |item, error|
+  fallback_handler(item, error)
 end
+
+puts reprocessed.succeeded.size  # => items recovered during reprocessing
+puts reprocessed.failed.size     # => items that failed reprocessing too
 ```
 
 ### Statistics
@@ -72,10 +102,11 @@ stats = result.stats
 
 | Method | Description |
 |--------|-------------|
-| `.process(items, max_retries:, concurrency:, backoff:) { \|item\| }` | Process items with retry logic |
+| `.process(items, max_retries:, concurrency:, backoff:, retry_on:, on_retry:) { \|item\| }` | Process items with retry logic |
 | `Result#succeeded` | Array of successfully processed items |
 | `Result#failed` | Array of hashes with `:item`, `:error`, `:attempts` |
 | `Result#stats` | Hash with `:total`, `:succeeded`, `:failed`, `:success_rate`, `:elapsed` |
+| `Result#reprocess_failed { \|item, error\| }` | Reprocess failed items, returns a new Result |
 
 ## Development
 
@@ -85,6 +116,13 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+## Support
+
+If you find this package useful, consider giving it a star on GitHub — it helps motivate continued maintenance and development.
+
+[![LinkedIn](https://img.shields.io/badge/Philip%20Rehberger-LinkedIn-0A66C2?logo=linkedin)](https://www.linkedin.com/in/philiprehberger)
+[![More packages](https://img.shields.io/badge/more-open%20source%20packages-blue)](https://philiprehberger.com/open-source-packages)
+
 ## License
 
-MIT
+[MIT](LICENSE)

data/lib/philiprehberger/retry_queue/processor.rb

@@ -10,12 +10,16 @@ module Philiprehberger
       # @param max_retries [Integer] maximum retry attempts per item
       # @param concurrency [Integer] number of concurrent workers (reserved for future use)
       # @param backoff [Proc, nil] proc receiving attempt number, returns sleep duration
-      def initialize(max_retries: 3, concurrency: 1, backoff: nil)
+      # @param retry_on [Array<Class>, nil] exception classes to retry on; nil means retry all
+      # @param on_retry [Array<Proc>, Proc, nil] callbacks fired before each retry attempt
+      def initialize(max_retries: 3, concurrency: 1, backoff: nil, retry_on: nil, on_retry: nil)
         raise Error, 'max_retries must be non-negative' unless max_retries.is_a?(Integer) && max_retries >= 0
 
         @max_retries = max_retries
         @concurrency = concurrency
         @backoff = backoff || DEFAULT_BACKOFF
+        @retry_on = retry_on
+        @on_retry_hooks = Array(on_retry)
       end
 
       # Process a collection of items with retry logic.
@@ -48,16 +52,28 @@ module Philiprehberger
           succeeded << item
           return
         rescue StandardError => e
-          if attempts > @max_retries
+          if !retryable?(e) || attempts > @max_retries
             failed << { item: item, error: e, attempts: attempts }
             return
           end
 
+          fire_on_retry_hooks(item, e, attempts)
+
           sleep_duration = @backoff.call(attempts - 1)
           sleep(sleep_duration) if sleep_duration.positive?
         end
       end
 
+      def retryable?(error)
+        return true if @retry_on.nil?
+
+        @retry_on.any? { |klass| error.is_a?(klass) }
+      end
+
+      def fire_on_retry_hooks(item, error, attempt)
+        @on_retry_hooks.each { |hook| hook.call(item, error, attempt) }
+      end
+
       def now
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end

data/lib/philiprehberger/retry_queue/result.rb

@@ -32,6 +32,29 @@ module Philiprehberger
           elapsed: @elapsed
         }
       end
+
+      # Reprocess failed items by yielding each item and its last error to the block.
+      # Returns a new Result with the reprocessing outcomes.
+      #
+      # @yield [item, error] block that reprocesses a failed item
+      # @return [Result] new result with reprocessing outcomes
+      def reprocess_failed(&block)
+        raise Error, 'a reprocessing block is required' unless block
+
+        reprocess_succeeded = []
+        reprocess_failed = []
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        @failed.each do |entry|
+          block.call(entry[:item], entry[:error])
+          reprocess_succeeded << entry[:item]
+        rescue StandardError => e
+          reprocess_failed << { item: entry[:item], error: e, attempts: 1 }
+        end
+
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        Result.new(succeeded: reprocess_succeeded, failed: reprocess_failed, elapsed: elapsed)
+      end
     end
   end
 end

data/lib/philiprehberger/retry_queue/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module RetryQueue
-    VERSION = '0.1.2'
+    VERSION = '0.2.0'
   end
 end

data/lib/philiprehberger/retry_queue.rb

@@ -14,10 +14,18 @@ module Philiprehberger
     # @param max_retries [Integer] maximum retry attempts per item
     # @param concurrency [Integer] number of concurrent workers
     # @param backoff [Proc, nil] custom backoff strategy
+    # @param retry_on [Array<Class>, nil] exception classes to retry on; others go straight to failed
+    # @param on_retry [Array<Proc>, nil] callbacks fired before each retry attempt
     # @yield [item] block that processes a single item
     # @return [Result] processing result
-    def self.process(items, max_retries: 3, concurrency: 1, backoff: nil, &block)
-      processor = Processor.new(max_retries: max_retries, concurrency: concurrency, backoff: backoff)
+    def self.process(items, max_retries: 3, concurrency: 1, backoff: nil, retry_on: nil, on_retry: nil, &block)
+      processor = Processor.new(
+        max_retries: max_retries,
+        concurrency: concurrency,
+        backoff: backoff,
+        retry_on: retry_on,
+        on_retry: on_retry
+      )
       processor.call(items, &block)
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-retry_queue
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-25 00:00:00.000000000 Z
+date: 2026-03-30 00:00:00.000000000 Z
 dependencies: []
 description: Processes collections of items with configurable per-item retry logic,
   exponential backoff, and dead letter collection for failed items. Returns detailed