philiprehberger-retry_queue 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3dce27c1ada757443f23b10abbc62c9530a7495f85fb4616c5002f3d51eb0e6e
+  data.tar.gz: 72374dcd0b0ddb9624098cbf194ac63ab29543e62888eed93d9e6b527d56d5b5
+SHA512:
+  metadata.gz: 8c4a789d3cc288ebd9ddacf23c498edda4914d288fef3f7f9b824d2e24545315d8e512cbe2cdb64b4250882e2295e93328d2d2dfd0ce6814af2c149e64baf4b0
+  data.tar.gz: 6f13bcef9ff0d5d44dbf88fea0f8b36cde68baabe3816b8ccc535889f901e4cad117c10c49d5ee1660d857ab51c6b6a1bfd45c4a20bc4ecfddfda2217653d3ad

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-22
+
+### Added
+- Initial release
+- Batch processing with per-item retry and configurable max retries
+- Exponential backoff with custom backoff strategy support
+- Dead letter collection for items that exhaust retries
+- Result object with succeeded, failed, and stats accessors
+- Timing statistics with elapsed duration and success rate

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+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,90 @@
+# philiprehberger-retry_queue
+
+[![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)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-retry-queue)](LICENSE)
+
+Batch processor with per-item retry, backoff, and dead letter collection
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-retry_queue"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-retry_queue
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/retry_queue"
+
+result = Philiprehberger::RetryQueue.process(items, max_retries: 3) do |item|
+  process_item(item)
+end
+
+puts result.succeeded.size  # => number of successful items
+puts result.failed.size     # => number of failed items
+```
+
+### Custom Backoff
+
+```ruby
+result = Philiprehberger::RetryQueue.process(items, max_retries: 5, backoff: ->(n) { n * 0.5 }) do |item|
+  external_api_call(item)
+end
+```
+
+### Dead Letter Inspection
+
+```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]}"
+end
+```
+
+### Statistics
+
+```ruby
+result = Philiprehberger::RetryQueue.process(records, max_retries: 3) do |record|
+  save(record)
+end
+
+stats = result.stats
+# => { total: 100, succeeded: 97, failed: 3, success_rate: 0.97, elapsed: 1.23 }
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `.process(items, max_retries:, concurrency:, backoff:) { \|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` |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # Run tests
+bundle exec rubocop    # Check code style
+```
+
+## License
+
+MIT

data/lib/philiprehberger/retry_queue/processor.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module RetryQueue
+    # Processes items with per-item retry, backoff, and dead letter collection.
+    class Processor
+      # Default backoff strategy: exponential with base 0.1s.
+      DEFAULT_BACKOFF = ->(attempt) { 0.1 * (2**attempt) }
+
+      # @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)
+        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
+      end
+
+      # Process a collection of items with retry logic.
+      #
+      # @param items [Array] items to process
+      # @yield [item] block that processes a single item; raise to signal failure
+      # @return [Result] processing result with succeeded, failed, and stats
+      def call(items, &block)
+        raise Error, 'a processing block is required' unless block
+
+        succeeded = []
+        failed = []
+        start_time = now
+
+        items.each do |item|
+          process_item(item, succeeded, failed, &block)
+        end
+
+        Result.new(succeeded: succeeded, failed: failed, elapsed: now - start_time)
+      end
+
+      private
+
+      def process_item(item, succeeded, failed, &block)
+        attempts = 0
+
+        loop do
+          attempts += 1
+          block.call(item)
+          succeeded << item
+          return
+        rescue StandardError => e
+          if attempts > @max_retries
+            failed << { item: item, error: e, attempts: attempts }
+            return
+          end
+
+          sleep_duration = @backoff.call(attempts - 1)
+          sleep(sleep_duration) if sleep_duration.positive?
+        end
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/philiprehberger/retry_queue/result.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module RetryQueue
+    # Holds the outcome of a batch processing run.
+    class Result
+      # @return [Array] items that were processed successfully
+      attr_reader :succeeded
+
+      # @return [Array<Hash>] items that exhausted retries, each with :item, :error, :attempts
+      attr_reader :failed
+
+      # @param succeeded [Array] successfully processed items
+      # @param failed [Array<Hash>] items that failed after all retries
+      # @param elapsed [Float] total processing time in seconds
+      def initialize(succeeded:, failed:, elapsed:)
+        @succeeded = succeeded
+        @failed = failed
+        @elapsed = elapsed
+      end
+
+      # Return processing statistics.
+      #
+      # @return [Hash] stats including counts, success rate, and elapsed time
+      def stats
+        total = @succeeded.size + @failed.size
+        {
+          total: total,
+          succeeded: @succeeded.size,
+          failed: @failed.size,
+          success_rate: total.zero? ? 0.0 : @succeeded.size.to_f / total,
+          elapsed: @elapsed
+        }
+      end
+    end
+  end
+end

data/lib/philiprehberger/retry_queue/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module RetryQueue
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/retry_queue.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'retry_queue/version'
+require_relative 'retry_queue/result'
+require_relative 'retry_queue/processor'
+
+module Philiprehberger
+  module RetryQueue
+    class Error < StandardError; end
+
+    # Process items with per-item retry, backoff, and dead letter collection.
+    #
+    # @param items [Array] items to process
+    # @param max_retries [Integer] maximum retry attempts per item
+    # @param concurrency [Integer] number of concurrent workers
+    # @param backoff [Proc, nil] custom backoff strategy
+    # @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)
+      processor.call(items, &block)
+    end
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-retry_queue
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 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
+  results with success/failure counts and timing statistics.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/retry_queue.rb
+- 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
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-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
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Batch processor with per-item retry, backoff, and dead letter collection
+test_files: []