philiprehberger-retry_queue 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22b3442db8a011863de798c26bd3d255b65cc355655bc98c7b32f5dc0d233a01
-  data.tar.gz: 73279504fb90ae3768d615e2e3e1db7df57151946320490856ccb62a98e7a2d3
+  metadata.gz: a5c95df7fb98070ed959408d5fce1be2d1b920a800221d831f24214ffe9425d1
+  data.tar.gz: d681958fb8eddf3710283315eb52ff81cc13bec03d67c0e72d1199ec5025ec9e
 SHA512:
-  metadata.gz: 106135b96e386b6fbda72eb74adba46d85d8e11eb233736a91b8dc2fec4304baa7ce6497f05553c7a9c649ca7a4641131fd1e2d48a072e013a9f2f6c5bbdbf4e
-  data.tar.gz: e478bba48e5c678502099b50db3f61714d3e5873bd5f3b244a0e47ff2a781570a703805449983df313bd4c6f3a3833790fe4e54203b579de7ab3279abbabe500
+  metadata.gz: 4b91743778fba30ed468fe23da3157c4df3086a81c5aa1784f5d304a967967ad271e7dd9646a54d75a54379b5123f8589614249c346fa760ccc05111f7e6bdcc
+  data.tar.gz: e63ef43720e3915d2942c06fd34e33ca79aabe147b3fc678db7812759c0501e6b660e80e4ae37afcc59ab031f8250e04371766888cd873e2edd7f1dc1f9ae0bf

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-17
+
+### Added
+- `on_failure:` callback for `process` and `Processor`, invoked with `(item, error)` when an item exhausts retries; hook exceptions are swallowed
+
+## [0.2.1] - 2026-03-31
+
+### Changed
+- Standardize README badges, support section, and license format
+
 ## [0.2.0] - 2026-03-29
 
 ### Added

data/README.md

@@ -2,12 +2,7 @@
 
 [![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
 
@@ -72,6 +67,20 @@ result = Philiprehberger::RetryQueue.process(items, max_retries: 3, on_retry: [l
 end
 ```
 
+### Dead-letter Notifications
+
+```ruby
+on_failure = ->(item, error) { Rails.logger.error("Dead-lettered #{item}: #{error.message}") }
+
+result = Philiprehberger::RetryQueue.process(items, max_retries: 3, on_failure: on_failure) do |item|
+  process_item(item)
+end
+```
+
+The hook fires once per item that exhausts its retries, just as the item is recorded in
+`Result#failed`. Exceptions raised inside the hook are swallowed so a faulty callback cannot
+break the queue.
+
 ### DLQ Reprocessing
 
 ```ruby
@@ -102,7 +111,8 @@ stats = result.stats
 
 | Method | Description |
 |--------|-------------|
-| `.process(items, max_retries:, concurrency:, backoff:, retry_on:, on_retry:) { \|item\| }` | Process items with retry logic |
+| `.process(items, max_retries:, concurrency:, backoff:, retry_on:, on_retry:, on_failure:) { \|item\| }` | Process items with retry logic |
+| `on_failure:` | Callable `(item, error)` invoked once per item that exhausts retries; hook errors are swallowed |
 | `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` |
@@ -118,10 +128,21 @@ bundle exec rubocop
 
 ## Support
 
-If you find this package useful, consider giving it a star on GitHub — it helps motivate continued maintenance and development.
+If you find this project useful:
+
+⭐ [Star the repo](https://github.com/philiprehberger/rb-retry-queue)
+
+🐛 [Report issues](https://github.com/philiprehberger/rb-retry-queue/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+
+💡 [Suggest features](https://github.com/philiprehberger/rb-retry-queue/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
+
+❤️ [Sponsor development](https://github.com/sponsors/philiprehberger)
+
+🌐 [All Open Source Projects](https://philiprehberger.com/open-source-packages)
+
+💻 [GitHub Profile](https://github.com/philiprehberger)
 
-[![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)
+🔗 [LinkedIn Profile](https://www.linkedin.com/in/philiprehberger)
 
 ## License
 

data/lib/philiprehberger/retry_queue/processor.rb

@@ -12,7 +12,10 @@ module Philiprehberger
       # @param backoff [Proc, nil] proc receiving attempt number, returns sleep duration
       # @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)
+      # @param on_failure [Proc, nil] callable invoked with `(item, error)` once per item that
+      #   exhausts retries and moves to the dead-letter list; exceptions raised by the hook are
+      #   swallowed so a faulty hook cannot break the queue
+      def initialize(max_retries: 3, concurrency: 1, backoff: nil, retry_on: nil, on_retry: nil, on_failure: nil)
         raise Error, 'max_retries must be non-negative' unless max_retries.is_a?(Integer) && max_retries >= 0
 
         @max_retries = max_retries
@@ -20,6 +23,7 @@ module Philiprehberger
         @backoff = backoff || DEFAULT_BACKOFF
         @retry_on = retry_on
         @on_retry_hooks = Array(on_retry)
+        @on_failure = on_failure
       end
 
       # Process a collection of items with retry logic.
@@ -54,6 +58,7 @@ module Philiprehberger
         rescue StandardError => e
           if !retryable?(e) || attempts > @max_retries
             failed << { item: item, error: e, attempts: attempts }
+            fire_on_failure_hook(item, e)
             return
           end
 
@@ -74,6 +79,16 @@ module Philiprehberger
         @on_retry_hooks.each { |hook| hook.call(item, error, attempt) }
       end
 
+      def fire_on_failure_hook(item, error)
+        return if @on_failure.nil?
+
+        @on_failure.call(item, error)
+      rescue StandardError
+        # Swallow hook errors — this is a best-effort notification and must never
+        # break the queue. Intentionally silent; users can log inside their hook.
+        nil
+      end
+
       def now
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end

data/lib/philiprehberger/retry_queue/version.rb

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

data/lib/philiprehberger/retry_queue.rb

@@ -16,15 +16,20 @@ module Philiprehberger
     # @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
+    # @param on_failure [Proc, nil] callable invoked with `(item, error)` once per item that
+    #   exhausts retries and moves to the dead-letter list; exceptions raised by the hook are
+    #   swallowed so a faulty hook cannot break the queue
     # @yield [item] block that processes a single item
     # @return [Result] processing result
-    def self.process(items, max_retries: 3, concurrency: 1, backoff: nil, retry_on: nil, on_retry: nil, &block)
+    def self.process(items, max_retries: 3, concurrency: 1, backoff: nil, retry_on: nil, on_retry: nil,
+                     on_failure: nil, &block)
       processor = Processor.new(
         max_retries: max_retries,
         concurrency: concurrency,
         backoff: backoff,
         retry_on: retry_on,
-        on_retry: on_retry
+        on_retry: on_retry,
+        on_failure: on_failure
       )
       processor.call(items, &block)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-retry_queue
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-30 00:00:00.000000000 Z
+date: 2026-04-18 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
@@ -26,11 +26,11 @@ files:
 - lib/philiprehberger/retry_queue/processor.rb
 - lib/philiprehberger/retry_queue/result.rb
 - lib/philiprehberger/retry_queue/version.rb
-homepage: https://github.com/philiprehberger/rb-retry-queue
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-retry_queue
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-retry-queue
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-retry_queue
   source_code_uri: https://github.com/philiprehberger/rb-retry-queue
   changelog_uri: https://github.com/philiprehberger/rb-retry-queue/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/philiprehberger/rb-retry-queue/issues